Agentic QA · Workflow Skill

/xray-cli

Gestión de pruebas en Xray Cloud desde la terminal: Tests, Test Plans, Test Executions, import de resultados, evidencia, defectos, backup y migración — todo vía bun xray.

[TMS_TOOL] · Modality jira-xray Sirve a Stages 1–6 del pipeline QA Xray GraphQL + Jira REST

Deck del skill xray-cli: el operador de Xray Cloud del repo. Es un skill utilitario: los workflow skills (sprint-testing, test-documentation, regression-testing) lo cargan cuando resuelven [TMS_TOOL] en modalidad jira-xray. Pulsa → para avanzar, S para modo presentador, O para overview, F para pantalla completa.

Mapa · 2 de 17

El workflow completo de bun xray

Gate 0

¿Modalidad jira-xray?

no → /acli
(jira-native)

→

Fase 1

Autenticar

auth login · status
.env · token 24 h

→

Fase 2

Especificar

test create + add-step
precondition · set

→

Fase 3

Planificar (ATP)

plan create
plan add-tests

→

Fase 4

Ejecutar (ATR)

exec create --environment
exec add-tests

→

Fase 5

Reportar

run status · evidence · defect
ó import junit/cucumber/xray

Caminos adyacentes

Reparar

Sync & Repair

exec sync · plan sync · repair --apply — cuando la capa Jira y la capa Xray divergen

Preservar

Backup & Migración

backup export --all → preflight → restore --sync (site → site)

Fallback

Atlassian MCP

sin binario o sin auth, operación simple — bulk siempre CLI

Handoffs

← /sprint-testing · ATP + ATR por ticket ← /test-documentation · Stage 4, TCs + ROI → /regression-testing · Stage 6, GO/NO-GO

Índice mental del deck: un gate de modalidad, cinco fases del camino principal, tres caminos adyacentes y los handoffs con las demás skills. Cada nodo del mapa es una sección de las que siguen.

Gate 0 · 3 de 17

Antes de teclear: ¿este proyecto usa Xray?

Modality jira-xray

Jira Cloud + plugin Xray. Este skill es el dueño de [TMS_TOOL]: Tests, Plans, Executions y Preconditions son issues Xray.

→ continúa con este deck.

Modality jira-native

Sin plugin Xray. No uses este skill: carga /acli — el TMS se mapea a issues Jira nativos (test-documentation/references/jira-setup.md).

¿Quién decide? La modalidad se resuelve UNA sola vez en /test-documentation §Phase 0 y las fases posteriores la heredan — nunca se re-decide a mitad de flujo (anti-patrón X6). Y los workflow skills nunca escriben bun xray literal: usan pseudocódigo [TMS_TOOL] y cargan este skill, que es el único dueño de la sintaxis (anti-patrón X1).

Puerta de entrada del skill. Si un agente llega desde un bloque [TMS_TOOL] sin haber resuelto la modalidad, debe pausar y consultar el resolver de test-documentation antes de seguir.

Craft · 4 de 17

Las piezas que el CLI manipula

Test

El QUÉ. La especificación de un caso (TC). Manual, Generic o Cucumber.

Precondition

El ANTES. Estado inicial reutilizable entre Tests.

Test Set

El GRUPO. Carpeta lógica: organiza, no ejecuta.

Test Plan

El SEGUIMIENTO. El alcance. En este repo: el ATP.

Test Execution

El CUÁNDO. El ciclo de corridas. En este repo: el ATR.

Test Run

El RESULTADO. Una corrida de un Test dentro de una Execution. No es un issue: su id es GraphQL.

Claves vs ids: los flags de issue (--execution · --plan · --set · --tests) aceptan clave Jira (PROJ-194) o issueId numérico. Los run ids son la excepción: GraphQL, nunca claves Jira.

Mnemotécnica: QUÉ / ANTES / GRUPO / SEGUIMIENTO / CUÁNDO + RESULTADO. Mapping del repo: ATP→Test Plan, ATR→Test Execution, TC→Test. Si solo hay credenciales Xray y pasas una clave Jira, el CLI falla con un error guía que apunta a los flags --jira-*.

Fase 1 · 5 de 17

Autenticar: auth login

$ bun xray auth status $ bun xray auth login # todo desde .env $ bun xray auth login \ --client-id <id> --client-secret <secret> # override: otro site $ bun xray auth login --jira-url https://org.atlassian.net \ --jira-email user@email.com --jira-token <token> $ bun xray auth logout

Dónde vive: ~/.xray-cli/config.json (creds + proyecto default) · token.json (token 24 h) · UN site a la vez.

