Enviar resultados desde CI con Vitest

La aplicación Vitest envía a Probara los resultados de tus pruebas de Vitest desde cualquier pipeline de CI, con el reporter de Probara para Vitest. Cada ejecución de Vitest se convierte en una ejecución automatizada con sus resultados, los casos de prueba que nombra y sus adjuntos.

El reporter se autentica con un token de aplicación: un token que pertenece a la organización, no a una persona. No ocupa ningún puesto y sigue funcionando cuando la persona que lo creó se va. Esta guía cubre la tarjeta en Probara y la configuración; la documentación del reporter cubre cada opción del reporter y los helpers de prueba.

Antes de empezar

Configurarla

1. En Workspace › Integraciones, selecciona la tarjeta Vitest. El diálogo muestra qué puede hacer la aplicación y enlaza a esta guía.

2. Abre la pestaña Tokens de acceso y selecciona Crear un token de aplicación.

3. Escribe un Nombre del token y selecciona Crear token. Ponle el nombre de lo que lo usa — el repositorio o el pipeline — para saber después cuál revocar.

4. Selecciona Copiar token en Copia tu nuevo token. Es la única vez que Probara lo muestra: guárdalo en tu CI como un secreto llamado PROBARA_API_TOKEN antes de seleccionar Listo.

5. Instala el reporter en tu proyecto de Vitest:

   npm install --save-dev @probara/vitest-reporter

6. Añádelo a los reporters de vitest.config.ts, después de default (el que lees en la terminal), y sustituye <PROJECT_CODE> por el ID del Proyecto, por ejemplo SHOP:

   import { defineConfig } from 'vitest/config';
   
   export default defineConfig({
     test: {
       reporters: ['default', ['@probara/vitest-reporter', { projectId: '<PROJECT_CODE>' }]],
     },
   });

   Al definir reporters se reemplaza el reporter predeterminado de Vitest, así que deja 'default' en la lista para seguir viendo la salida en la terminal.

7. Pasa el secreto a tus pruebas como la variable de entorno PROBARA_API_TOKEN y ejecútalas. Por ejemplo, en GitHub Actions:

   - name: Run Vitest tests
     run: npx vitest run
     env:
       PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}

El token nunca va en vitest.config.ts: el reporter lo lee del entorno. La tarjeta de la página de Integraciones muestra cuántos tokens activos tiene la aplicación.

Qué envía el reporter

Un campo o una opción que Probara no conoce, o que se elimina mientras se procesa el informe, se omite y se devuelve como advertencia, nunca como un error: el informe registra igualmente cada resultado. Un campo con el valor vacío se omite sin advertencia. Un correo de assignFailedTo que no corresponde a ningún miembro que pueda trabajar en el proyecto también se omite, con una advertencia que solo dice cuántos se omitieron. La documentación del reporter muestra cómo una prueba define sus parámetros, etiquetas, campos, pasos y enlaces. Los helpers no necesitan ningún archivo de configuración: el reporter añade el suyo a cada proyecto de Vitest.

Los mismos casos que una importación JUnit

Si ya envías los resultados de Vitest con probara import junit sobre el informe del reporter junit de Vitest, el reporter de Probara encuentra los mismos casos de prueba: sus claves de automatización son iguales a las de la importación — la ruta del archivo de prueba relativa a la raíz del proyecto más el título completo de la prueba. Por eso, al pasar al reporter cada prueba sigue vinculada a su caso y a su historial. Vale la pena conocer una diferencia: el reporter envía cada intento, mientras que la importación conserva solo el último.

Ejecutar solo las pruebas de una ejecución

Para ejecutar solo las pruebas de una ejecución creada en Probara, define PROBARA_RUN_CASES_ONLY con true y PROBARA_RUN_ULID con el ULID de la ejecución, solo en el job que ejecuta las pruebas de esa ejecución. No cambia nada en vitest.config.ts. Por ejemplo, en un workflow de GitHub Actions que inicias a mano con un input run_ulid:

- name: Run the tests of a Probara run
  run: npx vitest run
  env:
    PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
    PROBARA_RUN_CASES_ONLY: 'true'
    PROBARA_RUN_ULID: ${{ inputs.run_ulid }}

El reporter envía los resultados a esa ejecución y la deja abierta.

