@openclaw/matrix проти одноразового домашнього сервера Tuwunel у Docker, із тимчасовими обліковими записами driver, SUT і observer та попередньо створеними кімнатами. Це покриття Matrix із реальним транспортом наживо.
Це інструментарій лише для мейнтейнерів. Пакетовані релізи OpenClaw навмисно не містять qa-lab, тому openclaw qa доступна лише з вихідного checkout. Вихідні checkout завантажують вбудований runner напряму - крок встановлення Plugin не потрібен.
Ширший контекст фреймворку QA див. в огляді QA.
Швидкий старт
pnpm openclaw qa matrix запускає --profile all і не зупиняється після першої помилки. Використовуйте --profile fast --fail-fast для релізного gate; розбийте каталог на шарди за допомогою --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli, коли запускаєте повний інвентар паралельно.
Що робить лінія
- Створює одноразовий домашній сервер Tuwunel у Docker (типовий образ
ghcr.io/matrix-construct/tuwunel:v1.5.1, ім’я сервераmatrix-qa.test, порт28008) за обмеженим засобом запису запитів/відповідей із редагуванням чутливих даних. - Реєструє трьох тимчасових користувачів -
driver(надсилає вхідний трафік),sut(обліковий запис OpenClaw Matrix, що тестується),observer(захоплення стороннього трафіку). - Заповнює кімнати, потрібні для вибраних сценаріїв (main, threading, media, restart, secondary, allowlist, E2EE, verification DM тощо).
- Запускає substrate-neutral пробу протоколу
matrix-qa-v1проти записаної межі Tuwunel. Модульні тести доводять контракт проби з фікстурою протоколу Matrix; канонічний хост адаптера транспорту QA у #99707 володіє реальним підключенням цілі Crabline. - Запускає дочірній OpenClaw Gateway із реальним Plugin Matrix, обмеженим обліковим записом SUT;
qa-channelу дочірній процес не завантажується. - Послідовно запускає сценарії, спостерігаючи події через клієнти Matrix driver/observer і виводячи очікування маршруту/стану із записаного трафіку.
- Зупиняє домашній сервер, записує звіт і артефакти доказів, а потім завершує роботу.
CLI
Поширені прапорці
| Прапорець | Типове значення | Опис |
|---|---|---|
--profile <profile> | all | Профіль сценаріїв. Див. Профілі. |
--fail-fast | вимкнено | Зупинитися після першої невдалої перевірки або сценарію. |
--scenario <id> | - | Запустити лише цей сценарій. Можна повторювати. Див. Сценарії. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Куди записуються звіти, зведення, інвентар маршрутів/станів, спостережені події та вихідний журнал. Відносні шляхи розв’язуються відносно --repo-root. |
--repo-root <path> | process.cwd() | Корінь репозиторію під час виклику з нейтрального робочого каталогу. |
--sut-account <id> | sut | Ідентифікатор облікового запису Matrix у конфігурації QA Gateway. |
Прапорці провайдера
Лінія використовує реальний транспорт Matrix, але провайдер моделі налаштовується:| Прапорець | Типове значення | Опис |
|---|---|---|
--provider-mode <mode> | live-frontier | mock-openai для детермінованої mock-диспетчеризації або live-frontier для живих frontier-провайдерів. Застарілий псевдонім live-openai усе ще працює. |
--model <ref> | типове значення провайдера | Основний ref provider/model. |
--alt-model <ref> | типове значення провайдера | Альтернативний ref provider/model, коли сценарії перемикаються посеред запуску. |
--fast | вимкнено | Увімкнути швидкий режим провайдера там, де він підтримується. |
--credential-source або --credential-role. Лінія локально створює одноразових користувачів; спільного пулу облікових даних для оренди немає.
Профілі
Вибраний профіль визначає, які сценарії запускаються.| Профіль | Для чого використовувати |
|---|---|
all (типово) | Повний каталог. Повільний, але вичерпний. |
fast | Підмножина для релізного gate, яка перевіряє контракт живого транспорту: canary, mention gating, блок allowlist, форму відповіді, відновлення після restart, thread follow-up, ізоляцію thread, спостереження reaction і доставку metadata exec approval. |
transport | Сценарії threading, DM, кімнат, autojoin, mention/allowlist, approval і reaction на рівні транспорту. |
media | Покриття вкладень image, audio, video, PDF, EPUB. |
e2ee-smoke | Мінімальне покриття E2EE - базова зашифрована відповідь, thread follow-up, успішний bootstrap. |
e2ee-deep | Вичерпні сценарії E2EE для state-loss, backup, key і recovery. |
e2ee-cli | Сценарії CLI openclaw matrix encryption setup і verify *, що виконуються через QA harness. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Сценарії
Повний список ідентифікаторів сценаріїв - це unionMatrixQaScenarioId у extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. Категорії включають:
- threading -
matrix-thread-*,matrix-subagent-thread-spawn - top-level / DM / room -
matrix-top-level-reply-shape,matrix-room-*,matrix-dm-* - streaming і перебіг інструментів -
matrix-room-partial-streaming-preview,matrix-room-quiet-streaming-preview,matrix-room-tool-progress-*,matrix-room-block-streaming - media -
matrix-media-type-coverage,matrix-room-image-understanding-attachment,matrix-attachment-only-ignored,matrix-unsupported-media-safe - routing -
matrix-room-autojoin-invite,matrix-secondary-room-* - reactions -
matrix-reaction-* - approvals -
matrix-approval-*(metadata exec/plugin, chunked fallback, deny reactions, threads і routingtarget: "both") - restart і replay -
matrix-restart-*,matrix-stale-sync-replay-dedupe,matrix-room-membership-loss,matrix-homeserver-restart-resume,matrix-initial-catchup-then-incremental - mention gating, bot-to-bot і allowlists -
matrix-mention-*,matrix-allowbots-*,matrix-allowlist-*,matrix-multi-actor-ordering,matrix-inbound-edit-*,matrix-mxid-prefixed-command-block,matrix-observer-allowlist-override - E2EE -
matrix-e2ee-*(базова відповідь, thread follow-up, bootstrap, життєвий цикл recovery key, варіанти state-loss, поведінка server backup, device hygiene, перевірка SAS / QR / DM, restart, редагування артефактів) - E2EE CLI -
matrix-e2ee-cli-*(encryption setup, ідемпотентне setup, помилка bootstrap, життєвий цикл recovery-key, multi-account, gateway-reply round-trip, self-verification)
--scenario <id> (можна повторювати), щоб запустити вибраний вручну набір; поєднуйте з --profile all, щоб ігнорувати gating профілю.
Змінні середовища
| Змінна | Типове значення | Ефект |
|---|---|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 хв) | Жорстка верхня межа для всього запуску. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Межа для початкової контрольної відповіді. Release CI збільшує її на спільних раннерах, щоб повільний перший цикл Gateway не завершився помилкою до початку покриття сценаріїв. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Тихе вікно для негативних перевірок відсутності відповіді. Обмежується до ≤ тайм-ауту запуску. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Межа для завершення роботи Docker. Поверхні помилок містять команду відновлення docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Перевизначає образ homeserver під час перевірки з іншою версією Tuwunel. |
OPENCLAW_QA_MATRIX_PROGRESS | увімкнено | 0 вимикає рядки прогресу [matrix-qa] ... у stderr. 1 примусово вмикає їх. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | відредаговано | 1 зберігає тіло повідомлення та formatted_body у matrix-qa-observed-events.json. Типово редагує дані, щоб артефакти CI залишалися безпечними. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | вимкнено | 1 пропускає детермінований process.exit після запису артефактів. Типово вихід примусовий, бо нативні crypto-дескриптори matrix-js-sdk можуть утримувати event loop активним після завершення артефактів. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | не задано | Коли задано зовнішнім запускником (наприклад, scripts/run-node.mjs), Matrix QA повторно використовує цей шлях журналу замість запуску власного tee. |
Вихідні артефакти
Записуються в--output-dir:
matrix-qa-report.md- Markdown-звіт протоколу (що пройшло, не пройшло, було пропущено і чому).matrix-qa-summary.json- Структурований підсумок, придатний для парсингу CI та дашбордів.matrix-qa-route-state-manifest.json- Динамічний інвентарmatrix-qa-v1, індексований за id сценарію. Він фіксує відредаговані форми маршрутів/тіл, порядок запитів, спостережені повторні спроби, помилки, безперервність sync-token, а також сімейства станів пристроїв/ключів/медіа/резервних копій, спостережені під час цього запуску. Це виконуваний доказ, а не зафіксований у репозиторії baseline.matrix-qa-observed-events.json- Спостережені події Matrix від клієнтів драйвера й спостерігача. Тіла редагуються, якщо не заданоOPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; метадані схвалення підсумовуються з вибраними безпечними полями та обрізаним попереднім переглядом команди.matrix-qa-output.log- Об’єднані stdout/stderr із запуску. Якщо заданоOPENCLAW_RUN_NODE_OUTPUT_LOG, натомість повторно використовується журнал зовнішнього запускника.
<repo>/.artifacts/qa-e2e/matrix-<timestamp>, щоб послідовні запуски не перезаписували один одного.
Поради з тріажу
- Запуск зависає ближче до кінця: нативні crypto-дескриптори
matrix-js-sdkможуть пережити harness. Типово після запису артефактів примусово виконується чистийprocess.exit; якщо ви знялиOPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, очікуйте, що процес затримається. - Помилка очищення: знайдіть надруковану команду відновлення (виклик
docker compose ... down --remove-orphans) і виконайте її вручну, щоб звільнити порт homeserver. - Нестабільні вікна негативних перевірок у CI: зменште
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS(типово 8 с), коли CI швидкий; збільште його на повільних спільних раннерах. - Потрібні відредаговані тіла для звіту про помилку: перезапустіть із
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1і додайтеmatrix-qa-observed-events.json. Вважайте отриманий артефакт чутливим. - Інша версія Tuwunel: спрямуйте
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGEна версію, що тестується. Lane перевіряє лише закріплений типовий образ.
Контракт живого транспорту
Matrix — одна з трьох lane живого транспорту (Matrix, Telegram, Discord), які спільно використовують єдиний контрольний список контракту, визначений у Огляд QA → Покриття живого транспорту.qa-channel залишається широким синтетичним набором і навмисно не входить до цієї матриці.
Пов’язане
- Огляд QA - загальний стек QA і контракт живого транспорту
- QA Channel - синтетичний адаптер каналу для сценаріїв, підтримуваних репозиторієм
- Тестування - запуск тестів і додавання покриття QA
- Matrix - плагін каналу, що тестується