Dos patas de credenciales

Xray GraphQL: XRAY_CLIENT_ID/SECRET · Jira REST: ATLASSIAN_URL/EMAIL/API_TOKEN — resuelven claves Jira → issueId y habilitan Sync & Repair.

Gotcha X2

Token >24 h = 401 silencioso que parece blip de red. Re-auth con auth login; no atrapes el error.

bun auto-carga .env. La config guarda UN site a la vez — eso vuelve a aparecer en la fase de migración (re-login entre export y restore).

Fase 2 · 6 de 17

Especificar: crear Test

Manual

Pasos humanos: acción → dato → resultado.

steps[]

Generic

Referencia al test automatizado.

--definition

Cucumber

BDD Given / When / Then.

--gherkin

$ bun xray test create --project DEMO --summary "Verify login" --type Manual $ bun xray test add-step --test <issueId> --action "Enter credentials" --data "user@test.com" --result "Dashboard" # un add-step POR paso $ bun xray test get DEMO-123 # verificar que los steps aterrizaron

Gotcha: los steps NO persisten en create — Xray Cloud los descarta en silencio (stepCount:0) y --step está deprecado. Patrón fiable: create → un add-step por paso → verificar con test get. Enriquecer un Test existente: update-gherkin · update-definition · update-type.

También: test list --jql "project = DEMO AND labels = critical", test remove-step. La promoción de Stage 4 (regresión) usa update-gherkin sobre tests creados en sprint.

Fase 2 · 7 de 17

Reutilizar y agrupar

Precondition

Issue Xray de primera clase con el setup compartido — se define una vez, se ata a N Tests.

$ bun xray precondition create --project DEMO \ --summary "DB seeded" --type Generic \ --definition "bun run db:seed" --labels setup,smoke $ bun xray precondition add-to-test --test PROJ-123 \ --preconditions PROJ-90,PROJ-91 $ bun xray precondition update --precondition PROJ-90 --type Generic

Test Set

Carpeta lógica para seleccionar pruebas afines rápido. No ejecuta — solo organiza.

$ bun xray set create --project DEMO --summary "Smoke Tests" $ bun xray set add-tests --set <id> --tests <id1>,<id2> $ bun xray set remove-tests --set <id> --tests <id1> $ bun xray set get <issueId> $ bun xray set list --project DEMO

Ninguno de los dos corre pruebas. Precondition default --type Manual; admite Generic / Cucumber, labels y folder del test repository.

Fase 3 · 8 de 17

Planificar: Test Plan = el ATP

$ bun xray plan create --project PROJ \ --summary "Auth Suite - Q3 ATP" # → PROJ-110 $ bun xray plan add-tests --plan PROJ-110 \ --tests PROJ-100,PROJ-101 $ bun xray plan remove-tests --plan PROJ-110 --tests PROJ-100 $ bun xray plan list --project PROJ

El Test Plan es el contenedor del ATP: define el alcance y consolida el progreso de sus ejecuciones.

Craft · dos capas de trazabilidad

plan add-tests / exec add-tests registran el Test en la capa interna de Xray (membership GraphQL) — no son issuelinks de Jira. «Jira enlaza issues, Xray enlaza resultados».

Si solo se cableó la capa Jira

Ocurre con fallbacks creados sin auth Xray: el issue existe, pero los runs vuelven vacíos y los estados no se pueden fijar. Se repara con plan sync / exec sync (camino adyacente, slide 14).

Distinción crítica del skill: membership XRAY-INTERNAL ≠ issuelink Jira. El flujo canónico del slide 13 marca qué pasos son de qué capa.

Fase 4 · 9 de 17

Ejecutar: Test Execution = el ATR

$ bun xray exec create --project PROJ --summary "Auth Suite - Sprint 12 ATR" \ --environment staging # repetible o CSV: --environment staging,chrome # → PROJ-194 $ bun xray exec add-tests --execution PROJ-194 --tests PROJ-100,PROJ-101 $ bun xray exec remove-tests --execution PROJ-194 --tests PROJ-101 $ bun xray exec set-environment --execution PROJ-194 --environment staging,chrome $ bun xray exec get PROJ-194 $ bun xray exec list --project PROJ

Por qué importan los Test Environments

Una ejecución fijada a un entorno (staging vs production, chrome vs firefox) hace los resultados congruentes y comparables — nunca compares a ciegas un run de staging contra uno de prod. Se fijan al crear con --environment o después con exec set-environment.

La Execution es el contenedor del ATR: la tarea asignable de correr un grupo de pruebas. Contiene los Test Runs (uno por Test incluido).

