Langsung ke konten utama
Anda dapat menulis tes otomatis untuk mod dan menjalankannya dari shell Anda dengan claude plugin test. Tes menaikkan peristiwa yang ditangani hook Anda dan memeriksa apa yang dilakukan hook, sehingga Anda menangkap masalah sebelum mencapai sesi. Contoh pertama menguji mod dari Buat mod.

Menulis pengujian

Sebuah pengujian memuat mod Anda, mengirimkan event melalui hook-nya seperti yang dilakukan Claude Code, dan memeriksa apa yang dilakukan hook tersebut, tanpa sesi, tanpa masuk, dan tanpa jaringan. Anda menjalankan pengujian dari shell dengan claude plugin test, dan setiap file pengujian mengimpor test kit, sebuah pustaka pengujian dalam modul claude-code/testing. Beri setiap file pengujian nama yang diakhiri dengan .test.ts, seperti first-mod.test.ts, dan simpan di mana saja di dalam direktori plugin. Setiap file pengujian memerlukan setidaknya satu test(), atau eksekusi gagal dengan declares no test(): nothing ran. Sebuah file pengujian dapat mengimpor file milik mod Anda sendiri dan helper .ts di sebelahnya, sehingga Anda dapat melakukan unit test pada fungsi biasa, seperti aturan sebuah permainan, tanpa kit tersebut. Pengujian ini memicu dua panggilan tool, menjalankan perintah /tally dari Membuat mod, dan memeriksa bahwa balasannya menghitung keduanya. Baris pertamanya adalah sebuah stub, yang menjawab panggilan tool sebagai pengganti Claude Code. Simpan sebagai first-mod/tests/first-mod.test.ts:
first-mod/tests/first-mod.test.ts
Di shell Anda, jalankan pengujian dari direktori first-mod:
Output menyebutkan setiap pengujian dan apakah pengujian tersebut lulus, dengan waktu yang bervariasi dari satu eksekusi ke eksekusi lainnya:
Setiap $.tool.call melewati hook tool.call milik mod, yang menambahkan satu ke hitungannya dan meneruskan panggilan tersebut ke stub. Tidak ada ls yang dijalankan dan tidak ada file yang dibaca. $.command.run kemudian menuju hook command.run milik mod, dan answer adalah objek yang dikembalikan oleh hook tersebut. Perintah ini keluar dengan status 1 ketika sebuah pengujian gagal, sehingga dapat digunakan di CI. Jika mod Anda sendiri tidak dapat dimuat di shell yang menjalankannya, perintah ini mencetak baris yang diawali dengan claude plugin test: hooks modules are turned off beserta alasannya, dan keluar dengan status 1.

Stub untuk apa yang akan dijawab Claude Code

Tidak ada model, store, atau tool yang berjalan dalam pengujian, sehingga di mana pun mod Anda mengharapkan Claude Code menjawab, pengujian menyediakan jawabannya dengan stub. Sebuah fungsi pengujian menerima dua argumen untuk itu:
  • $: $ milik pengujian itu sendiri, yang berperan sebagai Claude Code. Ini bukan mods API yang diterima oleh hook. Setiap metodenya memicu event dengan nama yang sama, mengirimkannya melalui hook mod Anda, dan di-resolve ke hasilnya: $.tool.call({ tool: 'Bash', command: 'ls' }) memicu tool.call. $.command.run, $.prompt.submit, $.session.start, dan $.turn.complete bekerja dengan cara yang sama, dan $.classic.Stop serta metode $.classic lainnya memicu event hook pengaturan. Sebuah pengujian tidak dapat memicu panggilan mods API seperti ui.close secara langsung. Picu melalui mod Anda, misalnya dengan menekan tombol yang menutup panel.
  • on: panggil untuk mendaftarkan stub, yaitu hook yang menjawab sebagai pengganti Claude Code. Beri nama stub untuk panggilan mods API tanpa $., sehingga stub yang didaftarkan sebagai store.get menjawab $.store.get milik mod Anda. Ketika mod Anda memanggil $.model.complete atau $.store.get, sebuah stub menyediakan jawabannya.
