docs: record use cases without test coverage
Python package / build (3.12.3) (pull_request) Successful in 2m44s
Python package / build (3.13) (pull_request) Successful in 2m41s
Python package / build (3.14) (pull_request) Successful in 2m36s

This commit is contained in:
2026-10-05 17:58:53 +00:00
parent c3e81b75c8
commit ab50d5dbee
+345
View File
@@ -0,0 +1,345 @@
# Сценарии, не покрытые тестами
## Цель документа
Этот документ фиксирует сценарии из требований Brencher, для которых в текущем репозитории нет автоматического теста или есть только частичное покрытие. Проверка выполнена по файлам `tests/test_*.py`, тестовой документации и исходникам backend/frontend.
Ссылки `[B-*]` и `[U-*]` ведут на требования в документах:
- [Backend use cases](USE_CASES_BACKEND.md)
- [UI use cases](USE_CASES_UI.md)
- [AGENTS.md](../AGENTS.md) — требования к self-driving/autodeploy-конфигурации
- [tests/README.md](../tests/README.md) — заявленная область существующих integration tests
## Границы текущего покрытия
Покрыты или частично покрыты существующими тестами:
- Git clone, named remotes, validation и восстановление повреждённого local config — `tests/test_git_integration.py`;
- checkout/merge одной, двух и трёх веток, fast-forward, merge conflict и auto branch — `tests/test_git_integration.py`;
- GitUnmerge для valid/invalid version и non-HEAD commit — `tests/test_git_integration.py`;
- stale token на уровне shared state — `tests/test_cached_env.py`, `tests/test_processing_initial_branches.py`;
- apply через UI и повторное появление apply при конфликте — `tests/test_apply_changes.py`;
- dry run и переход к deploy после его выключения — `tests/test_dry_run_playwright.py`;
- отображение deployed column после apply/deploy — `tests/test_deploy_column_playwright.py`;
- кэширование pipeline step — `tests/test_caching_step.py`.
Эти тесты не покрывают весь пользовательский сценарий целиком: например, проверка `GET /state` на HTTP 200 не проверяет все поля ответа, а локальный container test не является тестом Docker Swarm rollout.
## Непокрытые backend-сценарии
### NB-01. Получение главной страницы и static resource
**Требование:** [B-03](USE_CASES_BACKEND.md#b-03-получить-веб-приложение--get) и [B-04](USE_CASES_BACKEND.md#b-04-получить-статический-ресурс-или-неизвестный-путь).
Нет теста, который проверяет:
- `GET /` и наличие `index.html`;
- загрузку `app.js` и `styles.css`;
- ошибку неизвестного static path;
- поведение при недоступном/повреждённом статическом ресурсе.
Связанные исходники: [`backend/web.py`](../backend/web.py), [`frontend/index.html`](../frontend/index.html).
### NB-02. Полный контракт REST `GET /state`
**Требование:** [B-01](USE_CASES_BACKEND.md#b-01-получить-состояние-окружений--get-state).
Существующие тесты проверяют в основном HTTP 200 и отдельные поля. Нет contract-теста на:
- `version`;
- `branches_token`;
- `dry`;
- desired branches/commits;
- deployed columns;
- Jobs и pipeline statuses;
- пустое/начальное состояние;
- ошибку отдельного окружения без падения всего ответа.
Связанные тесты: [`test_deploy_column_playwright.py`](../tests/test_deploy_column_playwright.py), [`test_apply_changes.py`](../tests/test_apply_changes.py).
### NB-03. Полный контракт REST `GET /branches`
**Требование:** [B-02](USE_CASES_BACKEND.md#b-02-получить-доступные-ветки--get-branches).
Нет отдельного REST contract-теста на:
- структуру `{environment: {branch: commits}}`;
- commit objects и их поля;
- несколько remotes и remote-префиксы в HTTP-ответе;
- изменение результата после fetch;
- ошибку Git/fetch.
Связанный код: [`backend/web.py`](../backend/web.py), [`backend/steps/git.py`](../backend/steps/git.py).
### NB-04. WebSocket initial state, malformed messages и unknown environment
**Требования:** [B-05](USE_CASES_BACKEND.md#b-05-открыть-ws-и-получить-начальное-состояние) и [B-06](USE_CASES_BACKEND.md#b-06-передать-обновление-выбранного-окружения).
Playwright-тесты используют WebSocket косвенно, но нет backend-теста на:
- точный порядок/состав initial `version` → `branches` → `environments`;
- несколько клиентов и независимое состояние deduplication;
- malformed JSON;
- неизвестное имя окружения;
- disconnect cleanup;
- ошибку отправки broadcast одному клиенту.
Связанный код: [`backend/web.py`](../backend/web.py).
### NB-05. Git credentials и ошибки внешнего Git
**Требование:** [B-08](USE_CASES_BACKEND.md#b-08-обновить-git-состояние).
Git integration tests работают с локальными repositories и не проверяют:
- authentication failure GitHub/Gitea;
- отсутствие или неправильные `GIT_USERNAME`/`GIT_PASSWORD`;
- network timeout и недоступный remote;
- поведение pipeline после failed fetch;
- сохранение корректного состояния после частично успешного fetch нескольких remotes.
Связанные исходники: [`backend/steps/git.py`](../backend/steps/git.py), [`README.instruction.md`](../README.instruction.md).
### NB-06. Выбор исторического и произвольного commit через backend
**Требование:** [B-07](USE_CASES_BACKEND.md#b-07-запустить-применение-или-dry-run) и [B-09](USE_CASES_BACKEND.md#b-09-разрешить-выбранный-commit).
Тесты проверяют branch/`HEAD` и внутренний Git commit resolution, но нет API/UI integration-теста на:
- исторический commit из branch history;
- произвольный полный или короткий SHA;
- неизвестный ref;
- commit, недоступный в выбранном remote;
- различение одинакового имени branch в разных remotes.
Связанные тесты: [`test_git_integration.py`](../tests/test_git_integration.py), [`docs/USE_CASES_UI.md`](USE_CASES_UI.md).
### NB-07. Swarm state inspection
**Требование:** [B-11](USE_CASES_BACKEND.md#b-11-проверить-deployed-состояние-swarm).
Текущие Playwright-тесты используют обычный Docker container. Нет теста на Docker Swarm API/socket, который проверяет:
- чтение `org.brencher.version` label;
- stack/service image;
- desired и running replicas;
- unavailable stack/service;
- недоступный Docker socket;
- несовпадение deployed version.
Связанный код: [`backend/steps/docker.py`](../backend/steps/docker.py), [`backend/steps/shared_state.py`](../backend/steps/shared_state.py).
### NB-08. Actions workflow, registry и deploy после workflow
**Требования:** [B-12](USE_CASES_BACKEND.md#b-12-запустить-сборку-и-публикацию-образа) и [B-13](USE_CASES_BACKEND.md#b-13-выполнить-deploy).
Нет теста на configuration-dependent Actions flow:
- dispatch Gitea Actions workflow;
- ожидание завершения workflow;
- failed/cancelled workflow;
- credentials registry;
- pull уже опубликованного image на Swarm node;
- `docker stack deploy` и проверку replicas/version после deploy;
- отсутствие локального build/push при `buildDocker=None`.
Требование self-driving pipeline и порядок шагов описаны в [`AGENTS.md`](../AGENTS.md#build-delegation-pattern-actions). Связанные исходники: [`backend/steps/actions.py`](../backend/steps/actions.py), [`backend/steps/docker.py`](../backend/steps/docker.py).
### NB-09. Автоматический drift/autodeploy без UI-команды
**Требование:** [B-14](USE_CASES_BACKEND.md#b-14-автоматически-обнаружить-drift).
GitUnmerge тестируется изолированно, но нет end-to-end теста, который:
1. запускает backend с deployed Swarm label;
2. меняет remote HEAD;
3. ждёт polling cycle;
4. проверяет автоматический pipeline без `environment_update` из UI;
5. проверяет новый image/version и replicas.
Это прямо требуется checklist-ом [`AGENTS.md`](../AGENTS.md#verification-checklist): push branch, дождаться polling cycle и подтвердить redeploy без UI update.
### NB-10. Health check
**Требование:** [B-15](USE_CASES_BACKEND.md#b-15-проверить-url-health-check).
Нет теста на `UrlCheck`/HTTP health-check flow:
- HTTP 200 с ожидаемым JSON;
- неправильный status code;
- невалидный JSON;
- рекурсивное несовпадение expected fields;
- timeout и недоступный service;
- влияние failed health check на pipeline/deploy status.
Связанный код: backend-конфигурации с `UrlCheck` и соответствующий pipeline step.
### NB-11. Secondary Brencher
**Требование:** [B-16](USE_CASES_BACKEND.md#b-16-синхронизировать-secondary-brencher).
Нет теста на `SECONDARY_BRENCHER`:
- подключение к remote `/ws`;
- forwarding update;
- объединение branches/environments;
- duplicate environment ID;
- reconnect и backoff;
- исчерпание retry attempts.
Связанный код: [`backend/secondary.py`](../backend/secondary.py).
### NB-12. Startup modes, profiles и restart recovery
**Требование:** [B-17](USE_CASES_BACKEND.md#b-17-запустить-разные-режимы).
Нет теста на:
- `PROFILES` с несколькими профилями;
- исключение профиля через `-profile`;
- `noweb` headless mode;
- глобальный `dry` startup mode;
- custom port/configuration;
- восстановление state после backend restart;
- отличие локального `brencher2` profile от `SECONDARY_BRENCHER`.
Связанный код: [`backend/app.py`](../backend/app.py), [`backend/discover_envs.py`](../backend/discover_envs.py).
### NB-13. Multi-client concurrency
**Требование:** [B-18](USE_CASES_BACKEND.md#b-18-обработать-несколько-клиентов).
Нет теста на два или более одновременно подключённых клиента:
- broadcast одного update всем клиентам;
- dedup одинакового payload для каждого клиента;
- disconnect одного клиента без влияния на остальные;
- параллельные updates разных окружений;
- race при одновременном изменении одного окружения.
Связанный код: [`backend/web.py`](../backend/web.py).
### NB-14. Security boundary
**Требование:** [B-19](USE_CASES_BACKEND.md#b-19-зафиксировать-границу-доступа).
Нет security integration-теста, который проверяет явно заявленную границу:
- REST endpoints доступны без встроенной auth/authz;
- WebSocket также не требует application-level credentials;
- внешний reverse proxy может ограничить доступ;
- неизвестный/неавторизованный клиент не получает ложный `401` от самого backend.
Связанный код: [`backend/web.py`](../backend/web.py), [`README.instruction.md`](../README.instruction.md).
## Непокрытые UI-сценарии
### NU-01. WebSocket reconnect и отсутствие socket leak
**Требование:** [U-03](USE_CASES_UI.md#u-03-переподключиться-после-разрыва-websocket).
Нет Playwright-теста, который принудительно закрывает socket и проверяет:
- reconnect;
- повторную загрузку initial state;
- отсутствие нескольких параллельных WebSocket instances;
- корректное закрытие старого socket;
- отображение reconnect/disconnected state.
Связанные исходники: [`frontend/app.js`](../frontend/app.js), [`backend/web.py`](../backend/web.py).
### NU-02. Фильтрация окружений
**Требование:** [U-06](USE_CASES_UI.md#u-06-отфильтровать-окружения).
Нет UI-теста на ввод фильтра, отсутствие совпадений, очистку фильтра и то, что фильтр не изменяет backend state.
Связанный исходник: [`frontend/app.js`](../frontend/app.js).
### NU-03. История и произвольный commit в UI
**Требования:** [U-10](USE_CASES_UI.md#u-10-выбрать-исторический-commit) и [U-11](USE_CASES_UI.md#u-11-ввести-произвольный-commit).
Существующие Playwright-тесты выбирают branch/commit из ограниченного сценария, но нет теста на:
- открытие полной commit history;
- исторический commit;
- ручной SHA/ref;
- невалидный commit;
- возврат selection к `HEAD`.
Связанные файлы: [`frontend/app.js`](../frontend/app.js), [`frontend/index.html`](../frontend/index.html).
### NU-04. Merge нескольких branches через UI
**Требование:** [U-13](USE_CASES_UI.md#u-13-объединить-несколько-branches).
Внутренние Git integration tests проверяют merge, но нет Playwright-теста на выбор нескольких branches, отображение selection и показ merge conflict в Jobs/error panel.
Связанные тесты/исходники: [`test_git_integration.py`](../tests/test_git_integration.py), [`frontend/app.js`](../frontend/app.js).
### NU-05. Jobs, pipeline progress и error rendering
**Требование:** [U-15](USE_CASES_UI.md#u-15-наблюдать-jobs-и-pipeline) и [U-18](USE_CASES_UI.md#u-18-увидеть-ошибку-gitcredentialsregistrydockerhealth-check).
Тесты проверяют отдельные конечные состояния, но нет полного UI-теста на:
- все pipeline steps в правильном порядке;
- running → success;
- running → failed;
- текст ошибки и failed step;
- повторный запуск после внешней ошибки;
- registry/Docker/health-check error display.
Связанный исходник: [`frontend/app.js`](../frontend/app.js).
### NU-06. User links
**Требование:** [U-16](USE_CASES_UI.md#u-16-просмотреть-ссылки-сервиса).
Нет теста на получение `userLinks`, наличие ссылок в UI, корректный href и отсутствие выдуманной ссылки при пустом `userLinks`.
Связанные исходники: [`frontend/app.js`](../frontend/app.js), [`frontend/index.html`](../frontend/index.html).
### NU-07. Automatic update reflected in UI
**Требование:** [U-17](USE_CASES_UI.md#u-17-увидеть-автоматический-deploy-без-действия-в-ui).
Нет end-to-end теста, который меняет remote HEAD без UI Update и проверяет отображение нового desired/deployed state и pipeline progress.
Связанный requirement checklist: [`AGENTS.md`](../AGENTS.md#verification-checklist).
### NU-08. Secondary state in UI
**Требование:** [U-20](USE_CASES_UI.md#u-20-работать-с-secondary-brencher).
Нет UI-теста на объединённое состояние local/secondary, duplicate environment conflict, secondary disconnect и отображение reconnect result.
Связанные файлы: [`backend/secondary.py`](../backend/secondary.py), [`frontend/app.js`](../frontend/app.js).
### NU-09. Direct REST diagnostics in UI/browser
**Требование:** [U-21](USE_CASES_UI.md#u-21-просмотреть-состояние-через-прямой-rest-url).
Тесты используют `/state` и `/branches` как вспомогательные API, но нет самостоятельного диагностики-теста, который проверяет:
- открытие endpoint в браузере;
- JSON content type;
- стабильную структуру ответа;
- read-only характер endpoint;
- ошибку недоступного окружения в JSON.
Связанные тесты: [`test_deploy_column_playwright.py`](../tests/test_deploy_column_playwright.py), [`test_containertest.py`](../tests/test_containertest.py).
## Итог
Наиболее критичные пробелы для приоритетного добавления тестов:
1. autodeploy/drift без UI-команды — [B-14](USE_CASES_BACKEND.md#b-14-автоматически-обнаружить-drift), [U-17](USE_CASES_UI.md#u-17-увидеть-автоматический-deploy-без-действия-в-ui);
2. Docker Swarm inspect/deploy и Actions workflow — [B-11](USE_CASES_BACKEND.md#b-11-проверить-deployed-состояние-swarm), [B-12](USE_CASES_BACKEND.md#b-12-запустить-сборку-и-публикацию-образа), [B-13](USE_CASES_BACKEND.md#b-13-выполнить-deploy);
3. WebSocket initial state/reconnect, multi-client и socket leak — [B-05](USE_CASES_BACKEND.md#b-05-открыть-ws-и-получить-начальное-состояние), [B-18](USE_CASES_BACKEND.md#b-18-обработать-несколько-клиентов), [U-03](USE_CASES_UI.md#u-03-переподключиться-после-разрыва-websocket);
4. secondary Brencher — [B-16](USE_CASES_BACKEND.md#b-16-синхронизировать-secondary-brencher), [U-20](USE_CASES_UI.md#u-20-работать-с-secondary-brencher);
5. REST contracts, errors и security boundary — [B-01](USE_CASES_BACKEND.md#b-01-получить-состояние-окружений--get-state), [B-02](USE_CASES_BACKEND.md#b-02-получить-доступные-ветки--get-branches), [B-19](USE_CASES_BACKEND.md#b-19-зафиксировать-границу-доступа).
Отдельное ограничение: `test_containertest.py::test_start` помечен `skip`, поэтому его проверки startup/API не входят в фактически исполняемое покрытие.