Para obtener el ULID, abre la ejecución, selecciona Acciones de la ejecución (el menú de la cabecera de la ejecución) y elige Copiar ULID de la ejecución; la misma opción está en el menú de cada ejecución de la lista de ejecuciones. La opción del reporter runCasesOnly: true en vitest.config.ts activa la misma selección, pero en todos los jobs: mientras reporta, cada job sin ULID muestra entonces una advertencia y ejecuta todas las pruebas.

Antes de que empiecen las pruebas, el reporter lee los casos de la ejecución. Una prueba pertenece a la ejecución cuando su clave de automatización es la de uno de los casos de la ejecución, o cuando su título o uno de sus bloques describe nombra uno de los casos de la ejecución, por ejemplo SHOP-12. Una llamada a probara.id() no cuenta: se ejecuta con la prueba, después de la selección. Leer las claves de casos es la única lectura que puede hacer un token de aplicación.

Vitest omite cada una de las demás pruebas, y el reporter no la envía: el resumen de Vitest la cuenta como omitida. Una prueba de la ejecución que el propio archivo omite, con test.skip o test.todo, se envía igualmente como omitida. Cuando no se pueden leer los casos de la ejecución, o cuando no hay ningún ULID definido, todas las pruebas se ejecutan y se envían, con una advertencia. La referencia de la selección de pruebas cubre las reglas de coincidencia y cada alternativa.

Ejecuciones divididas en shards

Con vitest --shard y el reporter blob, pon blob antes del reporter de Probara en la configuración de los shards. Los shards no envían nada, y vitest --merge-reports, ejecutado una sola vez con el reporter de Probara en su configuración, envía los resultados de todos los shards a una sola ejecución. Sin informes blob, crea primero la ejecución con probara run create, pasa su ULID a cada shard en PROBARA_RUN_ULID y ciérrala al final con probara run close. En GitHub Actions los shards de un mismo workflow ya comparten una ejecución: los jobs en paralelo definen PROBARA_CLOSE_RUN: false, y un job final ejecuta probara run close (jobs en paralelo). La referencia de sharding recoge los dos flujos.

Gestionar los tokens

En Tokens de aplicación, la pestaña Tokens de acceso lista cada token activo con quién lo creó (o Creado por un usuario eliminado), cuándo y cuándo se usó por última vez (Nunca hasta su primer informe).

Selecciona Revocar en un token, y confírmalo, cuando pueda haberse filtrado o cuando alguien que podía leerlo deje tu equipo: los pipelines que lo usan dejan de enviar resultados al momento, y no se puede deshacer. Crea antes un token nuevo para ellos. Como un token de aplicación sobrevive a la persona que lo creó, rotarlo es decisión tuya: Probara nunca lo revoca por su cuenta.

Qué puede hacer un token de aplicación

Solo lo que hace el reporter: crear ejecuciones automatizadas, enviar informes (que pueden crear los casos de prueba y las suites que nombran), añadir adjuntos a sus resultados, cerrar ejecuciones y leer las claves de casos de una ejecución. No puede leer nada más, no puede eliminar adjuntos y no sirve para Probara MCP ni para ninguna otra llamada a la API. Para scripts y otros clientes de la API, usa un token API personal.

Las ejecuciones, las entradas de actividad y los adjuntos que creó un token de aplicación muestran el logotipo y el nombre de la aplicación junto al nombre del token — por ejemplo Vitest · unit-ci — en la lista de ejecuciones, los resúmenes de la ejecución y del hito, la actividad del workspace y la lista de adjuntos.

Cuando cambia el plan

Si tu organización pasa al plan Free, sus tokens de aplicación se conservan pero Probara los rechaza, así que los pipelines dejan de enviar resultados; su diálogo lo indica y ofrece Ver planes. Aún puedes ver y revocar los tokens. Vuelven a funcionar en cuanto la organización vuelve a un plan de pago, sin nada que configurar de nuevo. Las ejecuciones manuales no se ven afectadas.

Siguiente paso

• Documentación del reporter — opciones, helpers de prueba, modo navegador y selección de pruebas.
• Integraciones de CI — cómo se compara el reporter de Vitest con la CLI y los reporters de Playwright, Jest y Cypress.
• API de casos de una ejecución — las claves de casos que lee el reporter para ejecutar solo las pruebas de una ejecución.
• API de reportes — el endpoint al que llama el reporter, para tus propias herramientas.