Contoh ini membuat stub untuk panggilan model. Hook ini milik mod bernama grader, dan menangani perintah /grade yang mengirimkan sebuah kalimat ke model dan melaporkan apakah balasannya diawali dengan PASS. File ini hanya berisi hook yang diuji, sehingga mod juga memerlukan plugin.json dan hooks.json, seperti di Membuat mod. Untuk mengetik /grade dalam sebuah sesi, mod juga harus mendaftarkan perintah tersebut:
grader/hooks/register.js
Pengujian ini membuat stub untuk panggilan model guna memeriksa apa yang dilakukan hook dengan balasan yang lulus:
grader/tests/grader.test.ts
Pengujian ini lulus karena reply milik hook adalah objek di bawah value, yang text-nya diawali dengan PASS. Untuk memeriksa cabang lainnya, tambahkan pengujian kedua yang stub-nya mengembalikan text yang diawali dengan FAIL, dan harapkan Try again. Stub untuk panggilan mods API mengembalikan objek dengan field value, yang berisi nilai yang menjadi hasil resolve panggilan tersebut di mod Anda: { value: 7 } membuat $.store.get di-resolve ke 7. Stub untuk salah satu event Claude Code, seperti turn.step atau tool.call, mengembalikan hasil milik event tersebut, seperti { result: 'ok' }. $.session.send dan $.prompt.fill juga menggunakan hasil event-nya, seperti yang ditunjukkan tabel. Mencari apa yang dikembalikan stub menunjukkan bentuk mana yang digunakan oleh setiap nama umum. Error berikut berarti sebuah stub salah atau tidak ada. Output pengujian yang gagal menyertakan blok berjudul the engine reported:, dan setiap error muncul di sana:
  • returned neither { value } nor { deny }: stub untuk panggilan mods API mengembalikan nilai polos, yang membuat pengujian gagal
  • no implementation for diikuti sebuah nama: mod Anda melakukan panggilan tersebut dan tidak ada stub yang menjawabnya
Kit ini juga mengekspor mock siap pakai untuk jam, store, environment variable, dan baris yang ditambahkan ke percakapan:
  • mock.clock(on): menjawab $.clock dan mengembalikan jam tiruan yang dimajukan oleh pengujian Anda, sehingga pengujian sebuah timer tidak perlu menunggu.
  • mock.store(on, { count: 7 }): menjawab $.store dari store yang dimulai dengan entri tersebut. Mock ini tidak mengembalikan apa pun, jadi untuk memeriksa apa yang disimpan mod Anda, tulis sendiri dua stub store seperti yang dilakukan pengujian gambar.
  • mock.env(on, { CI: 'true' }): menjawab $.env.get dari variabel tersebut.
  • mock.session(on): mengembalikan sesi tiruan yang metode appended()-nya mencantumkan baris yang ditambahkan mod Anda dengan $.session.append, dari yang terlama; mock ini memerlukan Claude Code v2.1.293 atau yang lebih baru.

Mengikuti aturan test kit

  • Daftarkan setiap stub sebelum panggilan pertama pengujian pada $. Memanggil on setelah itu akan melempar error seperti on("ui.render") after the test first called $.
  • session.start tidak berjalan dengan sendirinya. Setiap pengujian dimulai dengan modul Anda yang baru dimuat dan belum ada hook-nya yang dipanggil, sehingga variabel tingkat modul menyimpan nilai awalnya. Jika sebuah hook bergantung pada apa yang disiapkan oleh session.start, picu terlebih dahulu:
    Stub kedua menjawab panggilan $.command.register yang dilakukan oleh hook session.start seperti milik tutorial. Tanpanya, panggilan tersebut ditolak dengan no implementation for command.register dan kit melewati hook Anda, sehingga tidak ada apa pun setelah panggilan tersebut di dalam hook yang berjalan. Pengujian tidak gagal pada titik itu. Hook yang dilewati dicantumkan di bawah the engine reported: hanya jika pemeriksaan berikutnya gagal.
  • Daftarkan stub ui.render untuk memilih apa yang dikembalikan next(e). Ketika hook ui.render Anda mengembalikan next(e), misalnya untuk tidak menggambar apa pun saat Claude sedang idle, pemasangan berhasil tanpa stub. Agar next(e) mengembalikan elemen yang Anda pilih, daftarkan stub yang mengembalikannya sebagai data polos:
    Di tempat situs tersebut dapat menggambar elemen itu, ui.find({ type: 'Text' }) mengembalikannya ketika hook Anda mengembalikan next(e). Pada v2.1.323 atau yang lebih baru, untuk band, berikan nama mod Anda sebagai argumen kedua untuk on, seperti dalam { plugin: 'my-mod' }. Tanpanya, stub tidak menjawab next(e) Anda. Sebelum v2.1.321, pemasangan gagal dengan no implementation for ui.render kecuali Anda mendaftarkan stub tersebut.
  • Stub untuk turn.step adalah async generator, dan pengujian membaca stream hingga akhir untuk mendapatkan hasilnya:
    Ketika loop berakhir, result adalah objek yang dikembalikan stub, setelah hook turn.step Anda berkesempatan mengubahnya. Di sini result.answer bernilai 'ok'.
  • Picu panggilan tool dengan nama tool dan argumennya sebagai field, seperti await $.tool.call({ tool: 'Bash', command: 'ls' }), dan daftarkan stub tool.call yang mengembalikan { result }.

