Files
crank/docs/manual-regression-checklist.md
T
bsodfather e93de7015a
CI / Rust Checks (pull_request) Failing after 1s
CI / UI Checks (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Deploy (pull_request) Skipped
feat(import): complete OpenAPI onboarding and verify delivery
2026-10-09 17:50:38 +03:00

323 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Ручной regression checklist
## 1. Назначение
Этот документ фиксирует post-integration baseline для Community UI, auth, secrets и REST/MCP slices.
Цель:
- дать воспроизводимый regression pass после крупных вертикальных срезов;
- отделить автоматический baseline от ручного smoke на стенде;
- не заставлять следующего агента заново собирать сценарии по всему проекту.
## Этап исполнения
Ручные сценарии этого checklist выполняются в отдельном приёмочном запуске. Для завершения разработки требуются готовые сценарии, fixtures/harness, пороги и шаблоны результатов, а не участие людей или внешние измерения в coding session. Единый [план приёмочного тестирования всех восьми эпиков](acceptance-test-plan.md) задаёт покрытие и порядок запуска. Реальные usability/performance/qualification outcomes остаются `not_run` до исполнения; release gates требуют фактического evidence.
## 2. Автоматический baseline
Локальный regression baseline на `2026-04-07`:
- `cargo check --workspace` -> passed;
- `cd apps/ui && npm run e2e` -> `11 passed`;
- e2e стек поднимает:
- `postgres`;
- `admin-api`;
- `mcp-server`;
- локальный UI proxy.
Покрытые автоматикой сценарии:
- login;
- operations catalog;
- agents;
- api keys;
- logs;
- usage;
- workspace/settings;
- wizard;
- REST draft/test/publish flow.
## 3. Когда запускать этот pass
Запускать обязательно после изменений в:
- auth/session;
- workspace switching;
- operations/wizard;
- agents;
- secrets/auth profiles;
- MCP transport;
- deploy routing/UI routes.
## 4. Обязательные команды перед ручным проходом
```bash
cargo check --workspace
cd apps/ui && npm run e2e
```
Если одна из команд не проходит, ручной regression pass не считается завершенным.
## 5. Ручной smoke checklist
### 5.1. Auth и shell
- открыть `/login`;
- проверить, что страница не зацикливается на redirect;
- проверить invalid login;
- войти bootstrap admin-пользователем;
- убедиться, что после входа открывается `/`;
- проверить logout;
- войти повторно;
- проверить header identity;
- проверить language switch;
- проверить workspace switch в navbar.
### 5.2. Operations
- открыть `/`;
- убедиться, что demo operations загружены;
- проверить search;
- проверить protocol/category/agent filters;
- открыть edit существующей operation;
- убедиться, что delete доступен только never-published Draft, а Published предлагает archive с подтверждением;
- открыть одну Operation в двух вкладках, сохранить обе и проверить, что вторая получает localized stale recovery без потери local edits;
- проверить success/error toasts;
- проверить clean routes без `/html/...`.
### 5.3. Wizard
- открыть `/wizard/`;
- убедиться, что доступна только `REST` protocol card;
- для нового upstream проверить режимы auth:
- `No auth`
- `Use existing auth profile`
- `Create auth profile now`
- создать quick secret из wizard;
- создать quick auth profile из wizard;
- сохранить upstream;
- убедиться, что `execution_config.auth_profile_ref` попадает в draft/test flow;
- проверить sample upload;
- проверить YAML export/import;
- проверить `Test run`;
- проверить, что Test run показывает безопасные Request ID и Trace ID с copy controls;
- проверить `Publish`, затем edit: Published vN остаётся неизменной, новая правка становится Draft vN+1;
- экспортировать Published vN как YAML v2, выполнить semantic no-op и changed upsert; previous Published Version не должна меняться;
- архивировать Operation и проверить, что существующий published Agent по-прежнему list/call pinned vN, а новая binding отклоняется.
### 5.4. Agents
- открыть `/agents`;
- проверить cards и lifecycle badges;
- открыть drawer;
- проверить bindings;
- создать или обновить agent;
- проверить publish/unpublish/archive flow;
- проверить copy MCP endpoint.
### 5.5. API Keys
- открыть `/api-keys`;
- создать MCP client key;
- убедиться, что raw key показывается один раз;
- проверить copy;
- закрыть reveal modal и убедиться, что raw key очищен из интерфейса;
- проверить revoke и убедиться, что существующая MCP session теряет доступ без restart;
- проверить delete revoked key: metadata остаётся со статусом `deleted`, raw/hash не отображаются;
- создать approval key с `allowed_origins`;
- проверить, что approval запрос с чужим `Origin` отклоняется.
- создать Operation с human approval, вызвать Tool дважды с одинаковыми
аргументами и разными control-token: должна остаться одна pending заявка;
- убедиться, что pending approval summary показывает Agent/Operation Version,
expiry и безопасные параметры без raw token/secret;
- подтвердить заявку и повторить approve: второй запрос должен вернуть terminal
status без повторного upstream side effect.
- проверить `last_used_at` после реального machine-auth вызова при необходимости.
### 5.6. Secrets
- открыть `/secrets`;
- проверить list/create/rotate/delete;
- создать:
- `token`;
- `username_password`;
- `header`;
- `generic`;
- убедиться, что plaintext не возвращается после create/rotate;
- проверить usage references через auth profiles;
- проверить, что удаление Secret, используемого Auth Profile, возвращает `409 secret_referenced_by_auth_profile`;
- проверить, что rotation Secret меняет credential для следующего Wizard Test run без изменения Auth Profile/Operation refs;
- проверить audit/log evidence: нет plaintext, ciphertext, hash или raw key;
- проверить, что wizard quick-create синхронизируется с этой страницей.
### 5.7. Logs и Usage
- открыть `/logs`;
- проверить loading/error/empty states;
- проверить фильтры period, explicit UTC window, status, outcome group, level/search и кнопку Load more;
- открыть detail expansion и убедиться, что видны Request ID, Trace ID и точная Operation Version, но нет raw секретов;
- экспортировать CSV из Logs и проверить, что выбранные фильтры применились без page-limit обрезки;
- открыть `/usage`;
- проверить summary cards;
- проверить timeline chart;
- проверить outcome groups `success`, `upstream`, `client`, `schema`, `crank`;
- проверить server-side CSV export из `/usage/export.csv`, а не client-side snapshot браузера.
### 5.8. Workspace и Settings
- открыть `/workspace-setup`;
- проверить редактирование имени, slug, описания и цвета единственного workspace;
- проверить, что интерфейса приглашений, ролей и управления пользователями нет;
- проверить export workspace;
- проверить, что delete workspace не отображается;
- открыть `/settings`;
- проверить profile update;
- проверить password change.
### 5.9. Getting Started: протокол usability для пяти участников
Этот протокол является планом сбора ручного evidence, а не заявлением о
пройденном исследовании. Выполнять его на пяти независимых участниках с fresh
self-hosted installation и отдельным новым Admin account для каждого прогона.
Участнику нельзя помогать документацией, исходным кодом, поиском по репозиторию
или подсказками оператора; разрешён только сам продукт и нормальное MCP client
окружение.
Для каждого участника:
- запустить таймер с первого authenticated рендера protected Admin UI;
- использовать Getting Started, создать manual REST Operation, выполнить test,
publish, создать/publish Agent и один MCP client key;
- сохранить key только через one-time reveal <!-- community-scope: allow=one-time-token -->, выполнить публичные
`initialize`, `notifications/initialized`, `tools/list`, `tools/call` по
canonical endpoint;
- остановить таймер после server-authoritative `first_call` с Agent/key/Tool,
Request ID и Trace ID в snapshot/Invocation History;
- проверить, что refresh/resume не раскрывает raw key, а revoke предлагает
deliberate recovery без автоматического создания дубликата;
- зафиксировать завершение, duration, все recovery/error states и факт
eligibility отдельно от completion. Не записывать bearer, payload, URL
частного контура или скриншоты с секретами.
Цель — median времени от первого authenticated render до authoritative first
call не более 15 минут. Незавершивший участник цензурируется на 30-й минуте, но
остаётся в conversion denominator; eligibility denominator и completion
numerator публикуются раздельно. До фактического пятиучастникового запуска
результат этого протокола остаётся `not_run`, а не `pass`.
### 5.10. Getting Started: ветка готового OpenAPI для пяти участников
Этот отдельный сценарий проверяет ветку готовой спецификации по Story 2.15.
Он дополняет сценарий 5.9 и не заменяет его: manual REST и OpenAPI результаты
записываются отдельно. До запуска подготовьте доступную тестовую REST-службу с
безопасными синтетическими данными и OpenAPI-файл, соответствующий текущим
ограничениям импорта. Все его actionable методы должны иметь проверяемый
результат; если требуется аутентификация, заранее настройте совместимый
workspace Auth Profile с тестовым Secret. Не используйте production credentials
или данные. Не включайте значения Secret в файл спецификации.
Проведите пять независимых прогонов на свежих self-hosted установках и новых
Admin accounts. Участникам разрешены только продукт, подготовленный файл и
обычное MCP client окружение. До каждого прогона оператор проверяет доступность
тестовой службы, файла и MCP client, но не показывает участнику дальнейшие шаги.
Назначьте язык интерфейса до начала таймера (как минимум один прогон на русском
и один на английском); не переключайте язык во время прогона. Каждый участник
сам выполняет действия:
1. Откройте **Getting Started**, выберите путь OpenAPI, загрузите подготовленный
файл и запустите preview.
2. Осмотрите методы, findings, security requirements и предлагаемые Operations.
Убедитесь, что blocker и unsupported findings видны. Выберите подходящую
policy; для защищённого метода используйте совместимый Auth Profile, то
есть только ссылку на Secret.
3. Проверьте точный план и последствия для конфликтующих Operations, подтвердите
Apply и осмотрите полный report. Если импорт создал несколько Drafts, явно
выберите одну actionable Draft для продолжения. Убедитесь, что публикация не
произошла автоматически.
4. Обновите страницу и возобновите onboarding. Сверьте выбранную Draft и report;
убедитесь, что повторное открытие или продолжение не создало новую версию.
При surfaced stale/error recovery следуйте UI: перечитайте актуальные данные,
создайте новый preview/plan при изменившемся digest и подтвердите его заново.
Запишите фактически увиденную ошибку и восстановление; не имитируйте успешный
recovery, если его не удалось пройти.
5. Через обычный Operation wizard проверьте Draft, выполните test и явно
опубликуйте Operation. Создайте Agent с этой опубликованной версией,
опубликуйте Agent, выпустите MCP client key через one-time reveal <!-- community-scope: allow=one-time-token -->, затем
выполните публичные `initialize`, `notifications/initialized`, `tools/list`
и `tools/call` по показанному MCP endpoint.
6. Завершите прогон только после подтверждения first call в authoritative
checklist или Invocation History с Agent, key, Tool, Request ID и Trace ID.
В процессе также проверьте refresh/resume после test, publication и создания
key; raw key не должен повторно раскрываться.
Запустите таймер при первом authenticated рендере protected Admin UI и
остановите при authoritative first call. В таблице фиксируйте только
обезличенный label участника (`P1`–`P5`), eligibility, язык, завершение,
длительность, наблюдённые recovery states и краткий безопасный результат. Не
записывайте имя, email, account/workspace IDs, credentials, raw key, payload,
исходную спецификацию, endpoint/private URL, Request ID, Trace ID или скриншоты.
Для незавершённого eligible прогона укажите `30 min (censored)` независимо от
момента остановки; он остаётся в denominator. Рассчитайте median по пяти
eligible значениям времени с этим 30-минутным пределом; completion numerator
публикуйте отдельно от eligibility denominator. Цель usability — median не
более 15 минут. Не записывайте протокол как `pass`, если не выполнены все пять
прогонов и цель не достигнута.
Перед запуском заполните идентификатор чистой ревизии и безопасные сведения о
среде. Запись ревизии допускается только для чистой checkout без незакоммиченных
изменений; фиксируйте фактически запущенный commit. Шаблон остаётся `not_run`,
пока реальные значения не внесены после проведения исследования:
| Поле | Значение |
|---|---|
| Статус | `not_run` |
| Чистая ревизия приложения | `<commit SHA>` |
| Среда | `<self-hosted версия/тип установки; браузер и ОС без hostnames>` |
| Eligible участников | `0 / 5` |
| Завершившие до 30 min | `0 / 5` |
| Длительности P1–P5 | `<not_run>` |
| Median (censored, max 30 min) | `<not_run>` |
| Recovery после refresh/stale/error | `<not_run>` |
| Итог и ограничения | `<not_run>` |
| Участник | Eligible | Язык | Завершил | Время (max 30 min) | Refresh/recovery и результат |
|---|---|---|---|---|---|
| P1 | `<not_run>` | `<ru/en>` | `<not_run>` | `<not_run>` | `<not_run>` |
| P2 | `<not_run>` | `<ru/en>` | `<not_run>` | `<not_run>` | `<not_run>` |
| P3 | `<not_run>` | `<ru/en>` | `<not_run>` | `<not_run>` | `<not_run>` |
| P4 | `<not_run>` | `<ru/en>` | `<not_run>` | `<not_run>` | `<not_run>` |
| P5 | `<not_run>` | `<ru/en>` | `<not_run>` | `<not_run>` | `<not_run>` |
Отсутствующий участник не считается нулём: публикуйте eligibility denominator и
completion numerator раздельно. Не подменяйте этот human run результатом
автоматического теста или документации.
## 6. Protocol smoke pass
Для smoke-проверки MCP использовать готовый public target из [public-smoke-targets.md](public-smoke-targets.md).
Обязательный кейс:
- REST: [Frankfurter examples](../examples/frankfurter/README.md)
## 7. Acceptance criteria
Regression pass считается завершенным, если одновременно выполнены условия:
- `cargo check --workspace` passed;
- Playwright suite passed;
- login/shell/manual navigation не ломаются;
- `Secrets -> Auth Profiles -> Wizard -> Test run` связка работает;
- public REST smoke target проходит;
- нет критичных UI regressions на clean routes, i18n и auth redirects.
## 8. Если что-то падает
- сначала фиксировать failing automated spec;
- потом чинить ручной smoke regression;
- после фикса повторять:
- `cargo check --workspace`;
- `cd apps/ui && npm run e2e`;
- только потом фиксировать результат в текущем рабочем трекере.