QA Matrix

Смуга QA Matrix запускає вбудований plugin @openclaw/matrix із тимчасовим домашнім сервером Tuwunel у Docker, використовуючи тимчасові облікові записи драйвера, тестованої системи (SUT) і спостерігача, а також попередньо створені кімнати. Це покриття Matrix із реальним транспортом для перевірок у робочому середовищі.

Інструментарій лише для супроводжувачів. Пакетні випуски OpenClaw не містять qa-lab, тому openclaw qa працює лише з робочої копії вихідного коду, яка безпосередньо завантажує вбудований засіб запуску без встановлення plugin.

Докладніший контекст щодо фреймворку QA див. в огляді QA.

Швидкий початок

pnpm openclaw qa matrix --profile fast --fail-fast

Звичайна команда pnpm openclaw qa matrix запускає --profile all і не зупиняється після першої помилки. Розподіляйте повний набір між паралельними завданнями за допомогою --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli.

Що робить ця смуга

1. Розгортає тимчасовий домашній сервер Tuwunel у Docker (типовий образ — ghcr.io/matrix-construct/tuwunel:v1.5.1, ім’я сервера — matrix-qa.test, порт — 28008) за обмеженим реєстратором запитів і відповідей із редагуванням конфіденційних даних.
2. Реєструє трьох тимчасових користувачів: driver (надсилає вхідний трафік), sut (тестований обліковий запис OpenClaw Matrix), observer (збирає сторонній трафік).
3. Створює кімнати, потрібні для вибраних сценаріїв (основна, для гілок, медіафайлів, перезапуску, додаткова, зі списком дозволів, E2EE, особистих повідомлень для перевірки тощо).
4. Запускає незалежну від основи протокольну перевірку matrix-qa-v1 на записаній межі Tuwunel. Модульні тести підтверджують контракт перевірки за допомогою фікстури протоколу Matrix; канонічний хост транспортного адаптера QA в #99707 відповідає за підключення реальної цілі Crabline.
5. Запускає дочірній Gateway OpenClaw зі справжнім plugin Matrix, обмеженим обліковим записом SUT.
6. Послідовно виконує сценарії, спостерігає за подіями через клієнти Matrix драйвера та спостерігача й визначає очікувані маршрути та стани із записаного трафіку.
7. Зупиняє домашній сервер, записує звіт і артефакти доказів, а потім завершує роботу.

CLI

pnpm openclaw qa matrix [options]

Загальні прапорці

Прапорці постачальника

Смуга використовує справжній транспорт Matrix, але постачальника моделі можна налаштувати:

Matrix QA не приймає --credential-source або --credential-role. Смуга локально створює тимчасових користувачів; спільного пулу облікових даних для оренди немає.

Профілі

Точне зіставлення міститься у extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.

Сценарії

Спільний адаптер Matrix надає такі канонічні сценарії YAML через openclaw qa suite --channel-driver live --channel matrix:

• channel-chat-baseline
• thread-follow-up
• thread-isolation
• thread-reply-override
• dm-shared-session
• dm-per-room-session

subagent-thread-spawn залишається доступним за явного вибору --scenario subagent-thread-spawn, але не входить до типового спільного набору Matrix, доки підтвердження завершення дочірнього процесу в реальному середовищі не стане стабільним.

Решта списку ідентифікаторів імперативних сценаріїв визначена об’єднанням MatrixQaScenarioId у extensions/qa-matrix/src/runners/contract/scenario-catalog.ts. Категорії:

• гілки: matrix-thread-root-preservation, matrix-thread-nested-reply-shape
• верхній рівень / особисті повідомлення / кімната: matrix-top-level-reply-shape, matrix-room-*, matrix-dm-*
• потокове передавання та перебіг виконання інструментів: matrix-room-partial-streaming-preview, matrix-room-quiet-streaming-preview, matrix-room-tool-progress-*, matrix-room-block-streaming
• медіафайли: matrix-media-type-coverage, matrix-room-image-understanding-attachment, matrix-attachment-only-ignored, matrix-unsupported-media-safe
• маршрутизація: matrix-room-autojoin-invite, matrix-secondary-room-*
• реакції: matrix-reaction-*
• схвалення: matrix-approval-* (метадані виконання/plugin, розбитий на частини резервний варіант, реакції відмови, гілки та маршрутизація target: "both")
• перезапуск і повторне відтворення: matrix-restart-*, matrix-stale-sync-replay-dedupe, matrix-room-membership-loss, matrix-homeserver-restart-resume, matrix-initial-catchup-then-incremental
• фільтрація за згадками, взаємодія між ботами та списки дозволів: 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-* (базова відповідь, продовження гілки, початкова ініціалізація, життєвий цикл ключа відновлення, варіанти втрати стану, поведінка серверного резервного копіювання, гігієна пристроїв, перевірка SAS / QR / особистими повідомленнями, перезапуск, редагування конфіденційних даних в артефактах)
• CLI E2EE: matrix-e2ee-cli-* (налаштування шифрування, ідемпотентне налаштування, помилка початкової ініціалізації, життєвий цикл ключа відновлення, кілька облікових записів, повний цикл відповіді Gateway, самоперевірка)

Передайте --scenario <id> (можна вказувати кілька разів), щоб запустити вручну вибраний набір; поєднайте з --profile all, щоб ігнорувати обмеження профілю.

Змінні середовища

Вихідні артефакти

Записуються до --output-dir (типово <repo>/.artifacts/qa-e2e/matrix-<timestamp>, тому послідовні запуски не перезаписують один одного):

• matrix-qa-report.md: звіт протоколу у форматі Markdown (що пройшло, завершилося помилкою, було пропущено та чому).
• matrix-qa-summary.json: структурований підсумок, придатний для обробки в CI та на інформаційних панелях.
• matrix-qa-route-state-manifest.json: динамічний перелік matrix-qa-v1, де ключем є ідентифікатор сценарію. Він фіксує відредаговані структури маршрутів і тіл, порядок запитів, спостережувані повторні спроби, помилки, безперервність токенів синхронізації, а також сімейства станів пристроїв, ключів, медіафайлів і резервних копій, спостережувані під час цього запуску. Це виконуваний доказ, а не базовий еталон, збережений у репозиторії.
• matrix-qa-observed-events.json: спостережувані події Matrix від клієнтів-драйверів і клієнтів-спостерігачів. Тіла редагуються, якщо не задано OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; метадані схвалення узагальнюються з вибраними безпечними полями та скороченим попереднім переглядом команди.
• matrix-qa-output.log: об’єднані stdout/stderr запуску. Якщо задано OPENCLAW_RUN_NODE_OUTPUT_LOG, натомість повторно використовується журнал зовнішнього засобу запуску.

Поради щодо діагностики

• Запуск зависає ближче до завершення: нативні криптографічні дескриптори matrix-js-sdk можуть продовжувати існувати після завершення роботи тестового середовища. Типово після запису артефактів примусово виконується чистий process.exit; якщо задано OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, очікуйте, що процес залишатиметься активним.
• Помилка очищення: знайдіть виведену команду відновлення (виклик docker compose ... down --remove-orphans) і виконайте її вручну, щоб звільнити порт домашнього сервера.
• Нестабільні часові вікна негативних перевірок у 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 версію, що тестується. Для цього конвеєра в репозиторії зафіксовано лише типовий образ.

Контракт перевірки транспорту наживо

Matrix — один із трьох конвеєрів перевірки транспорту наживо (Matrix, Telegram, Discord), які використовують єдиний контрольний список контракту, визначений у розділі Огляд QA: охоплення транспорту наживо. qa-channel залишається широким набором синтетичних перевірок і навмисно не входить до цієї матриці.

Пов’язані матеріали

• Огляд QA: загальний стек QA та контракт перевірки транспорту наживо
• Канал QA: синтетичний адаптер каналу для сценаріїв, що зберігаються в репозиторії
• Тестування: запуск тестів і додавання охоплення QA
• Matrix: Plugin каналу, що тестується