Pengujian

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

• Apa yang dicakup setiap suite (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/provider.
• Cara menambahkan regresi untuk masalah model/provider dunia nyata.

# Mulai cepat

Sebagian besar hari:

• Gate penuh (diharapkan sebelum push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Jalankan suite penuh lokal lebih cepat di mesin dengan ruang memadai: pnpm test:max
• Loop watch Vitest langsung: pnpm test:watch
• Penargetan file langsung kini juga merutekan path ekstensi/kanal: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Utamakan run bertarget terlebih dahulu saat Anda mengiterasi satu kegagalan.
• Situs QA berbasis Docker: pnpm qa:lab:up
• Lane QA berbasis VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Saat Anda menyentuh pengujian atau ingin keyakinan ekstra:

• Gate cakupan: pnpm test:coverage
• Suite E2E: pnpm test:e2e

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

• Suite 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_gpt54=true untuk giliran agen openai/gpt-5.4 nyata atau deep_profile=true untuk artefak CPU/heap/trace Kova. Run terjadwal harian menerbitkan artefak lane mock-provider, deep-profile, dan GPT 5.4 ke openclaw/clawgrit-reports saat CLAWGRIT_REPORTS_TOKEN dikonfigurasi. Laporan mock-provider juga mencakup angka boot Gateway tingkat sumber, memori, plugin-pressure, hello-loop fake-model berulang, dan startup CLI.
• Sweep model live Docker: pnpm test:docker:live-models
  • Setiap model terpilih kini 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 provider.
  • Cakupan 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 di-shard menurut provider.
  • Untuk rerun CI terfokus, dispatch OpenClaw Live And E2E Checks (Reusable) dengan include_live_suites: true dan live_models_only: true.
  • Tambahkan secret provider baru bersinyal 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 lane 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, cron MCP, 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 lainnya: 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 diatur.
• Smoke perintah penyelamatan Crestodian: pnpm test:live:crestodian-rescue-channel
  • Pemeriksaan opt-in berlapis untuk permukaan perintah penyelamatan kanal pesan. Ini menjalankan /crestodian status, mengantrekan perubahan model persisten, membalas /crestodian yes, dan memverifikasi path tulis audit/konfigurasi.
• Smoke Docker perencana Crestodian: pnpm test:docker:crestodian-planner
  • Menjalankan Crestodian dalam kontainer tanpa konfigurasi dengan CLI Claude palsu di PATH dan memverifikasi fallback perencana fuzzy diterjemahkan menjadi penulisan konfigurasi bertipe yang diaudit.
• Smoke Docker first-run Crestodian: pnpm test:docker:crestodian-first-run
  • Memulai dari direktori state OpenClaw kosong, merutekan openclaw polos ke Crestodian, menerapkan setup/model/agen/Plugin Discord + penulisan SecretRef, memvalidasi konfigurasi, 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 diatur, 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 suite pengujian utama saat Anda memerlukan realisme QA-lab:

CI menjalankan QA Lab dalam workflow khusus. Paritas agentic berada 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 lane paritas mock, lane Matrix live, lane Telegram live yang dikelola Convex, dan lane Discord live yang dikelola Convex sebagai job paralel. QA terjadwal dan pemeriksaan rilis meneruskan Matrix --profile fast secara eksplisit, sedangkan CLI Matrix dan input workflow manual default tetap all; dispatch manual dapat memecah all menjadi job transport, media, e2ee-smoke, e2ee-deep, dan e2ee-cli. OpenClaw Release Checks menjalankan paritas plus lane Matrix cepat dan Telegram sebelum persetujuan rilis, menggunakan mock-openai/gpt-5.5 untuk pemeriksaan transport rilis agar tetap deterministik dan menghindari startup plugin provider normal. Gateway transport live ini menonaktifkan pencarian memori; perilaku memori tetap dicakup oleh suite 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 terpilih, 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 pada host.
  • Menjalankan beberapa skenario terpilih secara paralel secara default dengan worker gateway terisolasi. qa-channel default ke konkurensi 4 (dibatasi oleh jumlah skenario yang dipilih). Gunakan --concurrency <count> untuk menyesuaikan jumlah worker, atau --concurrency 1 untuk jalur serial lama.
  • Keluar non-zero ketika skenario apa pun 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 yang didukung AIMock untuk cakupan fixture eksperimental dan protocol-mock tanpa menggantikan jalur mock-openai yang sadar skenario.
• pnpm test:plugins:kitchen-sink-live
  • Menjalankan gauntlet Plugin Kitchen Sink OpenAI live melalui QA Lab. Ini menginstal paket Kitchen Sink eksternal, memverifikasi inventaris permukaan SDK Plugin, memeriksa /healthz dan /readyz, merekam bukti CPU/RSS gateway, menjalankan giliran OpenAI live, dan memeriksa diagnostik adversarial. Memerlukan autentikasi OpenAI live seperti OPENAI_API_KEY. Dalam sesi Testbox yang terhidrasi, ini otomatis mengambil profil live-auth Testbox ketika helper openclaw-testbox-env tersedia.
• pnpm test:gateway:cpu-scenarios
  • Menjalankan bench startup gateway ditambah paket kecil skenario QA Lab tiruan (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 berkelanjutan (--cpu-core-warn plus --hot-wall-warn-ms), sehingga lonjakan startup singkat dicatat sebagai metrik tanpa tampak seperti regresi gateway peg selama 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 pada host.
  • Menggunakan ulang flag pemilihan penyedia/model yang sama seperti qa suite.
  • Run live meneruskan input autentikasi QA yang didukung dan praktis untuk guest: kunci penyedia berbasis env, path config penyedia live QA, dan CODEX_HOME ketika tersedia.
  • Direktori output harus tetap berada di bawah root repo agar guest dapat menulis balik melalui workspace yang di-mount.
  • Menulis laporan + ringkasan QA normal ditambah log Multipass di bawah .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Memulai situs QA yang didukung 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 terpaket dimuat tanpa perbaikan dependensi startup, menjalankan doctor, dan menjalankan satu giliran agen lokal terhadap endpoint OpenAI tiruan.
  • Gunakan OPENCLAW_NPM_ONBOARD_CHANNEL=discord untuk menjalankan jalur packaged-install yang sama dengan Discord.
• pnpm test:docker:session-runtime-context
  • Menjalankan smoke Docker built-app deterministik untuk transkrip konteks runtime tertanam. Ini memverifikasi bahwa konteks runtime tersembunyi OpenClaw dipersistenkan sebagai pesan kustom non-display, alih-alih bocor ke giliran pengguna yang terlihat, lalu menanam JSONL sesi rusak yang terdampak dan memverifikasi openclaw doctor --fix menulis ulangnya ke cabang aktif dengan cadangan.
• pnpm test:docker:npm-telegram-live
  • Menginstal kandidat paket OpenClaw di Docker, menjalankan onboarding installed-package, mengonfigurasi Telegram melalui CLI terinstal, lalu menggunakan ulang jalur QA Telegram live dengan paket terinstal tersebut sebagai Gateway SUT.
  • Default ke OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; setel 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.
  • Menggunakan kredensial env Telegram atau sumber kredensial Convex yang sama seperti pnpm openclaw qa telegram. Untuk otomatisasi CI/rilis, setel OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex plus OPENCLAW_QA_CONVEX_SITE_URL dan secret peran. Jika OPENCLAW_QA_CONVEX_SITE_URL dan secret peran Convex tersedia di CI, wrapper Docker memilih Convex secara otomatis.
  • Wrapper memvalidasi env kredensial Telegram atau Convex pada host sebelum pekerjaan build/install Docker. Setel OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 hanya ketika sengaja men-debug penyiapan pra-kredensial.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer menimpa OPENCLAW_QA_CREDENTIAL_ROLE bersama hanya untuk jalur ini.
  • GitHub Actions mengekspos jalur 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 bukti produk side-run terhadap satu paket kandidat. Ini menerima ref tepercaya, spec npm yang dipublikasikan, 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 ada dengan profil jalur smoke, package, product, full, atau custom. Setel telegram_mode=mock-openai atau live-frontier untuk menjalankan workflow QA Telegram terhadap artefak package-under-test yang sama.
  • Bukti 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

• Bukti URL tarball persis memerlukan digest:

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

• Bukti 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 yang dikonfigurasi, lalu mengaktifkan channel/plugin terbundel melalui edit config.
  • Memverifikasi bahwa discovery penyiapan membiarkan plugin downloadable yang belum dikonfigurasi tetap tidak ada, perbaikan doctor terkonfigurasi pertama menginstal setiap plugin downloadable yang hilang secara eksplisit, dan restart kedua tidak menjalankan perbaikan dependensi tersembunyi.
  • Juga menginstal baseline npm lama yang diketahui, mengaktifkan Telegram sebelum menjalankan openclaw update --tag <candidate>, dan memverifikasi doctor pasca-update kandidat membersihkan sisa dependensi plugin lama tanpa perbaikan postinstall sisi harness.

• pnpm test:parallels:npm-update

  • Menjalankan smoke update packaged-install native lintas guest Parallels. Setiap platform terpilih pertama-tama menginstal paket baseline yang diminta, lalu menjalankan perintah openclaw update terinstal dalam 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 iterasi pada satu guest. Gunakan --json untuk path artefak ringkasan dan status per jalur.

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

  • Bungkus run lokal panjang dalam timeout host agar stall transport Parallels tidak menghabiskan sisa jendela pengujian:

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

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

  • 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 bersarang terus bergerak.

  • Jangan menjalankan wrapper agregat ini secara paralel dengan jalur smoke Parallels macOS, Windows, atau Linux individual. Mereka berbagi status VM dan dapat bertabrakan pada restore snapshot, penyajian paket, atau status gateway guest.

  • Bukti pasca-update menjalankan permukaan Plugin terbundel normal karena facade kapabilitas seperti speech, pembuatan gambar, dan pemahaman media dimuat melalui API runtime terbundel meskipun giliran agen itu sendiri hanya memeriksa respons teks sederhana.

• pnpm openclaw qa aimock

  • Hanya memulai server penyedia AIMock lokal untuk pengujian smoke protokol langsung.

• pnpm openclaw qa matrix

  • Menjalankan jalur QA live Matrix terhadap homeserver Tuwunel sekali pakai yang didukung Docker. Hanya source-checkout - instalasi terpaket tidak mengirimkan qa-lab.
  • CLI lengkap, katalog profil/skenario, env vars, dan tata letak artefak: QA Matrix.

• pnpm openclaw qa telegram

  • Menjalankan jalur QA live 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 pool bersama. Gunakan mode env secara default, atau setel OPENCLAW_QA_CREDENTIAL_SOURCE=convex untuk ikut menggunakan lease pool.
  • Keluar non-zero 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 observasi bot-ke-bot yang stabil, aktifkan Bot-to-Bot Communication Mode di @BotFather untuk kedua bot dan pastikan bot driver dapat mengamati traffic bot grup.
  • Menulis laporan QA Telegram, ringkasan, dan artefak observed-messages di bawah .artifacts/qa-e2e/.... Skenario balasan menyertakan RTT dari permintaan kirim driver hingga balasan SUT yang teramati.

Jalur transport live berbagi satu kontrak standar sehingga transport baru tidak menyimpang; matriks cakupan per jalur berada di Ikhtisar QA → Cakupan transport live. 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 openclaw qa telegram, QA lab memperoleh lease eksklusif dari pool yang didukung Convex, mengirim heartbeat lease tersebut saat jalur berjalan, dan melepas lease saat shutdown.

Scaffold proyek Convex referensi:

• qa/convex-credential-broker/

Env vars wajib:

• OPENCLAW_QA_CONVEX_SITE_URL (misalnya https://your-deployment.convex.site)
• Satu secret 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
  • Default env: OPENCLAW_QA_CREDENTIAL_ROLE (default ke ci di CI, selain itu maintainer)

Env vars opsional:

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

OPENCLAW_QA_CONVEX_SITE_URL harus menggunakan https:// dalam operasi normal.

Perintah admin maintainer (pool add/remove/list) memerlukan OPENCLAW_QA_CONVEX_SECRET_MAINTAINER secara khusus.

Helper CLI untuk maintainer:

pnpm openclaw qa credentials doctor
pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

Gunakan doctor sebelum live run untuk memeriksa URL situs Convex, broker secrets, prefiks endpoint, timeout HTTP, dan keterjangkauan admin/list tanpa mencetak nilai secret. Gunakan --json untuk keluaran yang dapat dibaca mesin dalam skrip dan utilitas CI.

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

• POST /acquire
  • Permintaan: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Berhasil: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Habis/dapat dicoba ulang: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /heartbeat
  • Permintaan: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Berhasil: { status: "ok" } (atau 2xx kosong)
• POST /release
  • Permintaan: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Berhasil: { status: "ok" } (atau 2xx kosong)
• POST /admin/add (hanya secret maintainer)
  • Permintaan: { kind, actorId, payload, note?, status? }
  • Berhasil: { status: "ok", credential }
• POST /admin/remove (hanya secret maintainer)
  • Permintaan: { credentialId, actorId }
  • Berhasil: { status: "ok", changed, credential }
  • Pelindung lease aktif: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (hanya secret maintainer)
  • Permintaan: { kind?, status?, includePayload?, limit? }
  • Berhasil: { 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 cacat.

# Menambahkan channel ke QA

Arsitektur dan nama helper skenario untuk adaptor channel baru berada di ringkasan QA → Menambahkan channel. Standar minimum: implementasikan transport runner pada seam host qa-lab bersama, deklarasikan qaRunners dalam manifes Plugin, mount 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 (default)

• Perintah: pnpm test
• Konfigurasi: run tanpa target menggunakan set shard vitest.full-*.config.ts dan dapat memperluas shard multi-proyek menjadi konfigurasi 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 dalam shard khusus unit-ui
• Cakupan:
  • Pengujian unit murni
  • Pengujian integrasi dalam proses (autentikasi Gateway, routing, tooling, parsing, konfigurasi)
  • Regresi deterministik untuk bug yang diketahui
• Ekspektasi:
  • Berjalan di CI
  • Tidak memerlukan kunci nyata
  • Harus cepat dan stabil
  • Pengujian resolver dan public-surface loader 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 berada dalam suite kontrak/integrasi milik Plugin.

# Stabilitas (Gateway)

• Perintah: pnpm test:stability:gateway
• Konfigurasi: vitest.gateway.config.ts, dipaksa ke satu worker
• Cakupan:
  • Memulai Gateway loopback nyata dengan diagnostik aktif secara default
  • Mendorong churn pesan gateway sintetis, memori, dan payload besar melalui path event diagnostik
  • Mengueri diagnostics.stability melalui RPC WS Gateway
  • Mencakup helper persistensi bundle stabilitas diagnostik
  • Menegaskan bahwa recorder tetap berbatas, sampel RSS sintetis tetap di bawah anggaran tekanan, dan kedalaman antrean per-sesi terkuras kembali ke nol
• Ekspektasi:
  • Aman untuk CI dan tanpa kunci
  • Jalur sempit untuk tindak lanjut regresi stabilitas, bukan pengganti suite Gateway penuh

# E2E (smoke Gateway)

• Perintah: pnpm test:e2e
• Konfigurasi: vitest.e2e.config.ts
• File: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts, dan pengujian E2E Plugin bawaan di bawah extensions/
• Default runtime:
  • Menggunakan threads Vitest dengan isolate: false, sesuai dengan bagian repo lainnya.
  • Menggunakan pekerja adaptif (CI: hingga 2, lokal: 1 secara default).
  • Berjalan dalam mode senyap secara default untuk mengurangi overhead I/O konsol.
• Override berguna:
  • OPENCLAW_E2E_WORKERS=<n> untuk memaksa jumlah pekerja (dibatasi hingga 16).
  • OPENCLAW_E2E_VERBOSE=1 untuk mengaktifkan kembali keluaran konsol verbose.
• Cakupan:
  • Perilaku end-to-end Gateway multi-instans
  • Permukaan WebSocket/HTTP, pemasangan node, dan jaringan yang lebih berat
• Ekspektasi:
  • Berjalan di CI (saat diaktifkan dalam pipeline)
  • Tidak memerlukan kunci asli
  • Lebih banyak komponen bergerak daripada pengujian unit (bisa lebih lambat)

# E2E: Smoke backend OpenShell

• Perintah: pnpm test:e2e:openshell
• File: extensions/openshell/src/backend.e2e.test.ts
• Cakupan:
  • Memulai Gateway OpenShell terisolasi pada host melalui Docker
  • Membuat sandbox dari Dockerfile lokal sementara
  • Menguji backend OpenShell OpenClaw melalui sandbox ssh-config nyata + eksekusi SSH
  • Memverifikasi perilaku filesystem remote-kanonis melalui bridge fs sandbox
• Ekspektasi:
  • Hanya opt-in; bukan bagian dari eksekusi default pnpm test:e2e
  • Memerlukan CLI openshell lokal plus daemon Docker yang berfungsi
  • Menggunakan HOME / XDG_CONFIG_HOME terisolasi, lalu menghancurkan Gateway dan 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 biner CLI non-default atau skrip wrapper

# Langsung (penyedia nyata + model nyata)

• Perintah: pnpm test:live
• Konfigurasi: vitest.live.config.ts
• File: src/**/*.live.test.ts, test/**/*.live.test.ts, dan pengujian langsung Plugin bawaan di bawah extensions/
• Default: diaktifkan oleh pnpm test:live (mengatur OPENCLAW_LIVE_TEST=1)
• Cakupan:
  • "Apakah penyedia/model ini benar-benar berfungsi hari ini dengan kredensial nyata?"
  • Menangkap perubahan format penyedia, keunikan pemanggilan tool, masalah autentikasi, dan perilaku batas laju
• Ekspektasi:
  • Sengaja tidak stabil untuk CI (jaringan nyata, kebijakan penyedia nyata, kuota, gangguan)
  • Memerlukan biaya / menggunakan batas laju
  • Lebih baik menjalankan subset yang dipersempit daripada "semuanya"
• Eksekusi langsung mengambil sumber dari ~/.profile untuk mengambil kunci API yang hilang.
• Secara default, eksekusi langsung tetap mengisolasi HOME dan menyalin materi konfigurasi/autentikasi ke home pengujian sementara agar fixture unit tidak dapat mengubah ~/.openclaw nyata Anda.
• Atur OPENCLAW_LIVE_USE_REAL_HOME=1 hanya saat Anda secara sengaja membutuhkan pengujian langsung untuk menggunakan direktori home nyata Anda.
• pnpm test:live sekarang default ke mode yang lebih senyap: mode ini mempertahankan keluaran progres [live] ..., tetapi menekan pemberitahuan tambahan ~/.profile dan membisukan log bootstrap Gateway/obrolan Bonjour. Atur OPENCLAW_LIVE_TEST_QUIET=0 jika Anda ingin log startup lengkap kembali.
• Rotasi kunci API (spesifik penyedia): 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-langsung melalui OPENCLAW_LIVE_*_KEY; pengujian mencoba ulang pada respons batas laju.
• Keluaran progres/Heartbeat:
  • Suite langsung kini memancarkan baris progres ke stderr sehingga panggilan penyedia yang lama tetap terlihat aktif meskipun penangkapan konsol Vitest senyap.
  • vitest.live.config.ts menonaktifkan intersepsi konsol Vitest sehingga baris progres penyedia/Gateway langsung mengalir selama eksekusi langsung.
  • 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 / pemasangan: tambahkan pnpm test:e2e
• Men-debug "bot saya mati" / kegagalan spesifik penyedia / pemanggilan tool: jalankan pnpm test:live yang dipersempit

# Pengujian langsung (menyentuh jaringan)

Untuk matriks model langsung, smoke backend CLI, smoke ACP, harness server aplikasi Codex, dan semua pengujian langsung penyedia media (Deepgram, BytePlus, ComfyUI, gambar, musik, video, harness media) - plus penanganan kredensial untuk eksekusi langsung - lihat Menguji suite langsung. Untuk checklist pembaruan khusus dan validasi Plugin, lihat Menguji pembaruan dan Plugin.

# Runner Docker (pemeriksaan opsional "berfungsi di Linux")

Runner Docker ini terbagi menjadi dua kelompok:

• Runner model langsung: test:docker:live-models dan test:docker:live-gateway hanya menjalankan file langsung profile-key yang sesuai 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 dan workspace Anda (serta mengambil sumber ~/.profile jika di-mount). Entrypoint lokal yang sesuai adalah test:live:models-profiles dan test:live:gateway-profiles.
• Runner langsung Docker default ke batas smoke yang lebih kecil agar sweep Docker penuh tetap praktis: test:docker:live-models default ke OPENCLAW_LIVE_MAX_MODELS=12, 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. Override variabel env tersebut saat Anda secara eksplisit menginginkan pemindaian menyeluruh yang lebih besar.
• test:docker:all membangun image Docker langsung 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 instal/pembaruan/dependensi-plugin; lane tersebut me-mount tarball yang sudah dibangun. Image fungsional menginstal tarball yang sama ke /app untuk lane fungsionalitas aplikasi yang dibangun. Definisi lane Docker berada di scripts/lib/docker-e2e-scenarios.mjs; logika perencana berada di scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs menjalankan rencana yang dipilih. Agregat menggunakan penjadwal lokal berbobot: OPENCLAW_DOCKER_ALL_PARALLELISM mengontrol slot proses, sementara batas sumber daya mencegah lane langsung berat, npm-install, dan multi-service semuanya dimulai sekaligus. Jika satu lane lebih berat daripada batas aktif, penjadwal tetap dapat memulainya saat pool kosong lalu membiarkannya berjalan sendiri hingga kapasitas tersedia lagi. Defaultnya adalah 10 slot, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=10, dan OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; sesuaikan OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT atau OPENCLAW_DOCKER_ALL_DOCKER_LIMIT hanya saat host Docker memiliki ruang lebih. Runner melakukan preflight Docker secara default, menghapus kontainer OpenClaw E2E 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 eksekusi berikutnya. Gunakan OPENCLAW_DOCKER_ALL_DRY_RUN=1 untuk mencetak manifes lane berbobot tanpa membangun atau menjalankan Docker, atau node scripts/test-docker-all.mjs --plan-json untuk mencetak rencana CI bagi lane terpilih, kebutuhan paket/image, dan kredensial.
• Package Acceptance adalah gate paket native GitHub untuk "apakah tarball yang dapat diinstal ini berfungsi sebagai produk?" Gate ini menyelesaikan satu paket 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 persis itu alih-alih mengemas ulang ref yang dipilih. Profil diurutkan berdasarkan keluasan: smoke, package, product, dan full. Lihat Menguji pembaruan dan Plugin untuk kontrak paket/pembaruan/Plugin, matriks survivor upgrade-terpublikasi, default rilis, dan triase kegagalan.
• Pemeriksaan build dan rilis menjalankan scripts/check-cli-bootstrap-imports.mjs setelah tsdown. Guard menelusuri graf bawaan statis dari dist/entry.js dan dist/cli/run-main.js dan gagal jika startup pra-dispatch mengimpor dependensi paket seperti Commander, UI prompt, undici, atau logging sebelum dispatch perintah; guard ini juga menjaga chunk eksekusi Gateway bawaan tetap di bawah anggaran dan menolak impor statis dari path Gateway dingin yang diketahui. Smoke CLI terpaketkan juga mencakup bantuan root, bantuan onboard, bantuan doctor, status, skema konfigurasi, 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 paket terkirim: entri inventaris QA privat yang dihilangkan, gateway install --wrapper yang hilang, file patch yang hilang dalam fixture git turunan tarball, update.channel persisten yang hilang, lokasi catatan instal Plugin legacy, persistensi catatan instal marketplace yang hilang, dan migrasi metadata konfigurasi selama plugins update. Untuk paket setelah 2026.4.25, path tersebut adalah kegagalan ketat.
• Runner smoke kontainer: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, 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:pi-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 beberapa kontainer nyata dan memverifikasi path integrasi tingkat lebih tinggi.

Runner Docker model langsung juga melakukan bind-mount hanya home autentikasi CLI yang dibutuhkan (atau semua yang didukung saat eksekusi tidak dipersempit), lalu menyalinnya ke home kontainer sebelum eksekusi 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 adalah jalur QA privat berbasis checkout sumber. Jalur ini sengaja tidak menjadi bagian dari jalur rilis Docker paket karena tarball npm tidak menyertakan QA Lab.
• Smoke langsung Open WebUI: pnpm test:docker:openwebui (skrip: scripts/e2e/openwebui-docker.sh)
• Wizard onboarding (TTY, scaffolding penuh): 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 yang telah dipaketkan secara global di Docker, mengonfigurasi OpenAI melalui onboarding env-ref plus Telegram secara default, menjalankan doctor, dan menjalankan satu giliran agen OpenAI tiruan. Gunakan kembali tarball yang sudah dibuat dengan OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, lewati build host dengan OPENCLAW_NPM_ONBOARD_HOST_BUILD=0, atau ganti channel dengan OPENCLAW_NPM_ONBOARD_CHANNEL=discord atau OPENCLAW_NPM_ONBOARD_CHANNEL=slack.
• Smoke pergantian channel pembaruan: pnpm test:docker:update-channel-switch menginstal tarball OpenClaw yang telah dipaketkan secara global di Docker, beralih dari paket stable ke git dev, memverifikasi channel tersimpan dan kerja Plugin pascapembaruan, lalu beralih kembali ke paket stable dan memeriksa status pembaruan.
• Smoke penyintas upgrade: pnpm test:docker:upgrade-survivor menginstal tarball OpenClaw yang telah dipaketkan di atas fixture pengguna lama yang kotor dengan agen, konfigurasi channel, daftar izinkan Plugin, status dependensi Plugin basi, dan file workspace/sesi yang sudah ada. Ini menjalankan pembaruan paket plus doctor noninteraktif tanpa provider langsung atau kunci channel, lalu memulai Gateway loopback dan memeriksa pelestarian konfigurasi/status plus anggaran startup/status.
• Smoke penyintas upgrade terpublikasi: pnpm test:docker:published-upgrade-survivor menginstal openclaw@latest secara default, menanam file pengguna yang ada secara realistis, mengonfigurasi baseline tersebut dengan resep perintah bawaan, memvalidasi konfigurasi yang dihasilkan, memperbarui instalasi terpublikasi tersebut ke tarball kandidat, menjalankan doctor noninteraktif, menulis .artifacts/upgrade-survivor/summary.json, lalu memulai Gateway loopback dan memeriksa intent yang dikonfigurasi, 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 [email protected] [email protected] [email protected], dan perluas fixture berbentuk issue dengan OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS seperti reported-issues; set reported-issues menyertakan configured-plugin-installs untuk perbaikan instalasi Plugin OpenClaw eksternal otomatis. Package Acceptance mengeksposnya sebagai published_upgrade_survivor_baseline, published_upgrade_survivor_baselines, dan published_upgrade_survivor_scenarios, menyelesaikan token meta baseline 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 plus perbaikan doctor untuk cabang prompt-rewrite duplikat yang terdampak.
• Smoke instalasi global Bun: bash scripts/e2e/bun-global-install-smoke.sh memaketkan pohon saat ini, menginstalnya dengan bun install -g di home terisolasi, dan memverifikasi openclaw infer image providers --json mengembalikan provider gambar bawaan alih-alih menggantung. Gunakan kembali tarball yang sudah dibuat 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 dibuat 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 miliknya. Smoke pembaruan secara default menggunakan npm latest sebagai baseline stabil sebelum meningkatkan ke tarball kandidat. Timpa dengan OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 secara lokal, atau dengan input update_baseline_version milik workflow Install Smoke di GitHub. Pemeriksaan installer non-root mempertahankan cache npm terisolasi agar entri cache milik root tidak menutupi perilaku instalasi lokal pengguna. Atur OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache untuk menggunakan kembali cache root/update/direct-npm di seluruh rerun lokal.
• CI Install Smoke melewati pembaruan global direct-npm duplikat dengan OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; jalankan skrip secara lokal tanpa env tersebut saat cakupan npm install -g langsung diperlukan.
• Smoke CLI hapus workspace bersama agen: pnpm test:docker:agents-delete-shared-workspace (skrip: scripts/e2e/agents-delete-shared-workspace-docker.sh) membuat image Dockerfile root secara default, menanam dua agen dengan satu workspace di home container terisolasi, menjalankan agents delete --json, dan memverifikasi JSON valid plus 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, autentikasi 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) membuat 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 skema provider dan memeriksa detail mentah muncul di log Gateway.
• Bridge channel MCP (Gateway tertanam + bridge stdio + smoke notification-frame Claude mentah): pnpm test:docker:mcp-channels (skrip: scripts/e2e/mcp-channels-docker.sh)
• Alat MCP bundel Pi (server MCP stdio nyata + smoke allow/deny profil Pi tertanam): pnpm test:docker:pi-bundle-mcp-tools (skrip: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Pembersihan MCP Cron/subagen (Gateway nyata + teardown child MCP stdio setelah cron terisolasi dan proses subagen sekali jalan): pnpm test:docker:cron-mcp-cleanup (skrip: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugin (smoke instalasi/pembaruan untuk path lokal, file:, registry npm dengan dependensi yang di-hoist, ref git bergerak, ClawHub kitchen-sink, pembaruan marketplace, dan aktifkan/periksa bundel Claude): 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 pembaruan Plugin tanpa perubahan: pnpm test:docker:plugin-update (skrip: scripts/e2e/plugin-update-unchanged-docker.sh)
• Smoke matriks lifecycle Plugin: pnpm test:docker:plugin-lifecycle-matrix menginstal tarball OpenClaw yang telah dipaketkan di container kosong, menginstal Plugin npm, mengalihkan enable/disable, meng-upgrade dan men-downgrade-nya melalui registry npm lokal, menghapus kode yang terinstal, lalu memverifikasi uninstall tetap menghapus status basi sambil mencatat metrik RSS/CPU untuk setiap fase lifecycle.
• Smoke metadata reload konfigurasi: pnpm test:docker:config-reload (skrip: scripts/e2e/config-reload-source-docker.sh)
• Plugin: pnpm test:docker:plugins mencakup smoke instalasi/pembaruan untuk path lokal, file:, registry npm dengan dependensi yang di-hoist, ref git bergerak, fixture ClawHub, pembaruan marketplace, dan aktifkan/periksa bundel Claude. pnpm test:docker:plugin-update mencakup perilaku pembaruan tanpa perubahan untuk Plugin yang terinstal. pnpm test:docker:plugin-lifecycle-matrix mencakup instalasi, enable, disable, upgrade, downgrade, dan uninstall kode hilang untuk Plugin npm dengan pelacakan sumber daya.

Untuk membuat sebelumnya dan menggunakan kembali image fungsional bersama secara manual:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_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 menunjuk ke image bersama jarak jauh, skrip akan menariknya jika belum ada secara lokal. Pengujian QR dan installer Docker mempertahankan Dockerfile mereka sendiri karena memvalidasi perilaku paket/instalasi, bukan runtime aplikasi yang sudah dibuat bersama.

Runner Docker model live juga melakukan bind-mount checkout saat ini secara read-only dan men-stage-nya ke workdir sementara di dalam kontainer. 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 keluaran build aplikasi seperti .pnpm-store, .worktrees, __openclaw_vitest__, serta direktori keluaran .build lokal aplikasi atau Gradle agar run live Docker tidak menghabiskan menit untuk menyalin artefak khusus mesin. Runner tersebut juga menetapkan OPENCLAW_SKIP_CHANNELS=1 agar probe live gateway tidak memulai worker kanal Telegram/Discord/dll. nyata di dalam kontainer. 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: ia memulai kontainer Gateway OpenClaw dengan endpoint HTTP yang kompatibel dengan OpenAI diaktifkan, memulai kontainer 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. 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, dan OPENCLAW_PROFILE_FILE (~/.profile secara default) adalah cara utama untuk menyediakannya dalam run yang di-Docker-kan. Run yang berhasil mencetak payload JSON kecil seperti { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels sengaja deterministik dan tidak memerlukan akun Telegram, Discord, atau iMessage nyata. Ia mem-boot kontainer Gateway yang telah di-seed, memulai kontainer kedua yang men-spawn openclaw mcp serve, lalu memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata lampiran, perilaku antrean event live, routing pengiriman keluar, serta notifikasi kanal + izin bergaya Claude melalui bridge MCP stdio nyata. Pemeriksaan notifikasi memeriksa frame MCP stdio mentah secara langsung sehingga smoke memvalidasi apa yang benar-benar dipancarkan bridge, bukan hanya apa yang kebetulan ditampilkan SDK klien tertentu. test:docker:pi-bundle-mcp-tools deterministik dan tidak memerlukan kunci model live. Ia membangun image Docker repo, memulai server probe MCP stdio nyata di dalam kontainer, mematerialisasikan server tersebut melalui runtime MCP bundle Pi tertanam, mengeksekusi tool, lalu memverifikasi coding dan messaging mempertahankan tool bundle-mcp sementara minimal dan tools.deny: ["bundle-mcp"] memfilternya. test:docker:cron-mcp-cleanup deterministik dan tidak memerlukan kunci model live. Ia memulai Gateway yang telah di-seed dengan server probe MCP stdio nyata, menjalankan giliran cron terisolasi dan giliran anak one-shot /subagents spawn, lalu memverifikasi proses anak MCP keluar setelah setiap run.

Smoke thread bahasa sederhana ACP manual (bukan CI):

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

Variabel lingkungan 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=... (default: ~/.profile) di-mount ke /home/node/.profile dan di-source sebelum menjalankan tes
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 untuk memverifikasi hanya variabel lingkungan yang di-source dari OPENCLAW_PROFILE_FILE, menggunakan direktori konfigurasi/workspace sementara dan tanpa mount autentikasi 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 autentikasi 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 provider yang dipersempit hanya me-mount direktori/file yang diperlukan, yang 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 provider di dalam kontainer
• OPENCLAW_SKIP_DOCKER_BUILD=1 untuk menggunakan kembali image openclaw:local-live yang ada untuk rerun yang tidak memerlukan 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

# Sanitas docs

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

# Regresi offline (aman untuk CI)

Ini adalah regresi "pipeline nyata" tanpa provider nyata:

• Pemanggilan tool Gateway (OpenAI tiruan, 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 + autentikasi ditegakkan): src/gateway/gateway.test.ts (kasus: "runs wizard over ws and writes auth token config")

# Evaluasi reliabilitas agen (skills)

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

• Pemanggilan tool tiruan melalui gateway nyata + loop agen (src/gateway/gateway.test.ts).
• Alur 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: saat skills tercantum 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 alur kerja: skenario multi-giliran yang menegaskan urutan tool, penerusan riwayat sesi, dan batas sandbox.

Evaluasi mendatang harus tetap deterministik terlebih dahulu:

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

# Tes kontrak (bentuk plugin dan kanal)

Tes kontrak memverifikasi bahwa setiap plugin dan kanal 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 permukaan kanal atau provider bersama.

# Perintah

• Semua kontrak: pnpm test:contracts
• Hanya kontrak kanal: pnpm test:contracts:channels
• Hanya kontrak provider: pnpm test:contracts:plugins

# Kontrak kanal

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

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

# Kontrak status provider

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

• status - Probe status kanal
• registry - Bentuk registry Plugin

# Kontrak provider

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

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

# Kapan menjalankan

• Setelah mengubah ekspor atau subpath plugin-sdk
• Setelah menambahkan atau memodifikasi plugin kanal atau provider
• Setelah merefaktor registrasi atau penemuan plugin

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

# Menambahkan regresi (panduan)

Saat Anda memperbaiki masalah provider/model yang ditemukan secara live:

• Tambahkan regresi aman untuk CI jika memungkinkan (provider mock/stub, atau tangkap transformasi bentuk permintaan persisnya)
• Jika secara inheren hanya live (batas laju, kebijakan autentikasi), pertahankan tes live tetap sempit dan opt-in melalui variabel lingkungan
• Lebih suka menargetkan lapisan terkecil yang menangkap bug:
  • bug konversi/replay permintaan provider → 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 ini sengaja gagal pada id target yang tidak terklasifikasi agar kelas baru tidak dapat dilewati secara diam-diam.

# Terkait

• Menguji live
• Menguji pembaruan dan plugin
• CI