Mencari apa yang dikembalikan stub

Setiap panggilan mods API yang dilakukan mod Anda dalam pengujian memerlukan stub yang menjawab sebagai pengganti Claude Code, kecuali beberapa yang dijawab oleh kit itu sendiri: panggilan $.ui.invalidate, $.state, dan $.session.append. Untuk panggilan $.clock, gunakan mock.clock(on), atau $.clock.now() milik mod Anda gagal dengan no implementation for clock.now. Tabel ini mencantumkan yang paling sering digunakan mod. Kolom pertama adalah panggilan yang dilakukan mod Anda atau event yang diteruskannya dengan next(e). Kolom kedua adalah fungsi yang diberikan ke on dengan nama tersebut, sehingga baris $.store.get menjadi on('store.get', ($, e) => ({ value: saved.get(e.key) })). Sebuah '...' dalam stub menandai teks yang perlu Anda isi:

Memeriksa hasil dengan expect

expect memiliki kumpulan asersinya sendiri, seperti toEqual dan toHaveLength, yang ditempatkan setelah nilai yang sedang Anda periksa, seperti dalam expect(answer.text).toBe('ok'). Untuk daftar lengkapnya, cari type Matchers di claude-code/index.d.ts dalam tipe untuk build Anda. Letakkan .not sebelum asersi untuk memeriksa kebalikannya. Untuk memeriksa nilai akhir sebuah promise, letakkan .resolves atau .rejects tepat setelah expect(...) dan gunakan await pada baris tersebut, seperti dalam await expect(promise).rejects.toThrow(). Ketika sebuah expect gagal di dalam stub atau hook yang Anda berikan ke on sebagai fungsi biasa, bukan sebagai async generator, pengujian gagal. Engine melewati hook tersebut, dan output kegagalan menyebutkannya, seperti in the test's store.set hook.

Uji coba timer

Mod yang menjalankan pekerjaan pada timer memerlukan jam yang dikontrol tes, sehingga tes dapat memajukan waktu alih-alih menunggu. const clock = mock.clock(on) mengembalikan jam mock yang dimulai pada 0 dan bergerak hanya ketika tes Anda memindahkannya. Untuk memulai pada waktu lain, teruskan dalam milidetik, seperti dalam mock.clock(on, { now: 5000 }). Jam memiliki metode ini: Hook ini milik mod bernama countdown, dan menangani perintah /countdown yang mengambil jumlah detik, memulai timer $.clock.every satu detik, dan menunjukkan toast pada nol. Seperti dengan grader, file hanya menyimpan hook yang diuji dan tidak mendaftarkan perintah:
countdown/hooks/register.js
Tes ini menjalankan /countdown 3 dan memajukan jam mock, sehingga memeriksa tiga detik perilaku tanpa menunggu tiga detik:
countdown/tests/countdown.test.ts
expect pertama menunjukkan bahwa toast tidak datang lebih awal, dan yang kedua menunjukkan bahwa itu datang sekali. Setiap advance menyelesaikan setelah timer yang jatuh tempo telah berjalan, sehingga pemeriksaan pada baris berikutnya melihat efeknya.

