Sincronizar archivos .feature desde Git

Git puede ser la fuente de verdad de los casos Gherkin. Un job de CI lee tus archivos .feature y hace que los casos coincidan con ellos: un escenario nuevo crea un caso, un escenario modificado actualiza su caso y un escenario eliminado archiva su caso. Son casos sincronizados desde Git. Cambias sus escenarios en el archivo .feature, mediante un pull request. Todo lo demás sigue siendo editable en Probara.

Configurar la sincronización

1. En Workspace → Integraciones, abre la tarjeta Cucumber y crea un token de aplicación para tu pipeline. La sincronización necesita un plan de pago, igual que el envío de resultados desde CI. La página de la CLI tiene los detalles.
2. Guarda el token como el secreto de CI PROBARA_API_TOKEN y define PROBARA_PROJECT con el código de tu proyecto.
3. Ejecuta la sincronización después del checkout, en la rama principal:

- name: Sync the feature files to Probara
  run: npx @probara/cli sync gherkin "features/**/*.feature"
  env:
    PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
    PROBARA_PROJECT: <PROJECT_CODE>

Pon el patrón entre comillas para que el shell se lo deje a la CLI. Ejecuta el comando desde la raíz del repositorio, o pasa --root-dir: las rutas de las claves y de los enlaces a los archivos son relativas a esa raíz. En la primera ejecución, añade --dry-run. Muestra lo que crearía, actualizaría, movería, restauraría o archivaría una sincronización real, y no escribe nada.

La página de proveedores de CI de Cucumber tiene un pipeline completo que sincroniza y ejecuta las pruebas en GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, Bitbucket Pipelines y Buildkite.

Qué es un caso sincronizado

• Su título, descripción, pasos, precondición y las etiquetas que le da su archivo son de solo lectura, en el editor y en la API. El caso muestra una insignia Sincronizado desde Git con su ruta y su línea, enlazada al archivo cuando la sincronización conoce el enlace.
• Lo demás sigue siendo editable: responsable, prioridad, campos personalizados excepto la precondición, defectos, enlaces de incidencia, comentarios, pertenencia a planes y ejecuciones, las etiquetas que añades tú y la suite. La siguiente sincronización vuelve a colocar el caso en la suite de su archivo.
• La revisión no se aplica a los casos sincronizados. El pull request que cambia el archivo es su revisión, así que enviar un caso sincronizado a revisión y restaurar una de sus versiones anteriores están rechazados.

Cómo se convierte un escenario en un caso

Los pasos conservan sus palabras clave en inglés: Given, When, Then, And, But y *. Un archivo escrito en otro idioma detiene la sincronización.

Claves

Cada escenario tiene una clave, <ruta> > <Feature> > <Scenario>, por ejemplo features/checkout/pay.feature > Checkout > Pay with a card. La sincronización y la importación de resultados la construyen de la misma forma, así que un resultado encuentra el caso al que se sincronizó su escenario.

• La ruta es relativa a la raíz del repositorio y usa separadores /.
• Un Rule: no forma parte de la clave. Un Scenario Outline tiene una sola clave, y sus filas de Examples no forman parte de ella.
• Dos escenarios con la misma clave en un mismo archivo detienen la sincronización. El error nombra ambas líneas, así que renombra uno de ellos.
• Renombrar un archivo, su Feature o un escenario cambia su clave. La sincronización crea entonces un caso, salvo que un vínculo o un movimiento encuentre el existente.

Movimientos, renombres y vínculos

La sincronización empareja cada escenario en este orden. Cada caso se empareja una sola vez.

1. Vínculo. Una etiqueta @probara:<ID> vincula el escenario con ese caso, sea cual sea su clave. Úsala cuando renombras un escenario y cambias sus pasos en el mismo commit. Un ID que no corresponde a ningún caso del proyecto, o a un caso de otro proyecto, y dos escenarios vinculados al mismo caso, detienen la sincronización sin escribir nada.
2. Clave. Se actualiza el caso que tiene la clave del escenario.
3. Contenido. Una clave nueva mueve un caso sincronizado que desapareció en la misma sincronización, cuando los pasos, el Background y los Examples del escenario son iguales. El caso conserva su historial bajo la clave nueva. Los nombres, las etiquetas, la descripción y el enlace no cuentan, así que un renombre que deja los pasos sin cambios es un movimiento. Para moverlo hace falta exactamente un caso así. Si no, el escenario recibe un caso nuevo y el antiguo se archiva.

Un caso manual que encuentra una clave o un vínculo se convierte en caso sincronizado. La sincronización toma el título, la descripción, los pasos y la suite del archivo. Sus pasos anteriores se sustituyen, así que sus imágenes se eliminan y sus pasos dejan de usar pasos compartidos.

Un archivo movido a una carpeta que sincroniza otro job recibe un caso nuevo en esa carpeta. El caso antiguo solo lo archiva el job que sincroniza su carpeta original.

Escenarios eliminados y alcance

Un caso sincronizado cuyo escenario ya no existe se archiva, nunca se elimina, y queda en la Papelera. Solo se pueden archivar los casos cuyo archivo coincide con alguno de los argumentos de la sincronización. Los casos de archivos fuera de esos argumentos no se tocan, así que cada carpeta puede tener su propio job:

