Jira y Xray: el tracker y el TMS del repo

Alcance y modalidades

Este repo trabaja con Jira Cloud y Xray Cloud. Jira guarda las historias, los bugs y los work types de QA; Xray añade los tipos de issue de test management (Test, Test Plan, Test Execution, Test Set y Precondition) y el registro de cada ejecución. Las versiones Server y Data Center no están soportadas: la CLI de Xray y los scripts de sincronización hablan solo con las APIs de Cloud.

Hay una segunda modalidad para proyectos sin licencia de Xray, llamada jira-native. En ella el ATP y el ATR son work types nativos Test Plan y Test Execution (el custom field de la historia es el fallback cuando la instancia no los tiene) y los test cases son un work type Test propio. Esta guía cubre la modalidad con Xray; la configuración de jira-native está en .agents/skills/test-documentation/references/jira-setup.md (sección 3).

La diferencia entre el estado del Test y el Execution Status es la confusión más común. El detalle está en .agents/skills/test-documentation/references/xray-platform.md.

Antes de empezar

• Un sitio de Jira Cloud y permisos de administrador de Jira (los necesitas para issue type schemes, screens y workflows).
• Una licencia de Xray Cloud, de prueba o de pago.
• La lista de módulos de tu producto (Auth, Checkout, Billing...). La usarás para las carpetas del Test Repository y para los components.
• El repo instalado con bun setup y un .env creado a partir de .env.example.

Reserva entre dos y cuatro horas si partes de un proyecto vacío.

Instalar Xray y añadir sus work types

1. Instala la app

   En Jira, abre Settings (engranaje) > Apps > Find new apps, busca "Xray Test Management" y pulsa Get it now. Activa la licencia o el trial cuando te lo pida.

2. Comprueba la instalación

   Deben aparecer cinco tipos de issue nuevos (Test, Precondition, Test Set, Test Execution y Test Plan), una sección de Xray en Settings > Apps y los paneles de Xray dentro de los issues.

3. Añade los tipos al proyecto

   En Project settings > Issue types, usa Actions > Add Xray Issue Types y marca los cinco.

4. Activa la cobertura de requisitos

   En Project settings > Apps > Xray Settings > Test Coverage, marca como cubribles los tipos de issue que .agents/jira-required.yaml declara con coverable: true en work_types. En la configuración global de Xray, Issue Type Mapping, pon esos mismos tipos como requirement types, y Bug y Defect como defect types (una Improvement no rompe un criterio, así que queda fuera).

5. Revisa los Test Types

   Xray trae Manual (pasos que ejecuta una persona), Cucumber (Gherkin) y Generic (una referencia sin estructura, la que usan los tests automatizados con Playwright). Con esos tres alcanza; no hace falta crear tipos propios.

Workflows

Los skills mueven los issues de estado por su nombre de transición, así que el workflow de tu proyecto tiene que existir antes de la primera sesión. Los tres diagramas son los workflows de la instancia de referencia de la metodología IQL: historia, test case y bug. Si tu proyecto usa otros nombres, no pasa nada; el repo los descubre con bun run jira:sync-workflows (lo ves en Catálogos locales).

Historia de usuario

Test case

El workflow del Test es el que más vas a tocar a mano, así que aquí van sus estados y transiciones tal como están en el catálogo del repo (.agents/jira-workflows.json, clave test_case). Los nombres de transición van en minúscula, copiados letra por letra.

No inventes estados: Approved y Automating no forman parte de este workflow.

Todas las transiciones del Test, con su origen y su destino, están en .agents/jira-workflows.json (clave test_case); el catálogo se regenera con bun run jira:sync-workflows.

Bug

Para crear el workflow del Test en tu sitio:

1. Crea el workflow

   Settings > Issues > Workflows > Add workflow, con los estados y transiciones de las tablas de arriba.

2. Asígnalo al work type Test

   En Workflow schemes, asocia el workflow al tipo Test y asigna el scheme a tu proyecto.

3. Descárgalo al repo

   Ejecuta bun run jira:sync-workflows para que el catálogo local refleje lo que acabas de crear.

Test Repository

El Test Repository es el árbol de carpetas de Xray para ordenar los tests. Lo abres desde el proyecto, en Tests > Test Repository. Crea una carpeta por módulo del producto y subcarpetas por funcionalidad (clic derecho sobre la raíz > Create folder). Los tests existentes se mueven arrastrándolos o con las acciones masivas.

Test Repository
├── Auth
│   ├── Login
│   ├── Logout
│   └── Password Reset
├── Bookings
│   ├── Create Booking
│   └── Cancel Booking
├── Invoices
│   └── Export Invoice
└── Smoke Tests
    └── Critical Paths

Credenciales y .env

Necesitas dos juegos de credenciales, las dos para Cloud:

Token de Atlassian

Lo usan acli, la CLI de Xray para las funciones de Jira y los scripts jira:*. Se crea en id.atlassian.com.

API key de Xray

Un par Client ID y Client Secret. Se crea en Settings > Apps > Xray > API Keys > Create API Key. Dale un nombre que diga para qué es, por ejemplo "QA Automation - CI". Copia los dos valores en el momento: el secret no se vuelve a mostrar.

Después rellena estas variables en tu .env:

La lista completa y comentada está en .env.example. Las que tienen destino github en cli/lib/variables-manifest.ts también son secrets de CI: las sube a GitHub Actions bun setup --variables.

Catálogos locales y jira:check

Cada sitio de Jira da ids distintos a sus custom fields y nombres distintos a sus estados. Para que los skills funcionen en cualquier sitio, el repo descarga esa información a archivos JSON en .agents/ y los skills la referencian por slug ({{jira.acceptance_test_plan}} en vez de customfield_10123). Estos archivos se generan; no los edites a mano.

