diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index ffe01b928..bab98cfd0 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,51 +1,51 @@ --- read_when: - Розширення qa-lab або qa-channel - - Додавання QA-сценаріїв із підтримкою репозиторію - - Побудова реалістичнішої QA-автоматизації навколо панелі Gateway -summary: Форма приватної QA-автоматизації для qa-lab, qa-channel, початкових сценаріїв і звітів за протоколом -title: QA E2E-автоматизація + - Додавання QA-сценаріїв із прив’язкою до репозиторію + - Створення реалістичнішої QA-автоматизації навколо панелі Gateway +summary: Форма приватної QA-автоматизації для qa-lab, qa-channel, сценаріїв із сидуванням і звітів за протоколом +title: QA E2E автоматизація x-i18n: - generated_at: "2026-04-07T22:41:23Z" + generated_at: "2026-04-08T04:39:35Z" model: gpt-5.4 provider: openai - source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27 + source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# QA E2E-автоматизація +# QA E2E автоматизація Приватний стек QA призначений для того, щоб перевіряти OpenClaw у більш реалістичний, -орієнтований на канали спосіб, ніж це може зробити один модульний тест. +каналоподібний спосіб, ніж це може зробити один модульний тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, channel, thread, - reaction, edit і delete. -- `extensions/qa-lab`: UI для налагодження та шина QA для спостереження за транскриптом, - введення вхідних повідомлень і експорту Markdown-звіту. -- `qa/`: ресурси початкових даних із підтримкою репозиторію для стартового завдання та базових QA +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями для DM, каналів, тредів, + реакцій, редагування та видалення. +- `extensions/qa-lab`: UI для налагодження та QA-шина для спостереження за транскриптом, + ін’єкції вхідних повідомлень і експорту звіту в Markdown. +- `qa/`: ресурси сидування з прив’язкою до репозиторію для стартового завдання та базових QA сценаріїв. -Поточний робочий процес оператора QA — це двопанельний QA-сайт: +Поточний робочий процес QA-оператора — це QA-сайт із двома панелями: - Ліворуч: панель Gateway (Control UI) з агентом. -- Праворуч: QA Lab, що показує схожий на Slack транскрипт і план сценарію. +- Праворуч: QA Lab, який показує Slack-подібний транскрипт і план сценарію. -Запустіть його так: +Запустіть так: ```bash pnpm qa:lab:up ``` -Це збирає QA-сайт, запускає доріжку gateway на базі Docker і відкриває +Це збирає QA-сайт, запускає lane Gateway на базі Docker і відкриває сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, -спостерігати за реальною поведінкою каналу та фіксувати, що спрацювало, що не -спрацювало або що залишилося заблокованим. +спостерігати за реальною поведінкою каналу та фіксувати, що спрацювало, що +не спрацювало або що залишилося заблокованим. -Щоб швидше ітеруватися над UI QA Lab без перебудови Docker-образу щоразу, -запустіть стек із bind-mounted збіркою QA Lab: +Щоб швидше ітерувати UI QA Lab без повторного збирання Docker-образу щоразу, +запустіть стек із QA Lab bundle, змонтованим через bind mount: ```bash pnpm openclaw qa docker-build-image @@ -54,38 +54,39 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` залишає сервіси Docker на попередньо зібраному образі та bind-mount'ить +`qa:lab:up:fast` зберігає Docker-сервіси на попередньо зібраному образі та монтує через bind mount `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перебудовує цей bundle при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсу QA Lab. +перезбирає цей bundle при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсів QA Lab. -## Початкові дані з підтримкою репозиторію +## Ресурси сидування з прив’язкою до репозиторію -Ресурси початкових даних розміщено в `qa/`: +Ресурси сидування розміщено в `qa/`: -- `qa/scenarios.md` +- `qa/scenarios/index.md` +- `qa/scenarios/*.md` Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і агенту. Базовий список має залишатися достатньо широким, щоб охоплювати: -- чат у DM і каналі -- поведінку потоків +- чати в DM і каналах +- поведінку тредів - життєвий цикл дій із повідомленнями - cron-зворотні виклики -- відновлення пам’яті +- виклик пам’яті - перемикання моделей -- передавання підагенту +- передачу підагенту - читання репозиторію та документації -- одне невелике завдання зі збірки, таке як Lobster Invaders +- одне невелике завдання зі збирання, наприклад Lobster Invaders -## Звітність +## Звітування `qa-lab` експортує Markdown-звіт за протоколом на основі спостережуваної часової шкали шини. -Звіт має відповідати на такі запитання: +Звіт має відповідати на запитання: - Що спрацювало - Що не спрацювало - Що залишилося заблокованим -- Які сценарії для подальшої роботи варто додати +- Які сценарії для подальшого опрацювання варто додати ## Пов’язана документація diff --git a/docs/uk/refactor/qa.md b/docs/uk/refactor/qa.md index 1580f6fbd..7306cee1e 100644 --- a/docs/uk/refactor/qa.md +++ b/docs/uk/refactor/qa.md @@ -1,9 +1,9 @@ --- x-i18n: - generated_at: "2026-04-08T02:02:07Z" + generated_at: "2026-04-08T04:40:07Z" model: gpt-5.4 provider: openai - source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8 + source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd source_path: refactor/qa.md workflow: 15 --- @@ -14,52 +14,56 @@ x-i18n: ## Мета -Перевести QA OpenClaw з моделі розділених визначень на єдине джерело істини: +Перевести QA в OpenClaw з моделі з розділеними визначеннями до єдиного джерела істини: - метадані сценаріїв -- промпти, що надсилаються моделі -- налаштування та очищення +- підказки, що надсилаються моделі +- налаштування та завершення - логіка harness - перевірки та критерії успіху - артефакти та підказки для звіту -Бажаний кінцевий стан — універсальний QA harness, який завантажує потужні файли визначень сценаріїв замість жорсткого кодування більшості поведінки в TypeScript. +Бажаний кінцевий стан — це універсальний QA harness, який завантажує потужні файли визначення сценаріїв замість того, щоб жорстко кодувати більшість поведінки в TypeScript. ## Поточний стан -Основне джерело істини тепер знаходиться в `qa/scenarios.md`. +Основне джерело істини тепер розташоване в `qa/scenarios/index.md` плюс по одному файлу для кожного +сценарію в `qa/scenarios/*.md`. Реалізовано: -- `qa/scenarios.md` - - канонічний набір QA +- `qa/scenarios/index.md` + - канонічні метадані QA pack - ідентичність оператора - стартова місія - - метадані сценаріїв - - прив’язки обробників +- `qa/scenarios/*.md` + - один markdown-файл на сценарій + - метадані сценарію + - прив’язки handler + - конфігурація виконання, специфічна для сценарію - `extensions/qa-lab/src/scenario-catalog.ts` - - парсер markdown-пакета + валідація zod + - markdown-парсер pack + валідація zod - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - - рендеринг плану з markdown-пакета + - рендеринг плану з markdown pack - `extensions/qa-lab/src/qa-agent-workspace.ts` - - заповнює згенеровані файли сумісності плюс `QA_SCENARIOS.md` + - створює compatibility-файли плюс `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - - вибирає виконувані сценарії через визначені в markdown прив’язки обробників -- протокол шини QA + UI - - універсальні вбудовані вкладення для рендерингу зображень/відео/аудіо/файлів + - вибирає виконувані сценарії через прив’язки handler, визначені в markdown +- QA bus protocol + UI + - універсальні вбудовані вкладення для рендерингу image/video/audio/file Поверхні, що залишаються розділеними: - `extensions/qa-lab/src/suite.ts` - - досі містить більшість виконуваної логіки спеціальних обробників + - досі містить більшість виконуваної логіки кастомних handler - `extensions/qa-lab/src/report.ts` - - досі виводить структуру звіту з результатів часу виконання + - досі виводить структуру звіту з runtime-результатів -Тож розділення джерела істини усунуто, але виконання все ще переважно спирається на обробники, а не є повністю декларативним. +Тож розділення джерел істини вже виправлено, але виконання все ще переважно спирається на handler, а не є повністю декларативним. -## Як виглядає реальна поверхня сценаріїв +## Як насправді виглядає поверхня сценаріїв -Перегляд поточного suite показує кілька різних класів сценаріїв. +Читання поточного suite показує кілька окремих класів сценаріїв. ### Проста взаємодія @@ -67,15 +71,15 @@ x-i18n: - базовий сценарій DM - подальша взаємодія в треді - перемикання моделі -- проходження після схвалення +- продовження після погодження - реакція/редагування/видалення -### Мутація конфігурації та runtime +### Зміна конфігурації та runtime - вимкнення skill через patch конфігурації - пробудження після перезапуску через застосування конфігурації - перемикання можливостей після перезапуску конфігурації -- перевірка розходження інвентаря runtime +- перевірка дрейфу inventory у runtime ### Перевірки файлової системи та репозиторію @@ -86,47 +90,48 @@ x-i18n: ### Оркестрація пам’яті - відновлення з пам’яті -- інструменти пам’яті в контексті каналу -- резервний сценарій при збої пам’яті +- memory tools у контексті каналу +- fallback при збої пам’яті - ранжування пам’яті сесії -- ізоляція пам’яті треду +- ізоляція пам’яті тредів - sweep мрій пам’яті -### Інтеграція інструментів і плагінів +### Інтеграція tools і plugin -- виклик plugin-tools MCP +- виклик MCP plugin-tools - видимість skill - гаряче встановлення skill -- нативна генерація зображень -- повний цикл зображення +- нативна генерація зображення +- цикл обробки зображення - розуміння зображення з вкладення -### Багатокрокові та багатосуб’єктні сценарії +### Багатокрокові та мультиакторні сценарії -- передача підагенту -- fanout synthesis підагента -- сценарії відновлення після перезапуску +- передача підзадачі субагенту +- fanout synthesis субагента +- потоки у стилі відновлення після перезапуску -Ці категорії важливі, оскільки вони визначають вимоги до DSL. Плоского списку промпт + очікуваний текст недостатньо. +Ці категорії важливі, бо вони визначають вимоги до DSL. Простого списку prompt + очікуваний текст недостатньо. ## Напрямок ### Єдине джерело істини -Використовувати `qa/scenarios.md` як авторське джерело істини. +Використовувати `qa/scenarios/index.md` плюс `qa/scenarios/*.md` як авторське джерело +істини. -Пакет має залишатися: +Pack має залишатися: -- зрозумілим для читання під час рев’ю -- придатним для машинного парсингу -- достатньо насиченим, щоб керувати: +- читабельним для людини під час review +- придатним до машинного парсингу +- достатньо багатим, щоб керувати: - виконанням suite - bootstrap QA workspace - метаданими UI QA Lab - - промптами для docs/discovery + - prompts для docs/discovery - генерацією звітів -### Бажаний формат авторингу +### Бажаний формат авторства Використовувати markdown як формат верхнього рівня зі структурованим YAML усередині. @@ -139,13 +144,13 @@ x-i18n: - tags - docs refs - code refs - - model/provider overrides + - перевизначення model/provider - prerequisites - прозові секції - objective - notes - debugging hints -- fenced YAML-блоки +- fenced YAML blocks - setup - steps - assertions @@ -234,7 +239,7 @@ Verify generated media is reattached on the follow-up turn. ## Можливості runner, які має покривати DSL -На основі поточного suite універсальний runner потребує більшого, ніж просто виконання промптів. +З огляду на поточний suite, універсальному runner потрібне не лише виконання prompt. ### Дії середовища та налаштування @@ -245,14 +250,14 @@ Verify generated media is reattached on the follow-up turn. - `thread.create` - `workspace.writeSkill` -### Дії ходу агента +### Дії під час ходу агента - `agent.send` - `agent.wait` - `bus.injectInbound` - `bus.injectOutbound` -### Дії конфігурації та runtime +### Дії з конфігурацією та runtime - `config.get` - `config.patch` @@ -302,46 +307,46 @@ Verify generated media is reattached on the follow-up turn. ## Змінні та посилання на артефакти -DSL має підтримувати збережені результати та подальші посилання на них. +DSL має підтримувати збережені виходи та подальші посилання на них. Приклади з поточного suite: - створити тред, а потім повторно використати `threadId` - створити сесію, а потім повторно використати `sessionKey` - згенерувати зображення, а потім прикріпити файл на наступному ході -- згенерувати рядок-маркер пробудження, а потім перевірити, що він з’являється пізніше +- згенерувати рядок wake marker, а потім перевірити, що він з’являється пізніше -Необхідні можливості: +Потрібні можливості: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- типізовані посилання для шляхів, ключів сесій, id тредів, маркерів, результатів інструментів +- типізовані посилання для шляхів, ключів сесій, id тредів, marker, виходів tool -Без підтримки змінних harness і надалі буде пропускати логіку сценаріїв назад у TypeScript. +Без підтримки змінних harness і далі виноситиме логіку сценаріїв назад у TypeScript. -## Що має залишитися як escape hatches +## Що має залишитися як escape hatch Повністю чистий декларативний runner нереалістичний на фазі 1. -Деякі сценарії за своєю природою потребують складної оркестрації: +Деякі сценарії за своєю природою вимагають складної оркестрації: - sweep мрій пам’яті - пробудження після перезапуску через застосування конфігурації - перемикання можливостей після перезапуску конфігурації -- визначення артефактів згенерованих зображень за timestamp/шляхом -- оцінка discovery-report +- визначення артефакта згенерованого зображення за timestamp/шляхом +- оцінювання discovery-report -Поки що вони мають використовувати явні спеціальні обробники. +Поки що для них слід використовувати явні custom handlers. Рекомендоване правило: -- 85-90% декларативно +- 85-90% декларативного - явні кроки `customHandler` для складного залишку - лише іменовані та задокументовані custom handlers - жодного анонімного inline-коду у файлі сценарію -Це зберігає чистоту універсального рушія й водночас дає змогу рухатися вперед. +Це зберігає чистоту універсального engine і водночас дозволяє рухатися вперед. ## Архітектурна зміна @@ -352,25 +357,26 @@ Markdown сценаріїв уже є джерелом істини для: - виконання suite - bootstrap-файлів workspace - каталогу сценаріїв UI QA Lab -- метаданих звітів -- промптів discovery +- метаданих звіту +- prompts для discovery Згенерована сумісність: -- workspace із початковими даними все ще містить `QA_KICKOFF_TASK.md` -- workspace із початковими даними все ще містить `QA_SCENARIO_PLAN.md` -- workspace із початковими даними тепер також містить `QA_SCENARIOS.md` +- seeded workspace досі містить `QA_KICKOFF_TASK.md` +- seeded workspace досі містить `QA_SCENARIO_PLAN.md` +- seeded workspace тепер також містить `QA_SCENARIOS.md` ## План рефакторингу ### Фаза 1: loader і schema -Завершено. +Готово. -- додано `qa/scenarios.md` -- додано парсер для вмісту іменованого markdown YAML-пакета -- додано валідацію через zod -- споживачів переведено на розібраний пакет +- додано `qa/scenarios/index.md` +- сценарії розділено на `qa/scenarios/*.md` +- додано парсер для іменованого markdown YAML-вмісту pack +- виконано валідацію через zod +- споживачів переключено на parsed pack - видалено `qa/seed-scenarios.json` і `qa/QA_KICKOFF_TASK.md` на рівні репозиторію ### Фаза 2: універсальний engine @@ -378,16 +384,16 @@ Markdown сценаріїв уже є джерелом істини для: - розділити `extensions/qa-lab/src/suite.ts` на: - loader - engine - - registry дій - - registry перевірок + - action registry + - assertion registry - custom handlers -- зберегти наявні допоміжні функції як операції engine +- зберегти наявні helper-функції як операції engine Результат: - engine виконує прості декларативні сценарії -Почати зі сценаріїв, які переважно складаються з промпту + очікування + перевірки: +Почати зі сценаріїв, які здебільшого складаються з prompt + wait + assert: - подальша взаємодія в треді - розуміння зображення з вкладення @@ -396,40 +402,40 @@ Markdown сценаріїв уже є джерелом істини для: Результат: -- перші справжні сценарії, визначені в markdown, постачаються через універсальний engine +- перші реальні сценарії, визначені в markdown, постачаються через універсальний engine ### Фаза 4: міграція сценаріїв середньої складності -- повний цикл генерації зображення -- інструменти пам’яті в контексті каналу +- цикл обробки генерації зображення +- memory tools у контексті каналу - ранжування пам’яті сесії -- передача підагенту -- fanout synthesis підагента +- передача підзадачі субагенту +- fanout synthesis субагента Результат: -- доведено роботу змінних, артефактів, перевірок інструментів і перевірок журналу запитів +- підтверджено роботу змінних, артефактів, перевірок tool і request-log ### Фаза 5: залишити складні сценарії на custom handlers - sweep мрій пам’яті - пробудження після перезапуску через застосування конфігурації - перемикання можливостей після перезапуску конфігурації -- розходження інвентаря runtime +- дрейф inventory у runtime Результат: -- той самий формат авторингу, але з явними блоками custom-step там, де це потрібно +- той самий формат авторства, але з явними блоками custom-step там, де це потрібно -### Фаза 6: видалити жорстко закодовану мапу сценаріїв +### Фаза 6: видалити hardcoded map сценаріїв -Щойно покриття пакета стане достатньо хорошим: +Коли покриття pack стане достатньо добрим: -- видалити більшість специфічних для сценаріїв розгалужень TypeScript із `extensions/qa-lab/src/suite.ts` +- прибрати більшість специфічних для сценаріїв розгалужень TypeScript із `extensions/qa-lab/src/suite.ts` -## Підтримка fake Slack / rich media +## Підтримка Fake Slack / Rich Media -Поточна шина QA орієнтована насамперед на текст. +Поточний QA bus орієнтований насамперед на текст. Відповідні файли: @@ -439,17 +445,17 @@ Markdown сценаріїв уже є джерелом істини для: - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -Сьогодні шина QA підтримує: +Сьогодні QA bus підтримує: - текст - реакції - треди -Вона ще не моделює вбудовані медіавкладення. +Він ще не моделює вбудовані медіавкладення. ### Потрібний транспортний контракт -Додати універсальну модель вкладень шини QA: +Додати універсальну модель вкладень QA bus: ```ts type QaBusAttachment = { @@ -474,61 +480,61 @@ type QaBusAttachment = { - `QaBusInboundMessageInput` - `QaBusOutboundMessageInput` -### Чому спочатку універсальна модель +### Чому спочатку універсально -Не створювати модель медіа лише для Slack. +Не створюйте модель медіа лише для Slack. Натомість: - одна універсальна транспортна модель QA -- кілька рендерерів поверх неї +- кілька renderer поверх неї - поточний чат QA Lab - майбутній fake Slack web - - будь-які інші представлення fake transport + - будь-які інші fake transport views -Це запобігає дублюванню логіки й дозволяє сценаріям із медіа залишатися незалежними від transport. +Це запобігає дублюванню логіки й дозволяє медіасценаріям залишатися незалежними від транспорту. -### Потрібна робота в UI +### Необхідна робота в UI -Оновити UI QA, щоб він рендерив: +Оновити UI QA для рендерингу: -- вбудований попередній перегляд зображення -- вбудований аудіоплеєр -- вбудований відеоплеєр -- chip вкладеного файла +- вбудованого попереднього перегляду зображення +- вбудованого аудіоплеєра +- вбудованого відеоплеєра +- chip вкладеного файлу -Поточний UI вже може рендерити треди й реакції, тож рендеринг вкладень має нашаровуватися на ту саму модель картки повідомлення. +Поточний UI вже може рендерити треди та реакції, тож рендеринг вкладень має нашаровуватися на ту саму модель картки повідомлення. -### Робота зі сценаріями, яку відкриває транспорт медіа +### Робота зі сценаріями, яку відкриває медіатранспорт -Щойно вкладення почнуть проходити через шину QA, можна буде додати багатші сценарії fake-chat: +Коли вкладення проходитимуть через QA bus, ми зможемо додати багатші сценарії fake-chat: -- відповідь із вбудованим зображенням у fake Slack +- вбудована відповідь із зображенням у fake Slack - розуміння аудіовкладення - розуміння відеовкладення -- змішаний порядок вкладень +- змішане впорядкування вкладень - відповідь у треді зі збереженням медіа ## Рекомендація -Наступний етап реалізації має бути таким: +Наступний блок реалізації має бути таким: 1. додати markdown loader сценаріїв + zod schema 2. згенерувати поточний каталог із markdown 3. спочатку мігрувати кілька простих сценаріїв -4. додати універсальну підтримку вкладень у шині QA -5. рендерити вбудоване зображення в UI QA -6. потім розширити на аудіо та відео +4. додати універсальну підтримку вкладень QA bus +5. реалізувати рендеринг вбудованого зображення в UI QA +6. потім розширити на audio та video -Це найкоротший шлях, який доводить обидві цілі: +Це найменший шлях, який доводить обидві цілі: -- універсальний QA, визначений у markdown -- багатші поверхні fake messaging +- універсальний QA, визначений через markdown +- багатші fake messaging surfaces ## Відкриті питання -- чи мають файли сценаріїв дозволяти вбудовані markdown-шаблони промптів з інтерполяцією змінних -- чи мають setup/cleanup бути іменованими секціями або просто впорядкованими списками дій -- чи мають посилання на артефакти бути строго типізованими в schema або рядковими -- чи мають custom handlers жити в одному registry або в registry для кожної surface -- чи має згенерований JSON-файл сумісності залишатися закоміченим під час міграції +- чи мають файли сценаріїв дозволяти вбудовані markdown-шаблони prompt з інтерполяцією змінних +- чи мають setup/cleanup бути іменованими секціями, чи просто впорядкованими списками дій +- чи мають посилання на артефакти бути строго типізованими в schema, чи базуватися на рядках +- чи мають custom handlers жити в одному registry чи в registry для кожної surface +- чи має згенерований compatibility-файл залишатися закоміченим під час міграції