npx @probara/cli sync gherkin "features/checkout/**/*.feature"
npx @probara/cli sync gherkin "features/cart/**/*.feature"

• Un escenario que vuelve restaura su caso archivado. Si archivas tú un caso sincronizado, la siguiente sincronización que aún incluya su escenario lo restaura. Para mantener archivado un caso sincronizado, elimina su escenario del archivo.
• Un glob que no coincide con ningún archivo detiene el comando, así que un error tipográfico nunca archiva una carpeta.
• Una sincronización admite como máximo 1.000 escenarios y 20 argumentos. Un repositorio más grande se sincroniza carpeta a carpeta, con un job por carpeta.

Enlaces a los archivos

La CLI enlaza cada caso sincronizado con la línea de su escenario. Construye el enlace a partir del CI en el que se ejecuta: GitHub Actions, GitLab CI, Bitbucket Pipelines, o Azure Pipelines con un repositorio de Azure Repos. Para cualquier otro host, pasa una plantilla:

npx @probara/cli sync gherkin "features/**/*.feature" --file-url "https://git.example.com/acme/shop/blob/main/{path}#L{line}"

Solo se envían enlaces https. Los demás sistemas de CI no envían enlace, y el caso muestra su ruta.

Resultados de Cucumber

Los resultados de Cucumber usan las mismas claves, así que una ejecución rellena los casos sincronizados que cubre. Para cucumber-js, el reporter de Cucumber envía los resultados de cada escenario al final de la ejecución, con los archivos que adjuntan sus pasos. Añádelo a cucumber.js:

module.exports = {
  default: {
    format: ['@probara/cucumber-reporter'],
    formatOptions: { probara: { projectId: 'SHOP' } },
  },
};

Para Cucumber-JVM, playwright-bdd y otras herramientas que generan Cucumber JSON, importa el informe después de la ejecución:

npx cucumber-js --format json:results/cucumber.json
npx @probara/cli import cucumber results/cucumber.json

• Cada escenario es un resultado. Cada fila de un Scenario Outline es una combinación de su caso, y su resultado llega al caso de ejecución con los valores de la fila.
• Cada paso es un paso de resultado con su palabra clave, su estado, su duración y sus datos (un Doc String o una Data Table). Los pasos del Background quedan bajo un paso Background.
• Un paso que pasa es Aprobado. Un paso que falla, o que coincide con más de una definición de paso, es Fallido. Un paso omitido, pendiente o no definido no se ejecutó, así que es Omitido. Un escenario es Fallido cuando falla un paso o un hook Before o After, Omitido cuando un paso no se ejecutó, y Aprobado en cualquier otro caso.
• Mantén los archivos .feature en el checkout al importar. Un resultado encuentra su caso solo si su archivo está ahí, porque la clave incluye la ruta.
• Importa desde el directorio en el que se ejecutó Cucumber, o pásalo como --root-dir, y da a la sincronización la misma raíz. Las rutas del informe parten de ese directorio.
• La importación no envía los adjuntos del informe, como las capturas de pantalla. El resultado conserva sus pasos, estados, duraciones y errores. El reporter de Cucumber sí envía los archivos que adjunta un escenario.

La importación lee el informe JSON de Cucumber. Probara se ha probado con cucumber-js 13. Cucumber-JVM y playwright-bdd escriben el mismo formato, que Probara no ha probado.

Usa el informe JSON de Cucumber, y no JUnit, en las suites BDD. Una prueba JUnit tiene un solo nombre y un solo estado, sin palabras clave, datos ni valores de Examples, así que Probara no puede reconstruir a partir de ella la clave de un escenario ni encontrar el caso de ejecución de una fila de Outline.

Si vienes de otra herramienta

Probara lee una sola etiqueta de vínculo, @probara:<ID>. Las etiquetas de otras herramientas, como @TEST_ABC-12 de Xray, @TestCaseKey=ABC-T1 de Zephyr Scale, @QaseID=12 de Qase o @C123 de TestRail, no vinculan nada. La sincronización las guarda como etiquetas de archivo del caso, así que quítalas de los archivos cuando hayas hecho el cambio.

Hay dos formas de cambiar:

• Empezar desde los archivos. Ejecuta la sincronización con --dry-run y después de verdad. Cada escenario se convierte en un caso nuevo. Los casos y resultados de la otra herramienta se quedan allí.
• Conservar los casos que importaste. Importa los casos desde una exportación de Qase o TestRail (consulta Importar casos de prueba). Cada uno recibe un ID de Probara: búscalo por el título del caso. En los archivos, sustituye cada etiqueta antigua por un vínculo a ese ID, por ejemplo @QaseID=12 por @probara:SHOP-45, y ejecuta la sincronización. Cada caso vinculado pasa a ser un caso sincronizado. Su título, sus pasos y su suite vienen del archivo, y sus campos, comentarios y defectos se mantienen.

Las exportaciones de Xray y Zephyr Scale no son una fuente de importación, así que empieza desde los archivos.

Solución de problemas

API y MCP

La sincronización es POST /api/v1/projects/{projectId}/gherkin-sync, y la herramienta MCP sync_gherkin_features llama al mismo endpoint. Consulta la referencia de la API y la referencia de herramientas MCP.