claude plugin test. Una prueba dispara los eventos que manejan tus hooks y verifica lo que hicieron los hooks, para que detectes un problema antes de que llegue a una sesión. El primer ejemplo prueba el mod de Crear un mod.
Escribir una prueba
Una prueba carga tu mod, envía eventos a través de sus hooks como lo haría Claude Code y comprueba lo que hicieron los hooks, sin una sesión, sin iniciar sesión y sin red. Ejecutas las pruebas desde tu shell conclaude plugin test, y cada archivo de prueba importa el kit de pruebas, una biblioteca de pruebas en el módulo claude-code/testing.
Dale a cada archivo de prueba un nombre que termine en .test.ts, como first-mod.test.ts, y guárdalo en cualquier lugar del directorio del plugin. Cada archivo de prueba necesita al menos un test(), o la ejecución falla con declares no test(): nothing ran. Un archivo de prueba puede importar los archivos propios de tu mod y los helpers .ts vecinos, así que puedes hacer pruebas unitarias de funciones simples, como las reglas de un juego, sin el kit.
Esta prueba dispara dos llamadas a herramientas, ejecuta el comando /tally de Crear un mod y comprueba que la respuesta cuente ambas. Su primera línea es un stub, que responde a las llamadas a herramientas en lugar de Claude Code. Guárdala como first-mod/tests/first-mod.test.ts:
first-mod/tests/first-mod.test.ts
first-mod:
$.tool.call pasó por el hook tool.call del mod, que sumó uno a su conteo y pasó la llamada al stub. No se ejecutó ningún ls ni se leyó ningún archivo. Luego $.command.run fue al hook command.run del mod, y answer es el objeto que devolvió ese hook.
El comando termina con estado 1 cuando una prueba falla, así que funciona en CI. Si tus propios mods no pueden cargarse en el shell que lo ejecuta, imprime una línea que empieza con claude plugin test: hooks modules are turned off con el motivo y termina con estado 1.
Crear stubs para lo que respondería Claude Code
En una prueba no se ejecuta ningún modelo, almacén ni herramienta, así que dondequiera que tu mod espere que Claude Code responda, la prueba proporciona la respuesta con un stub. Una función de prueba recibe dos argumentos para eso:$: el$propio de la prueba, que actúa como Claude Code. No es la API de mods que recibe un hook. Cada uno de sus métodos dispara el evento del mismo nombre, lo envía a través de los hooks de tu mod y se resuelve con el resultado:$.tool.call({ tool: 'Bash', command: 'ls' })disparatool.call.$.command.run,$.prompt.submit,$.session.starty$.turn.completefuncionan de la misma manera, y$.classic.Stopy los demás métodos$.classicdisparan un evento de hook de configuración. Una prueba no puede disparar directamente una llamada a la API de mods comoui.close. Desencadénala a través de tu mod, por ejemplo presionando el botón que cierra el panel.on: llámalo para registrar stubs, que son hooks que responden en lugar de Claude Code. Nombra un stub para una llamada a la API de mods sin el$., así que un stub registrado comostore.getresponde al$.store.getde tu mod. Cuando tu mod llama a$.model.completeo$.store.get, un stub proporciona la respuesta.
grader y maneja un comando /grade que envía una oración a un modelo e informa si la respuesta empieza con PASS. El archivo contiene solo el hook bajo prueba, así que el mod también necesita un plugin.json y un hooks.json, como en Crear un mod. Para escribir /grade en una sesión, el mod también tiene que registrar el comando:
grader/hooks/register.js
grader/tests/grader.test.ts
reply del hook es el objeto bajo value, cuyo text empieza con PASS. Para comprobar la otra rama, agrega una segunda prueba cuyo stub devuelva un text que empiece con FAIL, y espera Try again.
Un stub para una llamada a la API de mods devuelve un objeto con un campo value, que contiene aquello con lo que se resuelve la llamada en tu mod: { value: 7 } hace que $.store.get se resuelva con 7. Un stub para uno de los eventos de Claude Code, como turn.step o tool.call, devuelve el resultado propio de ese evento, como { result: 'ok' }. $.session.send y $.prompt.fill también toman el resultado de su evento, como muestra la tabla. Consultar lo que devuelve un stub muestra qué forma toma cada nombre común. Estos errores significan que un stub es incorrecto o falta. La salida de una prueba fallida incluye un bloque encabezado por the engine reported:, y cada error aparece allí:
returned neither { value } nor { deny }: un stub para una llamada a la API de mods devolvió un valor sin envolver, lo que hace fallar la pruebano implementation forseguido de un nombre: tu mod hizo esa llamada y ningún stub la responde
mock.clock(on): responde a$.clocky devuelve un reloj simulado que tu prueba hace avanzar, así que una prueba de un temporizador no espera.mock.store(on, { count: 7 }): responde a$.storedesde un almacén que empieza con esas entradas. No devuelve nada, así que para comprobar lo que guardó tu mod, escribe tú mismo los dos stubs destorecomo lo hace la prueba de dibujo.mock.env(on, { CI: 'true' }): responde a$.env.getdesde esas variables.mock.session(on): devuelve una sesión simulada cuyo métodoappended()enumera las filas que tu mod agregó con$.session.append, de la más antigua a la más reciente; requiere Claude Code v2.1.293 o posterior.
Seguir las reglas del kit de pruebas
-
Registra cada stub antes de la primera llamada de la prueba a
$. Llamar aondespués de eso lanza un error comoon("ui.render") after the test first called $. -
session.startno se ejecuta por sí solo. Cada prueba empieza con tu módulo recién cargado y ninguno de sus hooks llamado, así que las variables a nivel de módulo conservan sus valores iniciales. Si un hook depende de lo que configurasession.start, dispáralo primero:El segundo stub responde a la llamada$.command.registerque hace un hook desession.startcomo el del tutorial. Sin él, esa llamada se rechaza conno implementation for command.registery el kit omite tu hook, así que no se ejecuta nada de lo que sigue a la llamada en el hook. La prueba no falla en ese punto. El hook omitido aparece bajothe engine reported:solo si falla una comprobación posterior. -
Registra un stub de
ui.renderpara elegir lo que devuelvenext(e). Cuando tu hookui.renderdevuelvenext(e), por ejemplo para no dibujar nada mientras Claude está inactivo, el montaje tiene éxito sin ningún stub. Para quenext(e)devuelva un elemento que tú elijas, registra un stub que lo devuelva como datos simples:Donde el sitio puede dibujar ese elemento,ui.find({ type: 'Text' })lo devuelve cuando tu hook devolviónext(e). En v2.1.323 o posterior, para la banda, pasa el nombre de tu mod como segundo argumento aon, como en{ plugin: 'my-mod' }. Sin él, el stub no responde a tunext(e). Antes de v2.1.321, el montaje falla conno implementation for ui.rendera menos que registres el stub. -
Un stub para
turn.stepes un generador asíncrono, y la prueba lee el flujo hasta su final para obtener el resultado:Cuando termina el bucle,resultes el objeto que devolvió el stub, después de que tu hookturn.stephaya tenido la oportunidad de cambiarlo. Aquíresult.answeres'ok'. -
Dispara una llamada a herramienta con el nombre y los argumentos de la herramienta como campos, como
await $.tool.call({ tool: 'Bash', command: 'ls' }), y registra un stub detool.callque devuelva{ result }.
Consultar lo que devuelve un stub
Cada llamada a la API de mods que hace tu mod en una prueba necesita un stub que responda en lugar de Claude Code, excepto las pocas que el kit responde por sí mismo: las llamadas a$.ui.invalidate, $.state y $.session.append. Para las llamadas a $.clock, usa mock.clock(on), o el $.clock.now() de tu mod falla con no implementation for clock.now.
Esta tabla enumera las que más usan los mods. La primera columna es la llamada que hace tu mod o el evento que pasa con next(e). La segunda es la función que se pasa a on con ese nombre, así que la fila de $.store.get se convierte en on('store.get', ($, e) => ({ value: saved.get(e.key) })). Un '...' en un stub marca texto que debes completar tú:
Comprobar un resultado con expect
expect tiene su propio conjunto de aserciones, como toEqual y toHaveLength, que van después del valor que estás comprobando, como en expect(answer.text).toBe('ok'). Para ver la lista completa, busca type Matchers en claude-code/index.d.ts dentro de los tipos para tu compilación. Pon .not delante de la aserción para comprobar lo contrario. Para comprobar con qué se resuelve o se rechaza una promesa, pon .resolves o .rejects justo después de expect(...) y usa await en la línea, como en await expect(promise).rejects.toThrow().
Cuando un expect falla dentro de un stub o hook que pasaste a on como una función simple en lugar de un generador asíncrono, la prueba falla. El motor omite ese hook, y la salida del fallo lo nombra, como in the test's store.set hook.
Probar un temporizador
Un mod que ejecuta trabajo con un temporizador necesita un reloj que la prueba controle, para que la prueba pueda hacer avanzar el tiempo en lugar de esperar.const clock = mock.clock(on) devuelve un reloj simulado que comienza en 0 y solo avanza cuando tu prueba lo hace avanzar. Para comenzar en otro momento, pásalo en milisegundos, como en mock.clock(on, { now: 5000 }). El reloj tiene estos métodos:
Este hook pertenece a un mod llamado
countdown y maneja un comando /countdown que recibe un número de segundos, inicia un temporizador $.clock.every de un segundo y muestra un toast al llegar a cero. Al igual que con grader, el archivo contiene solo el hook bajo prueba y no registra el comando:
countdown/hooks/register.js
/countdown 3 y hace avanzar el reloj simulado, por lo que verifica tres segundos de comportamiento sin esperar tres segundos:
countdown/tests/countdown.test.ts
expect muestra que el toast no llega antes de tiempo, y el segundo muestra que llega una sola vez. Cada advance se resuelve después de que se hayan ejecutado los temporizadores que vencieron, por lo que la verificación de la línea siguiente ve su efecto.
Probar un dibujo
Una prueba puede dibujar uno de los puntos de renderizado de tu mod y luego presionar, escribir en y buscar los elementos que dibujó.$.ui.mount dibuja el punto a través del hook ui.render de tu mod y devuelve un handle con un método para cada una de esas acciones. Para cubrir varias apps en una sola prueba, establece surface en la app para la que quieres dibujar. Esta prueba abre el panel de Crear un panel con pestañas, cambia de pestaña, presiona el botón y verifica el conteo en la terminal y en la app de Desktop:
hello-tabs/tests/hello-tabs.test.ts
claude plugin test desde el directorio hello-tabs. La prueba pasa cuando ambas apps dibujan la línea del conteo y el mod ha guardado 2. El conteo se mantiene de la primera app a la segunda porque ambos montajes usan el mismo módulo cargado.
El handle que devuelve $.ui.mount tiene estos métodos, que identifican los elementos por la key que les diste:
Cada método se resuelve después de que tu handler ha terminado, así que puedes verificar el resultado en la línea siguiente. Establece
props con lo que Claude Code pasaría para ese punto. La tabla de puntos de renderizado enumera las props de cada punto, y los tipos para tu compilación incluyen sus tipos.
Para detectar un árbol de elementos que no es válido para la app que indicaste en surface, usa find para buscar un elemento que agrega tu hook. La prueba no verifica cómo la app pinta un árbol, así que revisa también un nuevo diseño en una sesión real.
Probar un dibujo después de /clear
Cada prueba comienza con todos los valores de $.state en su valor predeterminado, que es como los deja /clear. Para probar lo que hace tu mod a continuación, omite session.start, dispara classic.SessionStart con source: 'clear' y verifica lo que dibuja tu mod.
Esta prueba verifica el módulo de Volver a cargar un valor guardado después de /clear. Agrégala al archivo de Probar un dibujo, donde está definido PANE. La primera prueba de ese archivo espera que el botón guarde el conteo, como lo hace el botón de Guardar desde más de una sesión:
hello-tabs/tests/hello-tabs.test.ts
classic.SessionStart ha copiado el 7 almacenado en $.state antes de que se dibuje el panel. Sin ese hook en tu módulo, el panel dibuja Count: 0, find devuelve undefined y la prueba falla en toBeDefined.
Prueba un mod de políticas
Un mod que tu organización incluye enprependPlugins puede rechazar otro mod antes de que se cargue. Para probar uno, establece el nivel de tu mod y dale a la prueba un segundo mod para que el tuyo lo permita o lo rechace:
tier: llámalo una vez al inicio del archivo de prueba, como entier('prepend'), para cargar tu mod comoprepend,appendobuiltin, su lugar en el orden en que se ejecutan los mods. Sin él, tu mod se carga comouser.plugins: pásale atestun objeto de opciones antes del cuerpo de la prueba. Su arreglopluginscontiene mods que escribes en línea, cada uno con unnamey una funciónregister. Para cargar uno en un lugar distinto deuser, agrégaletier.
acme-guard/tests/guard.test.ts
claude plugin test desde el directorio acme-guard. Ambas pruebas pasan con el mod de políticas tal como lo muestra la página de administración.
El kit carga todos los mods en la primera llamada de la prueba sobre $. Cuando tu mod rechaza uno, esa llamada lanza un error, y el mensaje indica el mod rechazado, el mod que lo rechazó y tu motivo. En la segunda prueba no se rechaza nada, así que reader responde la llamada a herramienta antes de que llegue al stub.
Próximos pasos
- Solucionar problemas de un mod: descubre por qué un mod no hace nada en una sesión
- Referencia de mods: la entrada y el resultado de cada evento, para escribir stubs