Fase 5 · 10 de 17

Reportar a mano: el Test Run

$ bun xray run list --execution PROJ-194 # → runIds (GraphQL, NO claves Jira) $ bun xray run get <runId> $ bun xray run status --id <runId> --status PASSED $ bun xray run step-status --run <runId> --step <stepId> --status PASSED $ bun xray run comment --id <runId> --comment "Test completed successfully" $ bun xray run step-comment --run <runId> --step <stepId> --comment "build 4172" # sobrescribe el anterior

Estados de run que acepta --status

TODO EXECUTING PASSED FAILED ABORTED BLOCKED

El Run es la unidad real de resultado: una corrida de UNA prueba. step-comment sobrescribe el comentario previo del paso — no acumula histórico.

Fase 5 · 11 de 17

Evidencia y defectos sobre el Run

$ bun xray run evidence --id <runId> --file ./screenshots/error.png $ bun xray run evidence --id <runId> --dir ./.context/PBI/.../evidence/ $ bun xray run step-evidence --run <runId> --step <stepId> --file step3.png $ bun xray run evidence-list --id <runId> $ bun xray run evidence-rm --id <runId> --filename error.png $ bun xray run defect --id <runId> --issues DEMO-456,DEMO-789

Límite de 20 MB

Xray Cloud rechaza requests >20 MB. El CLI auto-trocea los --dir en lotes de ~15 MB; un archivo suelto de 30 MB sí se rechaza — comprímelo o divídelo antes.

Craft · el bug nace en la corrida

El defecto se enlaza al Test Run, no al Test abstracto: un mismo Test puede tener 0 bugs en una corrida y 1 en otra. Nunca empujes runs a TCs con veredicto to_be_automated=no (anti-patrón X7).

La carpeta evidence/ del PBI local (.context/PBI/.../evidence/) se sube entera con --dir. evidence-rm acepta --evidence <id> o --filename.

Fase 5 · 12 de 17

Reportar en bloque: import

$ bun xray import junit --file results.xml --project DEMO $ bun xray import junit --file results.xml --plan DEMO-100 # cuelga la Execution del Plan $ bun xray import junit --file results.xml --execution DEMO-200 # rellena una Execution existente $ bun xray import cucumber --file cucumber-report.json --project DEMO $ bun xray import xray --file xray-results.json

X3 · pre-check

Verifica que Plan / Execution existan con plan list / exec get antes de importar: los resultados huérfanos abortan el import completo.

X5 · dry-run primero

Nunca contra producción sin previsualizar: import y restore escriben de forma irreversible sobre cientos de TCs y runs.

X4 · JSON canónico

Nunca fabriques a mano payloads Xray (testInfo, iterations, evidences): el CLI es dueño de la forma canónica.

Es el camino natural tras una corrida automatizada (Playwright → junit.xml). regression-testing (Stage 6) consume estos resultados para el GO/NO-GO.

Recap · 13 de 17

Flujo canónico: ATP → Tests → ATR

# 1. Test Plan (contenedor del ATP) $ bun xray plan create --project PROJ --summary "Auth Suite - Q3 ATP" # → PROJ-110 # 2. Tests + steps, un add-step por paso $ bun xray test create --project PROJ --summary "Verify login" --type Manual # → PROJ-100 $ bun xray test add-step --test <id-100> --action "Open app" --result "Login form displayed" # 3. Adjuntar Tests al Plan (membership XRAY-INTERNA, no issuelink) $ bun xray plan add-tests --plan PROJ-110 --tests PROJ-100,PROJ-101 # 4. Test Execution (contenedor del ATR), fijada a entorno $ bun xray exec create --project PROJ --summary "Auth Suite - Sprint 12 ATR" --environment staging # → PROJ-194 # 5. Adjuntar Tests a la Execution (membership XRAY-INTERNA) $ bun xray exec add-tests --execution PROJ-194 --tests PROJ-100,PROJ-101 # 6. Resultados: en bloque o run a run $ bun xray import junit --file test-results/junit.xml --execution PROJ-194 # ó runs a mano: $ bun xray run status --id <runId> --status PASSED

Este es el orden autoritativo al cablear un Test Plan / Test Execution a mano. Los pasos 3 y 5 viven en la capa interna de Xray — si esa capa falta, los runs vuelven vacíos.

Espejo del "Canonical End-to-End Flow" del SKILL.md. Sirve como chuleta: todo lo demás del deck son variaciones y salvaguardas alrededor de estos 6 pasos.

Camino adyacente · 14 de 17

