--- read_when: - Menjalankan atau memperbaiki pengujian summary: Cara menjalankan pengujian secara lokal (vitest) dan kapan menggunakan mode paksa/cakupan title: Pengujian x-i18n: generated_at: "2026-07-12T14:38:26Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - Kit pengujian lengkap (suite, langsung, Docker): [Pengujian](/id/help/testing) - Validasi pembaruan dan paket Plugin: [Menguji pembaruan dan Plugin](/id/help/testing-updates-plugins) ## Default agen Sesi agen menjalankan pengujian dan validasi yang intensif secara komputasi dari jarak jauh melalui Crabbox. Kode pengelola tepercaya secara default menggunakan Blacksmith Testbox. Alur kerja Testbox yang dikonfigurasi memuat kredensial, sehingga kode kontributor tidak tepercaya atau kode fork harus menggunakan CI fork tanpa rahasia atau AWS Crabbox langsung yang disanitasi. Jika tugas kode tepercaya kemungkinan memerlukan pengujian atau pembuktian berat, lakukan pemanasan awal segera dalam sesi perintah latar belakang, lanjutkan pekerjaan selama proses pemuatan berlangsung, gunakan kembali id `tbx_...` yang dikembalikan, sinkronkan checkout saat ini pada setiap proses, dan hentikan sebelum serah terima: ```bash node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json ``` Setelah penggunaan ulang pertama berhasil, pembungkus mencatat basis lease, dependensi, dan sidik jari alur kerja Testbox di bawah `.crabbox/testbox-leases/`. Pengeditan khusus sumber tetap menggunakan ulang kotak yang telah dipanaskan. Perubahan basis penggabungan, lockfile, masukan pengelola paket, pembungkus, atau alur kerja Testbox akan ditutup saat gagal dan memerlukan lease baru. Setiap proses tetap menyinkronkan checkout saat ini. `OPENCLAW_TESTBOX_ALLOW_STALE=1` hanya untuk diagnostik yang disengaja, bukan pembuktian rilis. Perintah pengujian lokal di bawah ditujukan untuk alur kerja manusia atau fallback agen eksplisit yang diminta pengguna. Ketidaktersediaan penyedia jarak jauh harus dilaporkan; hal tersebut bukan izin untuk menjalankan gate lokal yang luas secara diam-diam. Untuk kode tidak tepercaya, lakukan pemanasan awal dengan `--provider aws`. Setiap proses harus menetapkan `CRABBOX_ENV_ALLOW=CI`, meneruskan `--provider aws --no-hydrate`, dan menggunakan `HOME` jarak jauh sementara yang baru sebelum memasang dependensi atau menjalankan pengujian. Gunakan lease yang baru dipanaskan dan dikhususkan untuk sumber tidak tepercaya tersebut; jangan pernah menggunakan ulang lease tepercaya atau yang sebelumnya telah dimuati. Jalankan biner Crabbox tepercaya yang telah terpasang dari checkout `main` tepercaya yang bersih dan ambil hanya PR jarak jauh dengan `--fresh-pr`; jangan pernah menjalankan pembungkus atau konfigurasi checkout tidak tepercaya secara lokal. Hapus penetapan `CRABBOX_AWS_INSTANCE_PROFILE` dan tutup saat gagal kecuali `aws.instanceProfile` yang dihasilkan kosong. Sebelum pemasangan/pengujian apa pun, gunakan alat berjalur absolut yang tepercaya untuk mewajibkan token IMDSv2, membuktikan bahwa endpoint kredensial IAM mengembalikan 404, dan memverifikasi bahwa `git rev-parse HEAD` jarak jauh sama dengan SHA lengkap head PR yang telah ditinjau. Ikat lease ke SHA tersebut dan hentikan/panaskan ulang saat head berubah. Unggah `scripts/crabbox-untrusted-bootstrap.sh` tepercaya dari `main` yang bersih bersama `--fresh-pr`; skrip tersebut memasang Node/pnpm yang disematkan, memverifikasi SHA dan penyematan pengelola paket, mengisolasi `HOME`, memasang dependensi, lalu menjalankan pengujian yang diminta. Jika broker tidak dapat membuktikan bahwa tidak ada peran atau tidak ada PR jarak jauh, gunakan CI fork tanpa rahasia. Jangan gunakan `hydrate-github`, `--no-sync`, atau alur kerja Testbox yang dimuati kredensial. Hapus penetapan semua penggantian `CRABBOX_TAILSCALE*`, paksa `--network public --tailscale=false`, bersihkan flag simpul keluar/LAN, dan wajibkan `crabbox inspect` untuk melaporkan jaringan publik tanpa status Tailscale sebelum mengunggah skrip apa pun. ## Urutan lokal rutin 1. `pnpm test:changed` untuk pembuktian Vitest dalam cakupan perubahan. 2. `pnpm test ` untuk satu berkas, direktori, atau target eksplisit. 3. `pnpm test` hanya ketika Anda sengaja memerlukan suite Vitest lokal lengkap. Dalam worktree Codex atau checkout tertaut/sparse, agen menghindari penggunaan langsung `pnpm test*` / `pnpm check*` / `pnpm crabbox:run` secara lokal: - Fallback lokal yang diminta pengguna secara eksplisit untuk berkas kecil: `node scripts/run-vitest.mjs `. - Gate perubahan atau pembuktian luas: `node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed` agar pnpm berjalan di dalam Testbox. - `exitCode` akhir dan JSON waktu dari pembungkus merupakan hasil perintah. Proses Blacksmith GitHub Actions yang didelegasikan mungkin menampilkan `cancelled` setelah perintah SSH berhasil karena Testbox dihentikan dari luar tindakan keepalive; periksa ringkasan pembungkus dan keluaran perintah sebelum menganggapnya sebagai kegagalan. - `OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree `: mempertahankan serialisasi pemeriksaan berat di dalam worktree saat ini, bukan di direktori umum Git, untuk perintah seperti `pnpm check:changed` dan `pnpm test ...` yang ditargetkan. Gunakan hanya pada host lokal berkapasitas tinggi ketika Anda sengaja menjalankan pemeriksaan independen di seluruh worktree tertaut. ## Perintah inti Proses pembungkus pengujian diakhiri dengan ringkasan singkat `[test] passed|failed|skipped ... in ...`; baris durasi Vitest sendiri tetap menjadi detail per shard. | Perintah | Fungsinya | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Target berkas/direktori eksplisit dirutekan melalui jalur Vitest yang tercakup. Proses tanpa target merupakan pembuktian suite lengkap: grup shard tetap diperluas menjadi konfigurasi daun untuk eksekusi paralel lokal, dengan fanout shard yang diharapkan dicetak sebelum dimulai. Grup ekstensi selalu diperluas menjadi konfigurasi shard per ekstensi, bukan satu proses proyek root raksasa. | | `pnpm test:changed` | Proses pengujian perubahan cerdas yang ringan: target presisi dari pengeditan pengujian langsung, berkas saudara `*.test.ts`, pemetaan sumber eksplisit, dan grafik impor lokal. Perubahan luas/konfigurasi/paket dilewati kecuali dipetakan ke pengujian presisi. | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | Proses pengujian perubahan luas yang eksplisit; gunakan ketika pengeditan harness/konfigurasi/paket pengujian harus kembali ke perilaku pengujian perubahan Vitest yang lebih luas. | | `pnpm test:force` | Membebaskan porta Gateway OpenClaw yang dikonfigurasi (default `18789`), lalu menjalankan suite lengkap dengan porta Gateway terisolasi agar pengujian server tidak bertabrakan dengan instans yang sedang berjalan. | | `pnpm test:coverage` | Menghasilkan laporan cakupan V8 informasional untuk jalur unit default (`vitest.unit.config.ts`); tidak ada ambang cakupan yang diberlakukan. | | `pnpm test:coverage:changed` | Cakupan unit hanya untuk berkas yang berubah sejak `origin/main`. | | `pnpm changed:lanes` | Menampilkan jalur arsitektur yang dipicu oleh diff terhadap `origin/main`. | | `pnpm check:changed` | Mendelegasikan ke Crabbox/Testbox secara default di luar CI, lalu menjalankan gate pemeriksaan perubahan cerdas di dalam turunan jarak jauh: pemformatan beserta pemeriksaan tipe, lint, dan perintah penjaga untuk jalur terdampak. Tidak menjalankan Vitest; gunakan `pnpm test:changed` atau `pnpm test ` untuk pembuktian pengujian. | ## Status pengujian bersama dan pembantu proses - `src/test-utils/openclaw-test-state.ts`: gunakan dari Vitest ketika pengujian memerlukan `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture konfigurasi, ruang kerja, direktori agen, atau penyimpanan profil autentikasi yang terisolasi. - `pnpm test:env-mutations:report`: laporan nonpemblokiran tentang pengujian/harness yang secara langsung memodifikasi `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_WORKSPACE_DIR`, atau kunci lingkungan terkait. Gunakan untuk menemukan kandidat migrasi ke pembantu status pengujian bersama. - `test/helpers/openclaw-test-instance.ts`: pengujian E2E tingkat proses yang memerlukan Gateway berjalan, lingkungan CLI, pengambilan log, dan pembersihan dalam satu tempat. - Jalur E2E Docker/Bash yang memuat `scripts/lib/docker-e2e-image.sh` dapat meneruskan `docker_e2e_test_state_shell_b64