Uji coba gambar

Tes dapat menggambar salah satu situs render mod Anda, kemudian menekan, mengetik ke, dan menemukan elemen yang digambarnya. $.ui.mount menggambar situs melalui hook ui.render mod Anda dan mengembalikan handle dengan metode untuk masing-masing. Untuk mencakup beberapa aplikasi dalam satu tes, atur surface ke aplikasi untuk digambar. Tes ini membuka panel dari Bangun panel dengan tab, beralih tab, menekan tombol, dan memeriksa hitungan di terminal dan aplikasi Desktop:
hello-tabs/tests/hello-tabs.test.ts
Di shell Anda, jalankan claude plugin test dari direktori hello-tabs. Tes lulus ketika kedua aplikasi menggambar garis hitungan dan mod telah menyimpan 2. Hitungan dibawa dari aplikasi pertama ke yang kedua karena kedua pemasangan menggunakan modul yang dimuat sama. Handle yang dikembalikan $.ui.mount memiliki metode ini, yang mengatasi elemen berdasarkan key yang Anda berikan: Setiap metode menyelesaikan setelah handler Anda selesai, sehingga Anda dapat memeriksa hasil pada baris berikutnya. Atur props ke apa yang akan dilewatkan Claude Code untuk situs itu. Tabel situs render mencantumkan props setiap situs, dan tipe untuk build Anda memiliki tipe mereka. Untuk menangkap pohon elemen yang tidak valid untuk aplikasi yang Anda sebutkan di surface, periksa dengan find elemen yang ditambahkan hook Anda. Tes tidak memeriksa bagaimana aplikasi melukis pohon, jadi lihat tata letak baru dalam sesi nyata juga.

Uji coba gambar setelah /clear

Setiap tes dimulai dengan setiap nilai $.state pada default-nya, yang merupakan cara /clear meninggalkannya. Untuk menguji apa yang dilakukan mod Anda selanjutnya, lewati session.start, picu classic.SessionStart dengan source: 'clear', dan periksa apa yang digambar mod Anda. Tes ini memeriksa modul dari Muat nilai yang disimpan lagi setelah /clear. Tambahkan ke file dari Uji coba gambar, di mana PANE didefinisikan. Tes pertama file itu mengharapkan tombol untuk menyimpan hitungan, seperti tombol dalam Simpan dari lebih dari satu sesi:
hello-tabs/tests/hello-tabs.test.ts
Tes lulus ketika hook classic.SessionStart Anda telah menyalin 7 yang disimpan ke $.state sebelum panel menggambar. Tanpa hook itu dalam modul Anda, panel menggambar Count: 0, find mengembalikan undefined, dan tes gagal di toBeDefined.

Uji coba mod kebijakan

Mod yang tercantum organisasi Anda dalam prependPlugins dapat menolak mod lain sebelum dimuat. Untuk menguji satu, atur tier mod Anda dan berikan tes mod kedua untuk diizinkan atau ditolak oleh mod Anda:
  • tier: panggil sekali di bagian atas file tes, seperti dalam tier('prepend'), untuk memuat mod Anda sebagai prepend, append, atau builtin, tempatnya dalam urutan mod berjalan. Tanpa itu, mod Anda memuat sebagai user.
  • plugins: teruskan test objek opsi di depan badan tes. Array plugins menyimpan mod yang Anda tulis inline, masing-masing dengan name dan fungsi register. Untuk memuat satu di tempat lain selain user, tambahkan tier ke itu.
File tes ini memuat mod kebijakan dari halaman admin terlebih dahulu. Itu memeriksa bahwa mod kebijakan menolak mod yang memulai proses dan mengizinkan yang tidak:
acme-guard/tests/guard.test.ts
Di shell Anda, jalankan claude plugin test dari direktori acme-guard. Kedua tes lulus dengan mod kebijakan seperti yang ditunjukkan halaman admin. Kit memuat setiap mod pada panggilan pertama tes pada $. Ketika mod Anda menolak satu, panggilan itu melempar, dan pesan menamai mod yang ditolak, mod yang menolaknya, dan alasan Anda. Dalam tes kedua tidak ada yang ditolak, jadi reader menjawab panggilan alat sebelum mencapai stub.

Langkah berikutnya