Sync & Repair: reconciliar Jira ↔ Xray

Cuándo: un Execution / Plan nació por un fallback Jira sin auth Xray → la capa Jira aceptó el issue, pero Xray nunca registró los tests: runs vacíos, estados imposibles de fijar.

$ bun xray exec sync --execution PROJ-194 # diff — dry-run por defecto $ bun xray exec sync --execution PROJ-194 --apply # re-adjunta en la capa Xray $ bun xray plan sync --plan PROJ-110 [--apply] $ bun xray repair --project PROJ # scan masivo: todos los Plans + Executions $ bun xray repair --project PROJ --apply --limit 200

Missing at Xray layer

Tests enlazados en Jira pero no registrados en Xray → --apply los re-adjunta.

Missing at Jira layer

Tests registrados en Xray sin issuelink Jira → solo se reporta; sync nunca auto-borra.

Requisito: credenciales Xray y Jira configuradas — la vista Jira sale de Jira REST, separada del GraphQL de Xray.

Es la materialización operativa del craft de "dos capas" del slide 8. repair es el barrido bulk; exec/plan sync el bisturí por issue.

Camino adyacente · 15 de 17

Backup, restore y migración de site

$ bun xray backup export --project DEMO --output demo-backup.json [--include-runs] $ bun xray backup export --all --include-runs # cada proyecto con datos Xray → .backups/<KEY>-backup.json $ bun xray backup preflight --dir .backups # gaps de config en destino (read-only) $ bun xray backup restore --file demo-backup.json --project NEW_PROJ --dry-run $ bun xray backup restore --file demo-backup.json --project PROJ --sync # site→site, claves preservadas $ bun xray backup restore --file demo-backup.json --project PROJ --map-keys mappings.csv

Schema v2.0

Footprint completo: tests, preconditions, plans, sets y folders; executions + run statuses opt-in (--include-runs). Los backups v1.0 restauran igual.

Gotcha cross-site

GraphQL usa issueId numérico, re-asignado por site; la migración preserva la KEY → usa siempre --sync site→site, y re-corre auth login entre export y restore.

Runbook completo (references/migration-runbook.md): auth source → export --all → auth dest → preflight → corregir config → restore --sync.

Restore en modo create emite un CSV de key-mapping; --map-keys lo consume cuando las claves cambiaron. preflight se corre autenticado al destino y no escribe nada.

Salvaguardas · 16 de 17

Anti-patrones — nunca hacer

#	Regla
X1	Nunca llamar bun xray directo desde workflow skills — usan [TMS_TOOL] y cargan este skill.
X2	Nunca cachear tokens más allá de su TTL de 24 h — el 401 silencioso se cura con re-auth, no con try/catch.
X3	Nunca importar resultados en bloque sin verificar antes que las claves de Plan / Execution existen.
X4	Nunca fabricar a mano JSON de Xray (testInfo, iterations, evidences) fuera de bun xray.
X5	Nunca correr import ni backup restore contra producción sin --dry-run previo.
X6	Nunca mezclar modalidades jira-xray y jira-native en la misma fase — se resuelve una vez en Phase 0.
X7	Nunca empujar runs automatizados a TCs con veredicto Manual terminal (to_be_automated=no).

Los siete anti-patrones del SKILL.md, tal cual. X1/X6 protegen la arquitectura de skills; X2-X5 protegen los datos; X7 protege el reporting Candidate/Manual/Deferred.

Cierre · 17 de 17

Invocación, handoffs y artefactos

Cómo se invoca

/xray-cli — o frases como "create a test in Xray", "import test results to Xray", "update run status", "backup Xray project", "link defect to run". Los workflow skills llegan vía [TMS_TOOL].

Handoffs

← /sprint-testing S1–3: ATP + ATR por ticket.
← /test-documentation Stage 4: TCs + ROI.
→ /regression-testing Stage 6: resultados para el GO/NO-GO.

Fallback

Sin binario o sin auth y operación simple → Atlassian MCP (cobertura parcial). Bulk import, backup/restore y Plans/Executions a escala → siempre el CLI.

Artefactos que deja el skill

Test Plan = ATP · Test Execution = ATR · Test + steps = TCs · Runs con evidencia y defectos enlazados · backups en .backups/*.json · config en ~/.xray-cli/.

Referencias: references/backup-restore.md · migration-runbook.md · graphql-api.md · test-types.md

Fin del recorrido. El mapa del slide 2 resume todo: gate de modalidad → auth → especificar → planificar → ejecutar → reportar, con sync/backup/MCP como caminos adyacentes.