El manifiesto .agents/jira-required.yaml es lo que la metodología espera encontrar en tu sitio: campos obligatorios y opcionales, tipos de enlace y work types. bun run jira:check compara ese manifiesto con los catálogos:

• Cada campo obligatorio existe en jira-fields.json (si falta, es error y el comando sale con código 1), tiene el tipo esperado y, si es de opciones, tiene todas las opciones declaradas.
• Los campos opcionales que faltan solo se informan; nunca cambian el código de salida.
• Cada work type declarado aparece en jira-workflows.json.
• Los tipos de enlace se validan si existe jira-link-types.json; si no, el check queda en DEFERRED y sigue en verde.
• Con --live compara además el catálogo de workflows con lo que Jira responde ahora mismo. Sirve para detectar un catálogo que quedó viejo. Solo emite avisos.

bun run jira:baseline es un aviso aparte: te dice si tu manifiesto declara menos work types que la versión upstream. Un manifiesto incompleto produce un jira-workflows.json incompleto sin avisar, y las transiciones de los tipos que faltan dejan de resolverse. Nunca bloquea: omitir un work type puede ser una decisión legítima.

bun run jira:sync-fields
bun run jira:sync-workflows
bun run jira:sync-link-types
bun run jira:check

Dos tareas de administración tienen su propio skill, jira-administration, con un modo cada una: components reconcilia los Components del proyecto en Jira con los módulos del producto, y instance-migration repunta el repo cuando cambia la URL del sitio de Atlassian. En Claude Code, /jira-administration components; en OpenCode y Codex, "cargá la skill jira-administration, modo components". Los dos modos analizan sin escribir, te muestran el plan y no tocan Jira ni el repo hasta que lo apruebes.

La CLI de Xray

El repo trae su propia CLI de Xray en cli/xray/, que se ejecuta como bun xray. El skill /xray-cli tiene la sintaxis completa y bun xray --help muestra la versión actual. Estos son los comandos que usas durante el setup:

# Autenticación (lee XRAY_CLIENT_ID y XRAY_CLIENT_SECRET del entorno)
bun xray auth login
bun xray auth status
bun xray auth logout

# Tests
bun xray test list --project PROJ --limit 20
bun xray test get PROJ-101
bun xray test create --project PROJ --summary "Verify login with valid credentials" --type Manual --labels "e2e,auth"
bun xray test add-step --test <issue-id> --action "..." --result "..."
bun xray test enrich --project PROJ

# Test Executions
bun xray exec list
bun xray exec create --project PROJ --summary "RTR: staging-2026-09-24: Regression Testing" --environment staging
bun xray exec add-tests --execution <issue-id> --tests <id1,id2>

# Importar resultados: una entrada por ATC con la clave de su Test, siempre en una ejecución explícita
bun run xray:payload --execution PROJ-194 --out xray-results.json reports/atc_results.json
bun xray import xray --file xray-results.json

# Test Plans
bun xray plan list
bun xray plan get PROJ-300

test enrich completa la copia local de .context/PBI con las Preconditions y la pertenencia a Test Sets, que la API REST de Jira no expone.

Primer Test Plan y Test Execution

1. Configura los Test Environments

   En Settings > Apps > Xray > Test Environments, añade los entornos del repo: local, qa, staging y production. Usa exactamente esos nombres, sin abreviaturas.

2. Crea el Test Plan

   Create > tipo Test Plan, con un summary claro, la fix version si la usas y el objetivo del plan en la descripción.

3. Añade tests al plan

   Desde la sección Tests del plan, Add Tests: puedes buscarlos uno a uno, traer un Test Set entero o una carpeta del Test Repository.

4. Crea la Test Execution

   Desde el plan, Create Test Execution, eligiendo el Test Environment (por ejemplo staging) y la revisión o build. Los tests del plan entran solos.

En el día a día no harás esto a mano: los skills crean los planes y las ejecuciones con sus convenciones de nombre (ATP, STP, RTP, ATR, STR, RTR), crean el Test Set de aceptación de cada historia (ATS) y los cuelgan del epic de QA que corresponde. Hacerlo una vez sirve para comprobar que permisos y configuración están bien.

Validación final

• Los cinco tipos de Xray aparecen en el proyecto.
• Los Test Types Manual, Cucumber y Generic están disponibles.
• El workflow del Test está asignado y la transición start design aparece en un Test en Draft.
• La cobertura de requisitos está activa para los tipos que .agents/jira-required.yaml declara con coverable: true (el Epic no es uno de ellos).
• Un Test Set enlazado a una historia con el tipo tests / is tested by (el Set del lado is tested by de la historia) llena el panel de cobertura de esa historia. Es la arista que crean los skills: el ATS de cada Story. El enlace directo de un Test a la historia también cubre, pero queda como último recurso; el canon está en .agents/skills/agentic-qa-core/references/traceability-linking.md.
• bun xray auth status responde autenticado y bun xray test list --project PROJ devuelve datos.
• bun run jira:check termina sin errores.

Para una prueba de punta a punta: pon la clave de un Test que ya existe en un @atc, añádelo a un plan, ejecuta Playwright e importa el resultado con bun run xray:payload --execution <KEY> --out xray-results.json reports/atc_results.json y bun xray import xray --file xray-results.json. La Test Execution debe mostrar el resultado.

Problemas frecuentes

JQL útiles

# Tests automatizados
project = PROJ AND issuetype = Test AND status = AUTOMATED

# Candidatos a automatizar
project = PROJ AND issuetype = Test AND status = Candidate

# Tests por etiqueta
project = PROJ AND issuetype = Test AND labels in (regression, smoke)