Pengujian

OpenClaw memiliki tiga rangkaian Vitest (unit/integrasi, e2e, live) dan sekumpulan kecil runner Docker. Dokumen ini adalah panduan "cara kami menguji":

• Apa yang dicakup setiap rangkaian (dan apa yang sengaja tidak dicakup).
• Perintah mana yang dijalankan untuk alur kerja umum (lokal, pra-push, debugging).
• Bagaimana pengujian live menemukan kredensial dan memilih model/penyedia.
• Cara menambahkan regresi untuk masalah model/penyedia dunia nyata.

Mulai cepat

Hampir setiap hari:

• Gerbang penuh (diharapkan sebelum push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Jalankan rangkaian penuh lokal lebih cepat di mesin yang lega: pnpm test:max
• Loop watch Vitest langsung: pnpm test:watch
• Penargetan file langsung sekarang juga merutekan path ekstensi/channel: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Dahulukan menjalankan target spesifik saat Anda mengiterasi satu kegagalan.
• Situs QA berbasis Docker: pnpm qa:lab:up
• Jalur QA berbasis VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Saat Anda menyentuh pengujian atau ingin keyakinan tambahan:

• Gerbang coverage: pnpm test:coverage
• Rangkaian E2E: pnpm test:e2e

Direktori Temp Pengujian

Utamakan helper bersama di test/helpers/temp-dir.ts untuk direktori sementara milik pengujian. Helper ini membuat kepemilikan eksplisit dan menjaga cleanup dalam siklus hidup pengujian yang sama:

  const tempDirs = useAutoCleanupTempDirTracker(afterEach); it("uses a temp workspace", () => {  const workspace = tempDirs.make("openclaw-example-");  // use workspace});

useAutoCleanupTempDirTracker(afterEach) sengaja tidak mengekspos metode cleanup manual; Vitest memiliki cleanup setelah setiap pengujian. Helper tingkat lebih rendah yang ada tetap tersedia untuk pengujian yang belum dipindahkan, tetapi pengujian baru dan yang sudah dimigrasikan harus menggunakan tracker pembersihan otomatis. Hindari penggunaan manual baru makeTempDir, cleanupTempDirs, atau createTempDirTracker dan hindari panggilan fs.mkdtemp* mentah baru dalam pengujian kecuali sebuah kasus secara eksplisit memverifikasi perilaku temp-dir mentah. Tambahkan komentar izin yang dapat diaudit dengan alasan konkret saat sebuah pengujian sengaja membutuhkan direktori temp mentah:

// openclaw-temp-dir: allow verifies raw fs cleanup behaviorconst workspace = fs.mkdtempSync(prefix);

Untuk visibilitas migrasi, node scripts/report-test-temp-creations.mjs melaporkan pembuatan temp-dir mentah baru dan penggunaan helper bersama manual baru pada baris diff yang ditambahkan tanpa memblokir gaya cleanup yang sudah ada. Cakupan filenya sengaja mengikuti klasifikasi path pengujian yang sama dengan scripts/changed-lanes.mjs alih-alih mempertahankan heuristik nama file helper pengujian terpisah, sambil melewati implementasi helper bersama itu sendiri. check:changed menjalankan laporan ini untuk path pengujian yang berubah sebagai sinyal CI hanya-peringatan; temuannya berupa anotasi peringatan GitHub, bukan kegagalan.

Saat men-debug penyedia/model nyata (memerlukan kredensial nyata):

• Rangkaian live (model + probe alat/gambar Gateway): pnpm test:live
• Targetkan satu file live secara senyap: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Laporan performa runtime: dispatch OpenClaw Performance dengan live_openai_candidate=true untuk giliran agen openai/gpt-5.5 nyata atau deep_profile=true untuk artefak CPU/heap/trace Kova. Eksekusi terjadwal harian memublikasikan artefak jalur penyedia tiruan, deep-profile, dan GPT 5.5 ke openclaw/clawgrit-reports saat CLAWGRIT_REPORTS_TOKEN dikonfigurasi. Laporan penyedia tiruan juga mencakup angka boot Gateway tingkat sumber, memori, tekanan Plugin, hello-loop model palsu berulang, dan startup CLI.
• Sweep model live Docker: pnpm test:docker:live-models
  • Setiap model yang dipilih sekarang menjalankan satu giliran teks plus probe kecil bergaya pembacaan file. Model yang metadatanya mengiklankan input image juga menjalankan satu giliran gambar kecil. Nonaktifkan probe tambahan dengan OPENCLAW_LIVE_MODEL_FILE_PROBE=0 atau OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0 saat mengisolasi kegagalan penyedia.
  • Coverage CI: OpenClaw Scheduled Live And E2E Checks harian dan OpenClaw Release Checks manual sama-sama memanggil workflow live/E2E yang dapat digunakan ulang dengan include_live_suites: true, yang mencakup job matriks model live Docker terpisah yang dipecah berdasarkan penyedia.
  • Untuk rerun CI terfokus, dispatch OpenClaw Live And E2E Checks (Reusable) dengan include_live_suites: true dan live_models_only: true.
  • Tambahkan secret penyedia baru bernilai-sinyal tinggi ke scripts/ci-hydrate-live-auth.sh plus .github/workflows/openclaw-live-and-e2e-checks-reusable.yml dan pemanggil terjadwal/rilisnya.
• Smoke chat-terikat Codex native: pnpm test:docker:live-codex-bind
  • Menjalankan jalur live Docker terhadap path app-server Codex, mengikat DM Slack sintetis dengan /codex bind, menjalankan /codex fast dan /codex permissions, lalu memverifikasi balasan polos dan lampiran gambar dirutekan melalui binding Plugin native alih-alih ACP.
• Smoke harness app-server Codex: pnpm test:docker:live-codex-harness
  • Menjalankan giliran agen Gateway melalui harness app-server Codex milik Plugin, memverifikasi /codex status dan /codex models, dan secara default menjalankan probe gambar, MCP cron, sub-agen, dan Guardian. Nonaktifkan probe sub-agen dengan OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 saat mengisolasi kegagalan app-server Codex lainnya. Untuk pemeriksaan sub-agen terfokus, nonaktifkan probe lain: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. Ini keluar setelah probe sub-agen kecuali OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 disetel.
• Smoke instalasi on-demand Codex: pnpm test:docker:codex-on-demand
  • Menginstal tarball OpenClaw terpaket di Docker, menjalankan onboarding API-key OpenAI, dan memverifikasi Plugin Codex plus dependensi @openai/codex diunduh ke root proyek npm terkelola sesuai permintaan.
• Smoke dependensi alat Plugin live: pnpm test:docker:live-plugin-tool
  • Mengemas Plugin fixture dengan dependensi slugify nyata, menginstalnya melalui npm-pack:, memverifikasi dependensi di bawah root proyek npm terkelola, lalu meminta model OpenAI live memanggil alat Plugin dan mengembalikan slug tersembunyi.
• Smoke perintah penyelamatan Crestodian: pnpm test:live:crestodian-rescue-channel
  • Pemeriksaan opt-in belt-and-suspenders untuk permukaan perintah penyelamatan channel pesan. Ini menjalankan /crestodian status, mengantrekan perubahan model persisten, membalas /crestodian yes, dan memverifikasi path tulis audit/config.
• Smoke Docker planner Crestodian: pnpm test:docker:crestodian-planner
  • Menjalankan Crestodian dalam kontainer tanpa config dengan CLI Claude palsu pada PATH dan memverifikasi fallback planner fuzzy diterjemahkan menjadi penulisan config bertipe yang diaudit.
• Smoke Docker first-run Crestodian: pnpm test:docker:crestodian-first-run
  • Memulai dari direktori state OpenClaw kosong, memverifikasi entrypoint Crestodian onboard modern, menerapkan penulisan setup/model/agen/Plugin Discord + SecretRef, memvalidasi config, dan memverifikasi entri audit. Path setup Ring 0 yang sama juga dicakup di QA Lab oleh pnpm openclaw qa suite --scenario crestodian-ring-zero-setup.
• Smoke biaya Moonshot/Kimi: dengan MOONSHOT_API_KEY disetel, jalankan openclaw models list --provider moonshot --json, lalu jalankan openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json secara terisolasi terhadap moonshot/kimi-k2.6. Verifikasi JSON melaporkan Moonshot/K2.6 dan transkrip asisten menyimpan usage.cost yang dinormalisasi.

Runner khusus QA

Perintah ini berada di samping rangkaian pengujian utama saat Anda membutuhkan realisme QA-lab:

CI menjalankan QA Lab dalam workflow khusus. Paritas agentic bersarang di bawah QA-Lab - All Lanes dan validasi rilis, bukan workflow PR mandiri. Validasi luas harus menggunakan Full Release Validation dengan rerun_group=qa-parity atau grup QA release-checks. Pemeriksaan rilis stabil/default menempatkan soak live/Docker menyeluruh di belakang run_release_soak=true; profil full memaksa soak aktif. QA-Lab - All Lanes berjalan setiap malam di main dan dari dispatch manual dengan jalur paritas tiruan, jalur Matrix live, jalur Telegram live yang dikelola Convex, dan jalur Discord live yang dikelola Convex sebagai job paralel. QA terjadwal dan pemeriksaan rilis meneruskan Matrix --profile fast secara eksplisit, sementara input CLI Matrix dan workflow manual tetap default ke all; dispatch manual dapat memecah all menjadi job transport, media, e2ee-smoke, e2ee-deep, dan e2ee-cli. OpenClaw Release Checks menjalankan paritas plus jalur Matrix cepat dan Telegram sebelum persetujuan rilis, menggunakan mock-openai/gpt-5.5 untuk pemeriksaan transport rilis agar tetap deterministik dan menghindari startup Plugin penyedia normal. Gateway transport live ini menonaktifkan pencarian memori; perilaku memori tetap dicakup oleh rangkaian paritas QA.

Shard media live rilis penuh menggunakan ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04, yang sudah memiliki ffmpeg dan ffprobe. Shard model/backend live Docker menggunakan image bersama ghcr.io/openclaw/openclaw-live-test:<sha> yang dibangun sekali per commit yang dipilih, lalu menariknya dengan OPENCLAW_SKIP_DOCKER_BUILD=1 alih-alih membangun ulang di dalam setiap shard.

• pnpm openclaw qa suite
  • Menjalankan skenario QA yang didukung repo langsung di host.
  • Menulis artefak tingkat atas qa-evidence.json, qa-suite-summary.json, dan qa-suite-report.md untuk set skenario yang dipilih, termasuk pilihan skenario alur campuran, Vitest, dan Playwright.
  • Saat dipicu oleh pnpm openclaw qa run --qa-profile <profile>, menyematkan scorecard profil taksonomi yang dipilih dalam qa-evidence.json yang sama. smoke-ci menulis evidence ramping, yang menetapkan evidenceMode: "slim" dan menghilangkan execution per entri. release mencakup irisan kesiapan rilis yang dikurasi; all memilih setiap kategori kematangan aktif dan ditujukan untuk dispatch workflow QA Profile Evidence secara eksplisit ketika artefak scorecard lengkap diperlukan.
  • Menjalankan beberapa skenario yang dipilih secara paralel secara default dengan pekerja Gateway yang terisolasi. qa-channel default ke konkurensi 4 (dibatasi oleh jumlah skenario yang dipilih). Gunakan --concurrency <count> untuk menyesuaikan jumlah pekerja, atau --concurrency 1 untuk lane serial lama.
  • Keluar dengan non-zero ketika ada skenario yang gagal. Gunakan --allow-failures ketika Anda menginginkan artefak tanpa kode keluar gagal.
  • Mendukung mode penyedia live-frontier, mock-openai, dan aimock. aimock memulai server penyedia lokal berbasis AIMock untuk cakupan fixture eksperimental dan mock protokol tanpa menggantikan lane mock-openai yang sadar skenario.
• pnpm openclaw qa coverage --match <query>
  • Mencari ID skenario, judul, permukaan, ID cakupan, referensi docs, referensi kode, Plugin, dan persyaratan penyedia, lalu mencetak target suite yang cocok.
  • Gunakan ini sebelum menjalankan QA Lab ketika Anda mengetahui perilaku atau path file yang disentuh tetapi bukan skenario terkecilnya. Ini hanya bersifat advisori; tetap pilih proof mock, live, Multipass, Matrix, atau transport dari perilaku yang diubah.
• pnpm test:plugins:kitchen-sink-live
  • Menjalankan gauntlet Plugin OpenAI Kitchen Sink live melalui QA Lab. Ini menginstal paket Kitchen Sink eksternal, memverifikasi inventaris permukaan plugin SDK, memeriksa /healthz dan /readyz, merekam evidence CPU/RSS Gateway, menjalankan satu giliran OpenAI live, dan memeriksa diagnostik adversarial. Memerlukan auth OpenAI live seperti OPENAI_API_KEY. Dalam sesi Testbox yang telah dihidrasi, ini otomatis mengambil profil live-auth Testbox ketika helper openclaw-testbox-env ada.
• pnpm test:gateway:cpu-scenarios
  • Menjalankan bench startup Gateway ditambah paket kecil skenario QA Lab mock (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) dan menulis ringkasan observasi CPU gabungan di bawah .artifacts/gateway-cpu-scenarios/.
  • Secara default hanya menandai observasi CPU panas yang berkelanjutan (--cpu-core-warn plus --hot-wall-warn-ms), sehingga lonjakan singkat saat startup dicatat sebagai metrik tanpa terlihat seperti regresi Gateway peg berdurasi beberapa menit.
  • Menggunakan artefak dist yang sudah dibangun; jalankan build terlebih dahulu ketika checkout belum memiliki output runtime yang segar.
• pnpm openclaw qa suite --runner multipass
  • Menjalankan suite QA yang sama di dalam VM Linux Multipass sekali pakai.
  • Mempertahankan perilaku pemilihan skenario yang sama seperti qa suite di host.
  • Menggunakan kembali flag pemilihan penyedia/model yang sama seperti qa suite.
  • Run live meneruskan input auth QA yang didukung dan praktis untuk guest: kunci penyedia berbasis env, path konfigurasi penyedia live QA, dan CODEX_HOME ketika ada.
  • Direktori output harus tetap berada di bawah root repo agar guest dapat menulis balik melalui workspace yang di-mount.
  • Menulis laporan + ringkasan QA normal beserta log Multipass di bawah .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Memulai situs QA berbasis Docker untuk pekerjaan QA bergaya operator.
• pnpm test:docker:npm-onboard-channel-agent
  • Membangun tarball npm dari checkout saat ini, menginstalnya secara global di Docker, menjalankan onboarding kunci API OpenAI non-interaktif, mengonfigurasi Telegram secara default, memverifikasi runtime Plugin yang dipaketkan dimuat tanpa perbaikan dependency saat startup, menjalankan doctor, dan menjalankan satu giliran agen lokal terhadap endpoint OpenAI yang di-mock.
  • Gunakan OPENCLAW_NPM_ONBOARD_CHANNEL=discord untuk menjalankan lane packaged-install yang sama dengan Discord.
• pnpm test:docker:session-runtime-context
  • Menjalankan smoke Docker aplikasi-terbangun deterministik untuk transkrip konteks runtime tertanam. Ini memverifikasi bahwa konteks runtime OpenClaw tersembunyi dipersistenkan sebagai pesan kustom non-display alih-alih bocor ke giliran pengguna yang terlihat, lalu men-seed JSONL sesi rusak yang terdampak dan memverifikasi openclaw doctor --fix menulis ulangnya ke branch aktif dengan backup.
• pnpm test:docker:npm-telegram-live
  • Menginstal kandidat paket OpenClaw di Docker, menjalankan onboarding installed-package, mengonfigurasi Telegram melalui CLI yang terinstal, lalu menggunakan kembali lane QA Telegram live dengan paket terinstal itu sebagai SUT Gateway.
  • Wrapper hanya me-mount sumber harness qa-lab dari checkout; paket terinstal memiliki dist, openclaw/plugin-sdk, dan runtime Plugin yang dibundel sehingga lane tidak mencampur Plugin checkout saat ini ke dalam paket yang diuji.
  • Default ke OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; set OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz atau OPENCLAW_CURRENT_PACKAGE_TGZ untuk menguji tarball lokal yang sudah di-resolve alih-alih menginstal dari registry.
  • Memancarkan timing RTT berulang dalam qa-evidence.json secara default dengan OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20. Override OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES, OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS, atau OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES untuk menyesuaikan run RTT. OPENCLAW_NPM_TELEGRAM_RTT_CHECKS menerima daftar ID check QA Telegram yang dipisahkan koma untuk di-sample; ketika tidak diset, check default yang mampu RTT adalah telegram-mentioned-message-reply.
  • Menggunakan kredensial env Telegram yang sama atau sumber kredensial Convex seperti pnpm openclaw qa telegram. Untuk automasi CI/rilis, set OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex plus OPENCLAW_QA_CONVEX_SITE_URL dan secret role. Jika OPENCLAW_QA_CONVEX_SITE_URL dan secret role Convex ada di CI, wrapper Docker memilih Convex secara otomatis.
  • Wrapper memvalidasi env kredensial Telegram atau Convex di host sebelum pekerjaan build/install Docker. Set OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 hanya ketika sengaja men-debug setup pra-kredensial.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer meng-override OPENCLAW_QA_CREDENTIAL_ROLE bersama hanya untuk lane ini. Ketika kredensial Convex dipilih dan tidak ada role yang diset, wrapper menggunakan ci di CI dan maintainer di luar CI.
  • GitHub Actions mengekspos lane ini sebagai workflow maintainer manual NPM Telegram Beta E2E. Ini tidak berjalan saat merge. Workflow menggunakan environment qa-live-shared dan lease kredensial CI Convex.
• GitHub Actions juga mengekspos Package Acceptance untuk proof produk side-run terhadap satu kandidat paket. Ini menerima ref tepercaya, spec npm terpublikasi, URL tarball HTTPS plus SHA-256, atau artefak tarball dari run lain, mengunggah openclaw-current.tgz yang dinormalisasi sebagai package-under-test, lalu menjalankan scheduler Docker E2E yang sudah ada dengan profil lane smoke, package, product, full, atau custom. Set telegram_mode=mock-openai atau live-frontier untuk menjalankan workflow QA Telegram terhadap artefak package-under-test yang sama.
  • Proof produk beta terbaru:

gh workflow run package-acceptance.yml --ref main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=product \  -f telegram_mode=mock-openai

• Proof URL tarball persis memerlukan digest dan menggunakan kebijakan keamanan URL publik:

gh workflow run package-acceptance.yml --ref main \  -f source=url \  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

• Mirror tarball enterprise/private menggunakan kebijakan sumber tepercaya eksplisit:

gh workflow run package-acceptance.yml --ref main \  -f source=trusted-url \  -f trusted_source_id=enterprise-artifactory \  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

source=trusted-url membaca .github/package-trusted-sources.json dari ref workflow tepercaya dan tidak menerima kredensial URL atau bypass jaringan privat melalui input workflow. Jika kebijakan bernama mendeklarasikan bearer auth, konfigurasikan secret tetap OPENCLAW_TRUSTED_PACKAGE_TOKEN.

• Proof artefak mengunduh artefak tarball dari run Actions lain:

gh workflow run package-acceptance.yml --ref main \  -f source=artifact \  -f artifact_run_id=<run-id> \  -f artifact_name=<artifact-name> \  -f suite_profile=smoke

• pnpm test:docker:plugins

  • Mengemas dan menginstal build OpenClaw saat ini di Docker, memulai Gateway dengan OpenAI terkonfigurasi, lalu mengaktifkan channel/Plugin yang dibundel melalui edit konfigurasi.
  • Memverifikasi bahwa discovery setup membiarkan Plugin unduhan yang belum dikonfigurasi tetap absen, perbaikan doctor pertama yang dikonfigurasi menginstal setiap Plugin unduhan yang hilang secara eksplisit, dan restart kedua tidak menjalankan perbaikan dependency tersembunyi.
  • Juga menginstal baseline npm lama yang dikenal, mengaktifkan Telegram sebelum menjalankan openclaw update --tag <candidate>, dan memverifikasi bahwa doctor pasca-update kandidat membersihkan sisa dependency Plugin legacy tanpa perbaikan postinstall sisi harness.

• pnpm test:parallels:npm-update

  • Menjalankan smoke update packaged-install native di seluruh guest Parallels. Setiap platform yang dipilih pertama-tama menginstal paket baseline yang diminta, lalu menjalankan perintah openclaw update yang terinstal di guest yang sama dan memverifikasi versi terinstal, status update, kesiapan Gateway, dan satu giliran agen lokal.

  • Gunakan --platform macos, --platform windows, atau --platform linux saat mengiterasi pada satu guest. Gunakan --json untuk path artefak ringkasan dan status per-lane.

  • Lane OpenAI menggunakan openai/gpt-5.5 untuk proof giliran agen live secara default. Berikan --model <provider/model> atau set OPENCLAW_PARALLELS_OPENAI_MODEL ketika sengaja memvalidasi model OpenAI lain.

  • Bungkus run lokal yang lama dengan timeout host agar stall transport Parallels tidak dapat menghabiskan sisa jendela pengujian:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --jsontimeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json

  • Skrip menulis log lane bertingkat di bawah /tmp/openclaw-parallels-npm-update.*. Periksa windows-update.log, macos-update.log, atau linux-update.log sebelum menganggap wrapper luar hang.

  • Update Windows dapat menghabiskan 10 hingga 15 menit dalam pekerjaan doctor pasca-update dan update paket pada guest dingin; itu masih sehat ketika log debug npm bertingkat terus maju.

  • Jangan menjalankan wrapper agregat ini secara paralel dengan lane smoke Parallels macOS, Windows, atau Linux individual. Mereka berbagi state VM dan dapat bertabrakan saat restore snapshot, serving paket, atau state Gateway guest.

  • Proof pasca-update menjalankan permukaan Plugin bundel normal karena facade capability seperti speech, image generation, dan media understanding dimuat melalui API runtime bundel meskipun giliran agen itu sendiri hanya memeriksa respons teks sederhana.

• pnpm openclaw qa aimock

  • Memulai hanya server penyedia AIMock lokal untuk pengujian smoke protokol langsung.

• pnpm openclaw qa matrix

  • Menjalankan jalur QA langsung Matrix terhadap homeserver Tuwunel sekali pakai yang didukung Docker. Hanya checkout sumber - instalasi paket tidak menyertakan qa-lab.
  • CLI lengkap, katalog profil/skenario, variabel env, dan tata letak artefak: QA Matrix.

• pnpm openclaw qa telegram

  • Menjalankan jalur QA langsung Telegram terhadap grup privat nyata menggunakan token bot driver dan SUT dari env.
  • Memerlukan OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN, dan OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. Id grup harus berupa id chat Telegram numerik.
  • Mendukung --credential-source convex untuk kredensial bersama dalam kumpulan. Gunakan mode env secara bawaan, atau atur OPENCLAW_QA_CREDENTIAL_SOURCE=convex untuk ikut memakai sewa kumpulan.
  • Bawaan mencakup canary, gerbang mention, pengalamatan perintah, /status, balasan bot-ke-bot yang disebut, dan balasan perintah native inti. Bawaan mock-openai juga mencakup regresi rantai balasan deterministik dan streaming pesan akhir Telegram. Gunakan --list-scenarios untuk probe opsional seperti session_status.
  • Keluar dengan kode non-nol ketika skenario apa pun gagal. Gunakan --allow-failures ketika Anda menginginkan artefak tanpa kode keluar gagal.
  • Memerlukan dua bot berbeda dalam grup privat yang sama, dengan bot SUT mengekspos nama pengguna Telegram.
  • Untuk pengamatan bot-ke-bot yang stabil, aktifkan Bot-to-Bot Communication Mode di @BotFather untuk kedua bot dan pastikan bot driver dapat mengamati lalu lintas bot grup.
  • Menulis laporan QA Telegram, ringkasan, dan qa-evidence.json di bawah .artifacts/qa-e2e/.... Skenario balasan menyertakan RTT dari permintaan kirim driver hingga balasan SUT yang diamati.

Mantis Telegram Live adalah wrapper bukti PR di sekitar jalur ini. Ia menjalankan ref kandidat dengan kredensial Telegram yang disewa melalui Convex, merender bundel laporan/bukti QA yang telah disunting di browser desktop Crabbox, merekam bukti MP4, menghasilkan GIF yang dipangkas berdasarkan gerakan, mengunggah bundel artefak, dan memposting bukti PR inline melalui Mantis GitHub App ketika pr_number diatur. Maintainer dapat memulainya dari UI Actions melalui Mantis Scenario (scenario_id: telegram-live) atau langsung dari komentar pull request:

@openclaw-mantis telegram@openclaw-mantis telegram scenario=telegram-status-command@openclaw-mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

Mantis Telegram Desktop Proof adalah wrapper agentic native Telegram Desktop sebelum/sesudah untuk bukti visual PR. Mulai dari UI Actions dengan instructions bentuk bebas, melalui Mantis Scenario (scenario_id: telegram-desktop-proof), atau dari komentar PR:

@openclaw-mantis telegram desktop proof

Agen Mantis membaca PR, memutuskan perilaku yang terlihat di Telegram apa yang membuktikan perubahan, menjalankan jalur bukti Telegram Desktop pengguna nyata Crabbox pada ref acuan dan kandidat, mengiterasi hingga GIF native berguna, menulis manifes motionPreview berpasangan, dan memposting tabel GIF 2 kolom yang sama melalui Mantis GitHub App ketika pr_number diatur.

• pnpm openclaw qa mantis telegram-desktop-builder
  • Menyewa atau menggunakan ulang desktop Linux Crabbox, menginstal Telegram Desktop native, mengonfigurasi OpenClaw dengan token bot SUT Telegram yang disewa, memulai Gateway, dan merekam bukti tangkapan layar/MP4 dari desktop VNC yang terlihat.
  • Bawaan ke --credential-source convex sehingga workflow hanya membutuhkan rahasia broker Convex. Gunakan --credential-source env dengan variabel OPENCLAW_QA_TELEGRAM_* yang sama seperti pnpm openclaw qa telegram.
  • Telegram Desktop tetap membutuhkan login/profil pengguna. Token bot hanya mengonfigurasi OpenClaw. Gunakan --telegram-profile-archive-env <name> untuk arsip profil .tgz base64, atau gunakan --keep-lease dan masuk secara manual melalui VNC sekali.
  • Menulis mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png, dan telegram-desktop-builder.mp4 di bawah direktori output.

Jalur transport langsung berbagi satu kontrak standar agar transport baru tidak menyimpang; matriks cakupan per jalur berada di ikhtisar QA → Cakupan transport langsung. qa-channel adalah suite sintetis luas dan bukan bagian dari matriks tersebut.

Kredensial Telegram bersama melalui Convex (v1)

Ketika --credential-source convex (atau OPENCLAW_QA_CREDENTIAL_SOURCE=convex) diaktifkan untuk QA transport langsung, lab QA memperoleh sewa eksklusif dari kumpulan yang didukung Convex, mengirim Heartbeat untuk sewa itu saat jalur berjalan, dan melepaskan sewa saat shutdown. Nama bagian ini ada sebelum dukungan Discord, Slack, dan WhatsApp; kontrak sewa dibagikan di seluruh jenis.

Scaffold proyek Convex referensi:

• qa/convex-credential-broker/

Variabel env yang diperlukan:

• OPENCLAW_QA_CONVEX_SITE_URL (misalnya https://your-deployment.convex.site)
• Satu rahasia untuk peran yang dipilih:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER untuk maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI untuk ci
• Pemilihan peran kredensial:
  • CLI: --credential-role maintainer|ci
  • Bawaan env: OPENCLAW_QA_CREDENTIAL_ROLE (bawaan ke ci di CI, jika tidak maintainer)

Variabel env opsional:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (bawaan 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (bawaan 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (bawaan 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (bawaan 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (bawaan /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (id jejak opsional)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 mengizinkan URL Convex loopback http:// untuk pengembangan khusus lokal.

OPENCLAW_QA_CONVEX_SITE_URL sebaiknya menggunakan https:// dalam operasi normal.

Perintah admin maintainer (tambah/hapus/daftar kumpulan) memerlukan OPENCLAW_QA_CONVEX_SECRET_MAINTAINER secara khusus.

Helper CLI untuk maintainer:

pnpm openclaw qa credentials doctorpnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.jsonpnpm openclaw qa credentials list --kind telegrampnpm openclaw qa credentials remove --credential-id <credential-id>

Gunakan doctor sebelum menjalankan langsung untuk memeriksa URL situs Convex, rahasia broker, prefiks endpoint, timeout HTTP, dan keterjangkauan admin/daftar tanpa mencetak nilai rahasia. Gunakan --json untuk output yang dapat dibaca mesin di skrip dan utilitas CI.

Kontrak endpoint bawaan (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • Permintaan: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Sukses: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Habis/dapat dicoba ulang: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • Permintaan: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Sukses: { status: "ok", index, data }
• POST /heartbeat
  • Permintaan: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Sukses: { status: "ok" } (atau 2xx kosong)
• POST /release
  • Permintaan: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Sukses: { status: "ok" } (atau 2xx kosong)
• POST /admin/add (hanya rahasia maintainer)
  • Permintaan: { kind, actorId, payload, note?, status? }
  • Sukses: { status: "ok", credential }
• POST /admin/remove (hanya rahasia maintainer)
  • Permintaan: { credentialId, actorId }
  • Sukses: { status: "ok", changed, credential }
  • Penjaga sewa aktif: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (hanya rahasia maintainer)
  • Permintaan: { kind?, status?, includePayload?, limit? }
  • Sukses: { status: "ok", credentials, count }

Bentuk payload untuk jenis Telegram:

• { groupId: string, driverToken: string, sutToken: string }
• groupId harus berupa string id chat Telegram numerik.
• admin/add memvalidasi bentuk ini untuk kind: "telegram" dan menolak payload yang salah bentuk.

Bentuk payload untuk jenis pengguna nyata Telegram:

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId, dan telegramApiId harus berupa string numerik.
• tdlibArchiveSha256 dan desktopTdataArchiveSha256 harus berupa string heksadesimal SHA-256.
• kind: "telegram-user" dicadangkan untuk workflow bukti Telegram Desktop Mantis. Jalur QA Lab generik tidak boleh memperolehnya.

Payload multi-channel yang divalidasi broker:

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

Jalur Slack juga dapat menyewa dari kumpulan, tetapi validasi payload Slack saat ini berada di runner QA Slack, bukan broker. Gunakan { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string } untuk baris Slack.

Menambahkan channel ke QA

Arsitektur dan nama helper skenario untuk adapter channel baru berada di ikhtisar QA → Menambahkan channel. Batas minimum: implementasikan runner transport pada seam host qa-lab bersama, deklarasikan qaRunners dalam manifes Plugin, pasang sebagai openclaw qa <runner>, dan tulis skenario di bawah qa/scenarios/.

Suite pengujian (apa yang berjalan di mana)

Anggap suite sebagai "realisme yang meningkat" (dan flakiness/biaya yang meningkat):

Unit / integrasi (bawaan)

• Perintah: pnpm test
• Config: run tanpa target menggunakan set shard vitest.full-*.config.ts dan dapat memperluas shard multi-proyek menjadi config per proyek untuk penjadwalan paralel
• File: inventaris core/unit di bawah src/**/*.test.ts, packages/**/*.test.ts, dan test/**/*.test.ts; pengujian unit UI berjalan di shard khusus unit-ui
• Cakupan:
  • Pengujian unit murni
  • Pengujian integrasi dalam proses (auth Gateway, routing, tooling, parsing, config)
  • Regresi deterministik untuk bug yang diketahui
• Ekspektasi:
  • Berjalan di CI
  • Tidak memerlukan kunci nyata
  • Harus cepat dan stabil
  • Pengujian resolver dan loader permukaan publik harus membuktikan perilaku fallback api.js dan runtime-api.js yang luas dengan fixture Plugin kecil yang dihasilkan, bukan API sumber Plugin bundel nyata. Pemuatan API Plugin nyata termasuk dalam suite kontrak/integrasi milik Plugin.

Kebijakan dependensi native:

• Instalasi pengujian bawaan melewati build opus Discord native opsional. Suara Discord menggunakan libopus-wasm yang dibundel, dan @discordjs/opus tetap dinonaktifkan di allowBuilds sehingga pengujian lokal dan jalur Testbox tidak mengompilasi addon native.
• Bandingkan performa opus native di repo benchmark libopus-wasm, bukan di loop instalasi/pengujian OpenClaw bawaan. Jangan atur @discordjs/opus ke true di allowBuilds bawaan; itu membuat loop instalasi/pengujian yang tidak terkait mengompilasi kode native.

Stabilitas (gateway)

• Perintah: pnpm test:stability:gateway
• Config: vitest.gateway.config.ts, dipaksa ke satu worker
• Cakupan:
  • Memulai Gateway loopback nyata dengan diagnostik aktif secara default
  • Menggerakkan churn pesan gateway sintetis, memori, dan payload besar melalui path event diagnostik
  • Mengkueri diagnostics.stability melalui RPC WS Gateway
  • Mencakup helper persistensi bundle stabilitas diagnostik
  • Memastikan recorder tetap terbatas, sampel RSS sintetis tetap di bawah budget tekanan, dan kedalaman antrean per sesi kembali terkuras ke nol
• Ekspektasi:
  • Aman untuk CI dan tanpa key
  • Lane sempit untuk tindak lanjut regresi stabilitas, bukan pengganti suite Gateway penuh

E2E (agregat repo)

• Perintah: pnpm test:e2e
• Cakupan:
  • Menjalankan lane E2E smoke gateway
  • Menjalankan lane E2E browser Control UI yang di-mock
• Ekspektasi:
  • Aman untuk CI dan tanpa key
  • Memerlukan Playwright Chromium terinstal

E2E (smoke gateway)

• Perintah: pnpm test:e2e:gateway
• Config: vitest.e2e.config.ts
• File: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts, dan pengujian E2E bundled-plugin di bawah extensions/
• Default runtime:
  • Menggunakan threads Vitest dengan isolate: false, sesuai dengan bagian repo lainnya.
  • Menggunakan worker adaptif (CI: hingga 2, lokal: default 1).
  • Berjalan dalam mode senyap secara default untuk mengurangi overhead I/O konsol.
• Override berguna:
  • OPENCLAW_E2E_WORKERS=<n> untuk memaksa jumlah worker (dibatasi pada 16).
  • OPENCLAW_E2E_VERBOSE=1 untuk mengaktifkan kembali output konsol verbose.
• Cakupan:
  • Perilaku end-to-end gateway multi-instance
  • Permukaan WebSocket/HTTP, pairing node, dan networking yang lebih berat
• Ekspektasi:
  • Berjalan di CI (ketika diaktifkan dalam pipeline)
  • Tidak memerlukan key nyata
  • Lebih banyak bagian bergerak daripada pengujian unit (bisa lebih lambat)

E2E (browser Control UI yang di-mock)

• Perintah: pnpm test:ui:e2e
• Config: test/vitest/vitest.ui-e2e.config.ts
• File: ui/src/**/*.e2e.test.ts
• Cakupan:
  • Memulai Vite Control UI
  • Menggerakkan halaman Chromium nyata melalui Playwright
  • Mengganti Gateway WebSocket dengan mock dalam browser yang deterministik
• Ekspektasi:
  • Berjalan di CI sebagai bagian dari pnpm test:e2e
  • Tidak memerlukan Gateway, agent, atau key provider nyata
  • Dependensi browser harus tersedia (pnpm --dir ui exec playwright install chromium)

E2E: smoke backend OpenShell

• Perintah: pnpm test:e2e:openshell
• File: extensions/openshell/src/backend.e2e.test.ts
• Cakupan:
  • Menggunakan ulang gateway OpenShell lokal yang aktif
  • Membuat sandbox dari Dockerfile lokal sementara
  • Menguji backend OpenShell OpenClaw melalui sandbox ssh-config + eksekusi SSH nyata
  • Memverifikasi perilaku filesystem remote-canonical melalui bridge fs sandbox
• Ekspektasi:
  • Hanya opt-in; bukan bagian dari run default pnpm test:e2e
  • Memerlukan CLI openshell lokal plus daemon Docker yang berfungsi
  • Memerlukan gateway OpenShell lokal yang aktif dan sumber config-nya
  • Menggunakan HOME / XDG_CONFIG_HOME terisolasi, lalu menghancurkan sandbox pengujian
• Override berguna:
  • OPENCLAW_E2E_OPENSHELL=1 untuk mengaktifkan pengujian saat menjalankan suite e2e yang lebih luas secara manual
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell untuk menunjuk ke binary CLI non-default atau skrip wrapper
  • OPENCLAW_E2E_OPENSHELL_CONFIG_HOME=/path/to/config untuk mengekspos config gateway terdaftar ke pengujian terisolasi
  • OPENCLAW_E2E_OPENSHELL_HOST_IP=172.18.0.1 untuk mengganti IP gateway Docker yang digunakan oleh fixture kebijakan host

Live (provider nyata + model nyata)

• Perintah: pnpm test:live
• Konfigurasi: vitest.live.config.ts
• Berkas: src/**/*.live.test.ts, test/**/*.live.test.ts, dan pengujian live Plugin bundel di bawah extensions/
• Default: diaktifkan oleh pnpm test:live (mengatur OPENCLAW_LIVE_TEST=1)
• Cakupan:
  • "Apakah provider/model ini benar-benar berfungsi hari ini dengan kredensial nyata?"
  • Menangkap perubahan format provider, keunikan pemanggilan tool, masalah autentikasi, dan perilaku batas laju
• Ekspektasi:
  • Secara desain tidak stabil untuk CI (jaringan nyata, kebijakan provider nyata, kuota, gangguan)
  • Memerlukan biaya / menggunakan batas laju
  • Lebih baik menjalankan subset yang dipersempit daripada "semuanya"
• Run live menggunakan kunci API yang sudah diekspor dan profil autentikasi yang sudah disiapkan.
• Secara default, run live tetap mengisolasi HOME dan menyalin materi konfigurasi/autentikasi ke home pengujian sementara sehingga fixture unit tidak dapat mengubah ~/.openclaw nyata Anda.
• Atur OPENCLAW_LIVE_USE_REAL_HOME=1 hanya ketika Anda sengaja memerlukan pengujian live menggunakan direktori home nyata Anda.
• pnpm test:live default ke mode yang lebih senyap: mode ini mempertahankan output progres [live] ... dan membisukan log bootstrap gateway/obrolan Bonjour. Atur OPENCLAW_LIVE_TEST_QUIET=0 jika Anda ingin log startup lengkap kembali.
• Rotasi kunci API (spesifik provider): atur *_API_KEYS dengan format koma/titik koma atau *_API_KEY_1, *_API_KEY_2 (misalnya OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) atau override per-live melalui OPENCLAW_LIVE_*_KEY; pengujian mencoba ulang pada respons batas laju.
• Output progres/heartbeat:
  • Suite live sekarang memancarkan baris progres ke stderr sehingga panggilan provider yang lama terlihat aktif bahkan saat penangkapan konsol Vitest senyap.
  • vitest.live.config.ts menonaktifkan intersepsi konsol Vitest sehingga baris progres provider/gateway mengalir segera selama run live.
  • Sesuaikan heartbeat model-langsung dengan OPENCLAW_LIVE_HEARTBEAT_MS.
  • Sesuaikan heartbeat gateway/probe dengan OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Suite mana yang harus saya jalankan?

Gunakan tabel keputusan ini:

• Mengedit logika/pengujian: jalankan pnpm test (dan pnpm test:coverage jika Anda mengubah banyak hal)
• Menyentuh jaringan gateway / protokol WS / pairing: tambahkan pnpm test:e2e
• Men-debug "bot saya down" / kegagalan spesifik provider / pemanggilan tool: jalankan pnpm test:live yang dipersempit

Pengujian live (menyentuh jaringan)

Untuk matriks model live, smoke backend CLI, smoke ACP, harness app-server Codex, dan semua pengujian live media-provider (Deepgram, BytePlus, ComfyUI, image, music, video, media harness) - ditambah penanganan kredensial untuk run live - lihat Menguji suite live. Untuk checklist validasi pembaruan dan Plugin khusus, lihat Menguji pembaruan dan Plugin.

Runner Docker (pemeriksaan opsional "berfungsi di Linux")

Runner Docker ini terbagi menjadi dua kelompok:

• Runner model live: test:docker:live-models dan test:docker:live-gateway hanya menjalankan berkas live profile-key yang cocok di dalam image Docker repo (src/agents/models.profiles.live.test.ts dan src/gateway/gateway-models.profiles.live.test.ts), dengan me-mount direktori konfigurasi lokal, workspace, dan berkas env profil opsional Anda. Entrypoint lokal yang cocok adalah test:live:models-profiles dan test:live:gateway-profiles.
• Runner live Docker menjaga batas praktisnya sendiri saat diperlukan: test:docker:live-models default ke set high-signal yang didukung dan dikurasi, dan test:docker:live-gateway default ke OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000, dan OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Atur OPENCLAW_LIVE_MAX_MODELS atau variabel env gateway ketika Anda secara eksplisit menginginkan batas yang lebih kecil atau pemindaian yang lebih besar.
• test:docker:all membangun image Docker live sekali melalui test:docker:live-build, mengemas OpenClaw sekali sebagai tarball npm melalui scripts/package-openclaw-for-docker.mjs, lalu membangun/menggunakan ulang dua image scripts/e2e/Dockerfile. Image bare hanyalah runner Node/Git untuk lane install/update/plugin-dependency; lane tersebut me-mount tarball yang sudah dibangun. Image fungsional menginstal tarball yang sama ke /app untuk lane fungsionalitas built-app. Definisi lane Docker berada di scripts/lib/docker-e2e-scenarios.mjs; logika planner berada di scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs mengeksekusi plan yang dipilih. Agregat menggunakan scheduler lokal berbobot: OPENCLAW_DOCKER_ALL_PARALLELISM mengontrol slot proses, sementara batas sumber daya mencegah lane live berat, npm-install, dan multi-service semuanya dimulai sekaligus. Jika satu lane lebih berat daripada batas aktif, scheduler masih dapat memulainya ketika pool kosong lalu menjaganya berjalan sendiri sampai kapasitas tersedia lagi. Default-nya 10 slot, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=5, dan OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; sesuaikan OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT atau OPENCLAW_DOCKER_ALL_DOCKER_LIMIT hanya ketika host Docker memiliki ruang kapasitas lebih. Runner melakukan preflight Docker secara default, menghapus kontainer E2E OpenClaw yang usang, mencetak status setiap 30 detik, menyimpan timing lane yang berhasil di .artifacts/docker-tests/lane-timings.json, dan menggunakan timing tersebut untuk memulai lane yang lebih lama terlebih dahulu pada run berikutnya. Gunakan OPENCLAW_DOCKER_ALL_DRY_RUN=1 untuk mencetak manifest lane berbobot tanpa membangun atau menjalankan Docker, atau node scripts/test-docker-all.mjs --plan-json untuk mencetak plan CI bagi lane yang dipilih, kebutuhan package/image, dan kredensial.
• Package Acceptance adalah gate package native GitHub untuk "apakah tarball yang dapat diinstal ini berfungsi sebagai produk?" Gate ini me-resolve satu package kandidat dari source=npm, source=ref, source=url, atau source=artifact, mengunggahnya sebagai package-under-test, lalu menjalankan lane E2E Docker yang dapat digunakan ulang terhadap tarball yang sama persis alih-alih mengemas ulang ref yang dipilih. Profil diurutkan berdasarkan keluasan: smoke, package, product, dan full. Lihat Menguji pembaruan dan Plugin untuk kontrak package/update/Plugin, matriks survivor published-upgrade, default rilis, dan triase kegagalan.
• Pemeriksaan build dan rilis menjalankan scripts/check-cli-bootstrap-imports.mjs setelah tsdown. Guard menelusuri graf built statis dari dist/entry.js dan dist/cli/run-main.js dan gagal jika startup pra-dispatch mengimpor dependensi package seperti Commander, prompt UI, undici, atau logging sebelum dispatch perintah; guard ini juga menjaga chunk run gateway bundel tetap di bawah anggaran dan menolak impor statis dari path gateway dingin yang diketahui. Smoke CLI terpaket juga mencakup bantuan root, bantuan onboard, bantuan doctor, status, skema config, dan perintah daftar-model.
• Kompatibilitas legacy Package Acceptance dibatasi pada 2026.4.25 (termasuk 2026.4.25-beta.*). Hingga batas tersebut, harness hanya menoleransi celah metadata package yang sudah dikirim: entri inventaris QA privat yang dihilangkan, gateway install --wrapper yang hilang, berkas patch yang hilang dalam fixture git turunan tarball, update.channel persisten yang hilang, lokasi install-record Plugin legacy, persistensi install-record marketplace yang hilang, dan migrasi metadata config selama plugins update. Untuk package setelah 2026.4.25, path tersebut menjadi kegagalan ketat.
• Runner smoke kontainer: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:release-user-journey, test:docker:release-typed-onboarding, test:docker:release-media-memory, test:docker:release-upgrade-user-journey, test:docker:release-plugin-marketplace, test:docker:skill-install, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:agent-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix, dan test:docker:config-reload mem-boot satu atau lebih kontainer nyata dan memverifikasi path integrasi tingkat lebih tinggi.
• Lane E2E Docker/Bash yang menginstal tarball OpenClaw terkemas melalui scripts/lib/openclaw-e2e-instance.sh membatasi npm install pada OPENCLAW_E2E_NPM_INSTALL_TIMEOUT (default 600s; atur 0 untuk menonaktifkan wrapper saat debugging).

Runner Docker model live juga hanya melakukan bind-mount home autentikasi CLI yang diperlukan (atau semua yang didukung ketika run tidak dipersempit), lalu menyalinnya ke home kontainer sebelum run sehingga OAuth CLI eksternal dapat menyegarkan token tanpa mengubah penyimpanan autentikasi host:

• Model langsung: pnpm test:docker:live-models (skrip: scripts/test-live-models-docker.sh)

• Smoke bind ACP: pnpm test:docker:live-acp-bind (skrip: scripts/test-live-acp-bind-docker.sh; mencakup Claude, Codex, dan Gemini secara default, dengan cakupan Droid/OpenCode ketat melalui pnpm test:docker:live-acp-bind:droid dan pnpm test:docker:live-acp-bind:opencode)

• Smoke backend CLI: pnpm test:docker:live-cli-backend (skrip: scripts/test-live-cli-backend-docker.sh)

• Smoke harness app-server Codex: pnpm test:docker:live-codex-harness (skrip: scripts/test-live-codex-harness-docker.sh)

• Gateway + agen dev: pnpm test:docker:live-gateway (skrip: scripts/test-live-gateway-models-docker.sh)

• Smoke observabilitas: pnpm qa:otel:smoke, pnpm qa:prometheus:smoke, dan pnpm qa:observability:smoke adalah lane source-checkout QA privat. Lane ini sengaja bukan bagian dari lane rilis Docker package karena tarball npm menghilangkan QA Lab.

• Smoke live Open WebUI: pnpm test:docker:openwebui (skrip: scripts/e2e/openwebui-docker.sh)

• Wizard onboarding (TTY, scaffolding lengkap): pnpm test:docker:onboard (skrip: scripts/e2e/onboard-docker.sh)

• Smoke onboarding/channel/agen tarball Npm: pnpm test:docker:npm-onboard-channel-agent menginstal tarball OpenClaw terkemas secara global di Docker, mengonfigurasi OpenAI melalui onboarding env-ref plus Telegram secara default, menjalankan doctor, dan menjalankan satu giliran agen OpenAI tiruan. Gunakan ulang tarball yang sudah dibangun dengan OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, lewati rebuild host dengan OPENCLAW_NPM_ONBOARD_HOST_BUILD=0, atau ganti channel dengan OPENCLAW_NPM_ONBOARD_CHANNEL=discord atau OPENCLAW_NPM_ONBOARD_CHANNEL=slack.

• Smoke perjalanan pengguna rilis: pnpm test:docker:release-user-journey memasang tarball OpenClaw yang sudah dikemas secara global di home Docker yang bersih, menjalankan onboarding, mengonfigurasi provider OpenAI tiruan, menjalankan satu giliran agen, memasang/menghapus Plugin eksternal, mengonfigurasi ClickClack terhadap fixture lokal, memverifikasi pengiriman pesan keluar/masuk, memulai ulang Gateway, dan menjalankan doctor.

• Smoke onboarding bertipe rilis: pnpm test:docker:release-typed-onboarding memasang tarball yang sudah dikemas, menjalankan openclaw onboard melalui TTY nyata, mengonfigurasi OpenAI sebagai provider env-ref, memverifikasi tidak ada persistensi kunci mentah, dan menjalankan satu giliran agen tiruan.

• Smoke media/memori rilis: pnpm test:docker:release-media-memory memasang tarball yang sudah dikemas, memverifikasi pemahaman gambar dari lampiran PNG, keluaran pembuatan gambar yang kompatibel dengan OpenAI, pengingatan pencarian memori, dan ketahanan pengingatan setelah Gateway dimulai ulang.

• Smoke perjalanan pengguna upgrade rilis: pnpm test:docker:release-upgrade-user-journey secara default memasang baseline terbitan terbaru yang lebih lama daripada tarball kandidat, mengonfigurasi status provider/Plugin/ClickClack pada paket terbitan, melakukan upgrade ke tarball kandidat, lalu menjalankan ulang perjalanan inti agen/Plugin/channel. Jika tidak ada baseline terbitan yang lebih lama, versi kandidat digunakan kembali. Timpa baseline dengan OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>.

• Smoke marketplace Plugin rilis: pnpm test:docker:release-plugin-marketplace memasang dari marketplace fixture lokal, memperbarui Plugin terpasang, menghapusnya, dan memverifikasi CLI Plugin menghilang dengan metadata pemasangan dipangkas.

• Smoke pemasangan Skill: pnpm test:docker:skill-install memasang tarball OpenClaw yang sudah dikemas secara global di Docker, menonaktifkan pemasangan arsip unggahan di config, me-resolve slug skill ClawHub live saat ini dari pencarian, memasangnya dengan openclaw skills install, dan memverifikasi skill terpasang beserta metadata origin/lock .clawhub.

• Smoke peralihan channel update: pnpm test:docker:update-channel-switch memasang tarball OpenClaw yang sudah dikemas secara global di Docker, beralih dari paket stable ke git dev, memverifikasi channel yang dipersistenkan dan pekerjaan Plugin pasca-update, lalu beralih kembali ke paket stable dan memeriksa status update.

• Smoke penyintas upgrade: pnpm test:docker:upgrade-survivor memasang tarball OpenClaw yang sudah dikemas di atas fixture pengguna lama yang kotor dengan agen, config channel, allowlist Plugin, status dependensi Plugin usang, dan file workspace/sesi yang sudah ada. Ini menjalankan update paket beserta doctor non-interaktif tanpa provider live atau kunci channel, lalu memulai Gateway loopback dan memeriksa pelestarian config/status beserta anggaran startup/status.

• Smoke penyintas upgrade terbitan: pnpm test:docker:published-upgrade-survivor secara default memasang openclaw@latest, menanam file pengguna yang sudah ada secara realistis, mengonfigurasi baseline tersebut dengan resep perintah bawaan, memvalidasi config yang dihasilkan, memperbarui pemasangan terbitan itu ke tarball kandidat, menjalankan doctor non-interaktif, menulis .artifacts/upgrade-survivor/summary.json, lalu memulai Gateway loopback dan memeriksa intent terkonfigurasi, pelestarian status, startup, /healthz, /readyz, dan anggaran status RPC. Timpa satu baseline dengan OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, minta scheduler agregat memperluas baseline lokal persis dengan OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS seperti openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, dan perluas fixture berbentuk isu dengan OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS seperti reported-issues; set reported-issues menyertakan configured-plugin-installs untuk perbaikan otomatis pemasangan Plugin OpenClaw eksternal. Package Acceptance mengeksposnya sebagai published_upgrade_survivor_baseline, published_upgrade_survivor_baselines, dan published_upgrade_survivor_scenarios, me-resolve token baseline meta seperti last-stable-4 atau all-since-2026.4.23, dan Full Release Validation memperluas gate paket release-soak menjadi last-stable-4 2026.4.23 2026.5.2 2026.4.15 plus reported-issues.

• Smoke konteks runtime sesi: pnpm test:docker:session-runtime-context memverifikasi persistensi transkrip konteks runtime tersembunyi beserta perbaikan doctor untuk cabang prompt-rewrite duplikat yang terdampak.

• Smoke pemasangan global Bun: bash scripts/e2e/bun-global-install-smoke.sh mengemas tree saat ini, memasangnya dengan bun install -g di home terisolasi, dan memverifikasi openclaw infer image providers --json mengembalikan provider gambar bawaan, bukan menggantung. Gunakan kembali tarball yang sudah dibangun dengan OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz, lewati build host dengan OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0, atau salin dist/ dari image Docker yang sudah dibangun dengan OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.

• Smoke Docker installer: bash scripts/test-install-sh-docker.sh berbagi satu cache npm di seluruh container root, update, dan direct-npm. Smoke update secara default memakai npm latest sebagai baseline stable sebelum upgrade ke tarball kandidat. Timpa dengan OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 secara lokal, atau dengan input update_baseline_version workflow Install Smoke di GitHub. Pemeriksaan installer non-root mempertahankan cache npm terisolasi agar entri cache milik root tidak menutupi perilaku pemasangan lokal pengguna. Atur OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache untuk menggunakan kembali cache root/update/direct-npm di antara rerun lokal.

• CI Install Smoke melewati update global direct-npm duplikat dengan OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; jalankan skrip secara lokal tanpa env tersebut saat cakupan direct npm install -g diperlukan.

• Smoke CLI hapus workspace bersama agen: pnpm test:docker:agents-delete-shared-workspace (skrip: scripts/e2e/agents-delete-shared-workspace-docker.sh) secara default membangun image Dockerfile root, menanam dua agen dengan satu workspace di home container terisolasi, menjalankan agents delete --json, dan memverifikasi JSON valid beserta perilaku workspace yang dipertahankan. Gunakan kembali image install-smoke dengan OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1.

• Jaringan Gateway (dua container, auth WS + health): pnpm test:docker:gateway-network (skrip: scripts/e2e/gateway-network-docker.sh)

• Smoke snapshot CDP browser: pnpm test:docker:browser-cdp-snapshot (skrip: scripts/e2e/browser-cdp-snapshot-docker.sh) membangun image E2E sumber plus layer Chromium, memulai Chromium dengan CDP mentah, menjalankan browser doctor --deep, dan memverifikasi snapshot peran CDP mencakup URL tautan, clickable yang dipromosikan kursor, ref iframe, dan metadata frame.

• Regresi reasoning minimal OpenAI Responses web_search: pnpm test:docker:openai-web-search-minimal (skrip: scripts/e2e/openai-web-search-minimal-docker.sh) menjalankan server OpenAI tiruan melalui Gateway, memverifikasi web_search menaikkan reasoning.effort dari minimal ke low, lalu memaksa penolakan schema provider dan memeriksa detail mentah muncul di log Gateway.

• Bridge channel MCP (Gateway tertanam + bridge stdio + smoke frame notifikasi Claude mentah): pnpm test:docker:mcp-channels (skrip: scripts/e2e/mcp-channels-docker.sh)

• Tool MCP bundel OpenClaw (server MCP stdio nyata + smoke allow/deny profil OpenClaw tertanam): pnpm test:docker:agent-bundle-mcp-tools (skrip: scripts/e2e/agent-bundle-mcp-tools-docker.sh)

• Pembersihan Cron/subagen MCP (Gateway nyata + teardown child MCP stdio setelah run cron terisolasi dan subagen one-shot): pnpm test:docker:cron-mcp-cleanup (skrip: scripts/e2e/cron-mcp-cleanup-docker.sh)

• Plugin (smoke install/update untuk path lokal, file:, registry npm dengan dependensi hoisted, metadata paket npm cacat, ref git bergerak, ClawHub kitchen-sink, update marketplace, dan enable/inspect Claude-bundle): pnpm test:docker:plugins (skrip: scripts/e2e/plugins-docker.sh) Atur OPENCLAW_PLUGINS_E2E_CLAWHUB=0 untuk melewati blok ClawHub, atau timpa pasangan paket/runtime kitchen-sink default dengan OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC dan OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Tanpa OPENCLAW_CLAWHUB_URL/CLAWHUB_URL, pengujian menggunakan server fixture ClawHub lokal hermetik.

• Smoke update Plugin tidak berubah: pnpm test:docker:plugin-update (skrip: scripts/e2e/plugin-update-unchanged-docker.sh)

• Smoke matriks siklus hidup Plugin: pnpm test:docker:plugin-lifecycle-matrix memasang tarball OpenClaw yang sudah dikemas di container kosong, memasang Plugin npm, mengaktifkan/menonaktifkan, melakukan upgrade dan downgrade melalui registry npm lokal, menghapus kode terpasang, lalu memverifikasi uninstall tetap menghapus status usang sambil mencatat metrik RSS/CPU untuk setiap fase siklus hidup.

• Smoke metadata reload config: pnpm test:docker:config-reload (skrip: scripts/e2e/config-reload-source-docker.sh)

• Plugin: pnpm test:docker:plugins mencakup smoke install/update untuk path lokal, file:, registry npm dengan dependensi hoisted, ref git bergerak, fixture ClawHub, update marketplace, dan enable/inspect Claude-bundle. pnpm test:docker:plugin-update mencakup perilaku update tidak berubah untuk Plugin terpasang. pnpm test:docker:plugin-lifecycle-matrix mencakup pemasangan Plugin npm yang dilacak sumber dayanya, enable, disable, upgrade, downgrade, dan uninstall saat kode hilang.

Untuk melakukan prebuild dan menggunakan kembali image fungsional bersama secara manual:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-buildOPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

Override image khusus suite seperti OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE tetap menang saat diatur. Saat OPENCLAW_SKIP_DOCKER_BUILD=1 mengarah ke image bersama remote, skrip menariknya jika belum lokal. Pengujian Docker QR dan installer mempertahankan Dockerfile masing-masing karena memvalidasi perilaku paket/pemasangan, bukan runtime aplikasi terbangun bersama.

Runner Docker model live juga melakukan bind-mount checkout saat ini secara read-only dan men-staging-nya ke workdir sementara di dalam container. Ini menjaga image runtime tetap ramping sambil tetap menjalankan Vitest terhadap sumber/konfigurasi lokal persis milik Anda. Langkah staging melewati cache besar yang hanya lokal dan output build aplikasi seperti .pnpm-store, .worktrees, __openclaw_vitest__, serta direktori output .build lokal aplikasi atau Gradle agar run live Docker tidak menghabiskan beberapa menit untuk menyalin artefak khusus mesin. Runner tersebut juga menyetel OPENCLAW_SKIP_CHANNELS=1 agar probe live gateway tidak memulai worker saluran Telegram/Discord/dll. nyata di dalam container. test:docker:live-models tetap menjalankan pnpm test:live, jadi teruskan juga OPENCLAW_LIVE_GATEWAY_* saat Anda perlu mempersempit atau mengecualikan cakupan live gateway dari lane Docker tersebut. test:docker:openwebui adalah smoke kompatibilitas tingkat lebih tinggi: ini memulai container gateway OpenClaw dengan endpoint HTTP yang kompatibel dengan OpenAI diaktifkan, memulai container Open WebUI yang dipin terhadap gateway tersebut, masuk melalui Open WebUI, memverifikasi /api/models mengekspos openclaw/default, lalu mengirim permintaan chat nyata melalui proxy /api/chat/completions milik Open WebUI. Setel OPENWEBUI_SMOKE_MODE=models untuk pemeriksaan CI jalur rilis yang harus berhenti setelah sign-in Open WebUI dan penemuan model, tanpa menunggu penyelesaian model live. Run pertama bisa terasa lebih lambat karena Docker mungkin perlu menarik image Open WebUI dan Open WebUI mungkin perlu menyelesaikan penyiapan cold-start miliknya sendiri. Lane ini mengharapkan kunci model live yang dapat digunakan. Sediakan melalui environment proses, profil auth yang di-staging, atau OPENCLAW_PROFILE_FILE eksplisit. Run yang berhasil mencetak payload JSON kecil seperti { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels sengaja deterministik dan tidak membutuhkan akun Telegram, Discord, atau iMessage nyata. Ini mem-boot container Gateway yang di-seed, memulai container kedua yang menjalankan openclaw mcp serve, lalu memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata lampiran, perilaku antrean event live, routing pengiriman keluar, serta notifikasi saluran + izin gaya Claude melalui bridge MCP stdio nyata. Pemeriksaan notifikasi menginspeksi frame MCP stdio mentah secara langsung sehingga smoke memvalidasi apa yang benar-benar dipancarkan bridge, bukan hanya apa yang kebetulan ditampilkan oleh SDK klien tertentu. test:docker:agent-bundle-mcp-tools deterministik dan tidak membutuhkan kunci model live. Ini membangun image Docker repo, memulai server probe MCP stdio nyata di dalam container, mewujudkan server tersebut melalui runtime MCP bundle OpenClaw tertanam, mengeksekusi tool, lalu memverifikasi coding dan messaging tetap mempertahankan tool bundle-mcp sementara minimal dan tools.deny: ["bundle-mcp"] memfilternya. test:docker:cron-mcp-cleanup deterministik dan tidak membutuhkan kunci model live. Ini memulai Gateway yang di-seed dengan server probe MCP stdio nyata, menjalankan giliran cron terisolasi dan satu giliran anak one-shot sessions_spawn, lalu memverifikasi proses anak MCP keluar setelah setiap run.

Smoke thread bahasa biasa ACP manual (bukan CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Pertahankan skrip ini untuk workflow regresi/debug. Ini mungkin diperlukan lagi untuk validasi routing thread ACP, jadi jangan hapus.

Env var berguna:

• OPENCLAW_CONFIG_DIR=... (default: ~/.openclaw) di-mount ke /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (default: ~/.openclaw/workspace) di-mount ke /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... di-mount dan di-source sebelum menjalankan tes
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 untuk memverifikasi hanya env var yang di-source dari OPENCLAW_PROFILE_FILE, menggunakan direktori konfigurasi/workspace sementara dan tanpa mount auth CLI eksternal
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (default: ~/.cache/openclaw/docker-cli-tools) di-mount ke /home/node/.npm-global untuk instalasi CLI yang di-cache di dalam Docker
• Direktori/file auth CLI eksternal di bawah $HOME di-mount read-only di bawah /host-auth..., lalu disalin ke /home/node/... sebelum tes dimulai
  • Direktori default: .minimax
  • File default: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Run penyedia yang dipersempit hanya me-mount direktori/file yang diperlukan, disimpulkan dari OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Timpa secara manual dengan OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none, atau daftar koma seperti OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... untuk mempersempit run
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... untuk memfilter penyedia di dalam container
• OPENCLAW_SKIP_DOCKER_BUILD=1 untuk menggunakan ulang image openclaw:local-live yang sudah ada bagi rerun yang tidak membutuhkan build ulang
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 untuk memastikan kredensial berasal dari penyimpanan profil (bukan env)
• OPENCLAW_OPENWEBUI_MODEL=... untuk memilih model yang diekspos oleh gateway untuk smoke Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... untuk menimpa prompt pemeriksaan nonce yang digunakan oleh smoke Open WebUI
• OPENWEBUI_IMAGE=... untuk menimpa tag image Open WebUI yang dipin

Pemeriksaan kewajaran dokumentasi

Jalankan pemeriksaan dokumentasi setelah edit dokumentasi: pnpm check:docs. Jalankan validasi anchor Mintlify penuh saat Anda juga membutuhkan pemeriksaan heading dalam halaman: pnpm docs:check-links:anchors.

Regresi offline (aman untuk CI)

Ini adalah regresi "pipeline nyata" tanpa penyedia nyata:

• Pemanggilan tool Gateway (mock OpenAI, gateway nyata + loop agen): src/gateway/gateway.test.ts (kasus: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Wizard Gateway (WS wizard.start/wizard.next, menulis konfigurasi + auth ditegakkan): src/gateway/gateway.test.ts (kasus: "runs wizard over ws and writes auth token config")

Evaluasi keandalan agen (Skills)

Kita sudah memiliki beberapa tes aman untuk CI yang berperilaku seperti "evaluasi keandalan agen":

• Pemanggilan tool mock melalui gateway nyata + loop agen (src/gateway/gateway.test.ts).
• Flow wizard end-to-end yang memvalidasi wiring sesi dan efek konfigurasi (src/gateway/gateway.test.ts).

Yang masih kurang untuk Skills (lihat Skills):

• Pengambilan keputusan: ketika skills dicantumkan dalam prompt, apakah agen memilih skill yang tepat (atau menghindari yang tidak relevan)?
• Kepatuhan: apakah agen membaca SKILL.md sebelum digunakan dan mengikuti langkah/argumen yang diwajibkan?
• Kontrak workflow: skenario multi-turn yang menegaskan urutan tool, penerusan riwayat sesi, dan batas sandbox.

Evaluasi mendatang harus tetap deterministik terlebih dahulu:

• Runner skenario yang menggunakan penyedia mock untuk menegaskan pemanggilan tool + urutan, pembacaan file skill, dan wiring sesi.
• Suite kecil skenario berfokus skill (gunakan vs hindari, gating, prompt injection).
• Evaluasi live opsional (opt-in, dijaga env) hanya setelah suite aman untuk CI tersedia.

Tes kontrak (bentuk Plugin dan saluran)

Tes kontrak memverifikasi bahwa setiap Plugin dan saluran terdaftar mematuhi kontrak antarmukanya. Tes ini mengiterasi semua Plugin yang ditemukan dan menjalankan suite asersi bentuk dan perilaku. Lane unit pnpm test default sengaja melewati file smoke dan seam bersama ini; jalankan perintah kontrak secara eksplisit saat Anda menyentuh surface saluran atau penyedia bersama.

Perintah

• Semua kontrak: pnpm test:contracts
• Hanya kontrak saluran: pnpm test:contracts:channels
• Hanya kontrak penyedia: pnpm test:contracts:plugins

Kontrak saluran

Berada di src/channels/plugins/contracts/*.contract.test.ts:

• plugin - Bentuk Plugin dasar (id, nama, kapabilitas)
• setup - Kontrak wizard penyiapan
• session-binding - Perilaku binding sesi
• outbound-payload - Struktur payload pesan
• inbound - Penanganan pesan masuk
• actions - Handler aksi saluran
• threading - Penanganan ID thread
• directory - API direktori/roster
• group-policy - Penegakan kebijakan grup

Kontrak status penyedia

Berada di src/plugins/contracts/*.contract.test.ts.

• status - Probe status saluran
• registry - Bentuk registry Plugin

Kontrak penyedia

Berada di src/plugins/contracts/*.contract.test.ts:

• auth - Kontrak flow auth
• auth-choice - Pilihan/seleksi auth
• catalog - API katalog model
• discovery - Penemuan Plugin
• loader - Pemuatan Plugin
• runtime - Runtime penyedia
• shape - Bentuk/antarmuka Plugin
• wizard - Wizard penyiapan

Kapan menjalankan

• Setelah mengubah ekspor atau subpath plugin-sdk
• Setelah menambahkan atau memodifikasi Plugin saluran atau penyedia
• Setelah me-refactor registrasi atau penemuan Plugin

Tes kontrak berjalan di CI dan tidak membutuhkan kunci API nyata.

Menambahkan regresi (panduan)

Saat Anda memperbaiki isu penyedia/model yang ditemukan secara live:

• Tambahkan regresi aman untuk CI jika memungkinkan (penyedia mock/stub, atau tangkap transformasi bentuk permintaan yang persis)
• Jika secara inheren hanya live (batas laju, kebijakan auth), pertahankan tes live tetap sempit dan opt-in melalui env var
• Lebih baik menargetkan layer terkecil yang menangkap bug:
  • bug konversi/replay permintaan penyedia → tes model langsung
  • bug pipeline sesi/riwayat/tool gateway → smoke live gateway atau tes mock gateway aman untuk CI
• Guardrail traversal SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts menurunkan satu target sampel per kelas SecretRef dari metadata registry (listSecretTargetRegistryEntries()), lalu menegaskan id exec segmen traversal ditolak.
  • Jika Anda menambahkan keluarga target SecretRef includeInPlan baru di src/secrets/target-registry-data.ts, perbarui classifyTargetClass dalam tes tersebut. Tes sengaja gagal pada id target yang tidak terklasifikasi agar kelas baru tidak dapat dilewati secara diam-diam.

Terkait

• Testing live
• Testing updates and plugins
• CI