# Cómo gestionar casos de prueba con Jira y Xray

**Categoría:** Testing y QA · **Nivel:** Intermedio · **Lectura:** 13 min
**Publicada:** 2026-07-29 · **Actualizada:** 2026-07-29 · **Autoría:** Underc0de
**Versión HTML (canónica):** https://underc0de.org/guias/testing/gestionar-casos-de-prueba-con-jira-y-xray/

## Respuesta rápida

> **Xray** es una app de gestión de pruebas que se instala sobre **Jira** y agrega siete tipos de *issue* propios: **Test**, **Precondition**, **Test Set**, **Test Repository**, **Test Plan**, **Test Execution** y **Test Run**. El flujo habitual es crear un Test, agruparlo en un **Test Set** para reutilizarlo, incluirlo en un **Test Plan** para una versión concreta, ejecutarlo dentro de un **Test Execution** en un entorno determinado, y de ahí salen el resultado y los informes de cobertura de requisitos. El matiz que casi nadie explica: estos tipos de issue conviven al **mismo nivel jerárquico** en Jira, sin relación nativa de padre e hijo entre ellos; la agrupación es funcional, no jerárquica. La jerarquía visual real la aporta el **Test Repository**, con su estructura de carpetas. Esta guía da por sentado [qué es un caso de prueba](../que-es-un-caso-de-prueba/index.md) y cómo se [diseña a partir de requisitos](../disenar-casos-de-prueba-a-partir-de-requisitos/index.md): el foco acá es cómo esos conceptos se traducen a los issues reales de Xray.

## Qué es Xray y qué le agrega a Jira

**Jira** es la herramienta de seguimiento de incidencias (*issues*) y gestión ágil de Atlassian que gran parte de los equipos de desarrollo ya usa para historias de usuario, tareas y errores (*bugs*). Por sí sola, Jira no tiene un concepto nativo de «caso de prueba»: para eso existen complementos de gestión de pruebas que se instalan encima. **Xray** es uno de los más usados: agrega siete tipos de issue propios que conviven, dentro del mismo proyecto, con los tipos nativos de Jira como historia o bug.

Conviene aclarar desde acá que Xray tiene dos variantes con documentación distinta: **Xray Cloud**, para instancias de Jira Cloud, y **Xray Server / Data Center**, para instancias alojadas por el propio equipo. Los conceptos son los mismos en las dos, pero algunos nombres de pantalla y flujos de configuración cambian. Cuando esta guía menciona un dato específico de interfaz, es de Xray Cloud.

## Los siete tipos de issue y el matiz jerárquico

Xray añade siete tipos de issue nativos de Jira, cada uno con un propósito distinto dentro de la gestión de pruebas:

- **Test:** el caso de prueba, con sus pasos y su resultado esperado.
- **Precondition:** una condición previa reutilizable (por ejemplo, «usuario con sesión iniciada») que uno o varios Test requieren antes de ejecutarse.
- **Test Set:** colección lógica de Test agrupados por un criterio funcional, no por versión.
- **Test Repository:** el árbol de carpetas donde vive cada Test del proyecto.
- **Test Plan:** qué Test hay que ejecutar para una versión o ciclo de entrega concreto.
- **Test Execution:** la instancia real de ejecución de un grupo de Test en un entorno determinado.
- **Test Run:** el resultado individual de un Test en una ejecución puntual; se genera al agregar un Test a un Test Execution.

> **El matiz que casi nadie explica**
>
> Story, Precondition, Test, Test Set, Test Plan y Test Execution son tipos de issue de Jira ubicados al **mismo nivel jerárquico**. No existe una relación nativa de padre e hijo entre ellos, como sí la hay entre una Epic y las historias que agrupa. Cuando un Test Plan «contiene» Test, esa contención es una asociación funcional que Xray gestiona con enlaces entre issues, no una jerarquía de Jira. La jerarquía visual real la aporta el **Test Repository**, con su estructura de carpetas.

![Diagrama de los tipos de issue de Xray para Jira mapeados a cuatro fases: planificar, diseñar, ejecutar y reportar. En planificar aparece el Test Plan. En diseñar aparecen el Test y la Precondition, agrupados en un Test Set reutilizable. En ejecutar aparece el Test Execution, que genera un Test Run por cada test incluido. En reportar aparece nuevamente el Test Execution junto con los informes de cobertura de requisitos. Debajo, una fila muestra a Story, Precondition, Test, Test Set, Test Plan y Test Execution como issues de Jira ubicados al mismo nivel jerárquico, sin flechas de padre a hijo entre ellos, para remarcar que la relación entre estos tipos de issue es una asociación funcional y no una jerarquía nativa de Jira. Al final se explica que la jerarquía visual real la aporta el séptimo tipo de issue, el Test Repository, mediante una estructura de carpetas y subcarpetas donde vive cada test, y se aclara que el diagrama refleja la terminología de Xray Cloud, que puede variar en las versiones Server y Data Center.](../../assets/img/guias/xray-tipos-de-issue.svg)

*Las cuatro fases ordenan el trabajo, pero no crean jerarquía entre los tipos de issue: esa jerarquía visual la da el Test Repository, con sus carpetas.*

## El flujo de trabajo completo

Lo que importa es el recorrido que hace un caso de prueba desde que se escribe hasta que su resultado queda reportado. En un proyecto típico de Xray tiene cinco pasos:

1. **Crear el Test.** Se escribe a partir de un requisito o una historia ya [diseñada](../disenar-casos-de-prueba-a-partir-de-requisitos/index.md), y se vincula a ese requisito desde que se crea.
2. **Agruparlo en un Test Set.** Si pertenece a una categoría reutilizable —seguridad, regresión de humo, checkout—, se suma al Test Set correspondiente. Un Test puede estar en varios a la vez.
3. **Planificarlo en un Test Plan.** Para una versión concreta, se arma un Test Plan con los Test que hay que validar antes de liberarla.
4. **Ejecutarlo en un Test Execution.** Se crea una instancia para un entorno determinado (staging, producción). Cada Test agregado genera un Test Run, donde se registra si pasó, falló o quedó bloqueado.
5. **Reportar.** Si un Test Run falla, se crea o vincula un defecto (Bug). Desde el Test Plan se ve el estado agregado y la cobertura de requisitos.

No son obligatorios en ese orden estricto siempre: un equipo chico puede ejecutar un Test directamente, sin pasar por un Test Set. Lo que sí conviene mantener siempre es el vínculo entre el Test y el requisito, porque de ahí sale toda la trazabilidad posterior.

## Test Set, Test Plan y Test Execution: no son lo mismo

Es la confusión más común de todo el sistema, porque los tres «agrupan» Test pero responden preguntas distintas.

| Aspecto | Test Set | Test Plan | Test Execution |
|---|---|---|---|
| Qué es | Colección lógica reutilizable | Selección de tests para una versión | Instancia real de ejecución en un entorno |
| Pregunta que responde | ¿Qué tests pertenecen a esta categoría? | ¿Qué hay que probar para esta entrega? | ¿Qué resultado dio esta ronda en este entorno? |
| ¿Guarda resultados? | No | Agrega el estado de sus ejecuciones | Sí, un Test Run por cada test |
| Reutilización | Un test puede estar en varios Test Sets | Suele crearse uno por versión o ciclo | Suele crearse uno por entorno o ronda |

El error típico es asumir que el Test Set «ejecuta» algo: no lo hace, solo organiza. El segundo es tratar el Test Execution como permanente: en la práctica se crean varias instancias para el mismo Test Plan, una por cada entorno o ronda, y todas aportan al mismo informe de cobertura.

## Trazabilidad: requisitos, tests y defectos

La trazabilidad es la posibilidad de recorrer la cadena completa: qué requisito dio origen a qué Test, en qué Test Execution se corrió, y qué defecto se abrió si falló. En Xray esa cadena se arma con enlaces explícitos, no de forma automática: un Test se vincula al requisito mediante un tipo de enlace que la propia app agrega (habitualmente «Tests»), y un Test Run fallido se puede vincular a un Bug existente o generar uno nuevo.

Para encontrar rápido, por ejemplo, todas las Test Execution asociadas a una versión concreta, alcanza con una consulta en **JQL** (*Jira Query Language*, el lenguaje de búsqueda estructurada propio de Jira):

```jql
project = "QA" AND issuetype = "Test Execution" AND fixVersion = "2.4.0"
ORDER BY created DESC
```

Sin el enlace entre el Test y el requisito, esa cadena se corta: el Test puede ejecutarse y hasta pasar, pero el informe de cobertura no va a contarlo como parte de la verificación de esa historia. Por eso conviene vincular apenas se crea el Test, no como tarea de revisión posterior.

## Organizar un repositorio grande con el Test Repository

Cuando el número de Test crece a cientos o miles, la organización deja de ser opcional. El **Test Repository** es el árbol de carpetas y subcarpetas donde cada Test tiene un único lugar fijo, y es la pieza que da orden visual al conjunto.

- **Organizá por módulo o funcionalidad**, no por sprint ni por quién escribió el test: un Test suele sobrevivir muchos sprints y termina usándolo más de un equipo.
- **Usá los Test Set para lo transversal**: etiquetas funcionales que cruzan varias carpetas, como «regresión de humo» o «pruebas de seguridad».
- **Mantené las carpetas poco profundas**: un árbol de dos o tres niveles se navega mejor que uno con diez subniveles.
- **Revisá periódicamente Test huérfanos**: los que quedaron sin vínculo a un requisito o sin uso en ningún Test Set reciente.

La combinación de carpetas para la ubicación única y Test Set para las agrupaciones transversales es lo que evita que un repositorio grande se convierta en una lista plana imposible de mantener.

## Qué informes salen de Xray

Todo el trabajo de vincular y ejecutar tiene una razón práctica: alimentar informes que respondan preguntas concretas antes de una entrega. Desde un **Test Plan** se ve el estado agregado de sus Test —cuántos pasaron, cuántos fallaron, cuántos faltan— y el informe de **cobertura de requisitos**, que cruza cada historia con los Test que la verifican y su resultado más reciente. Desde un **Test Execution** puntual se ve el detalle fino: el resultado de cada Test Run, con su evidencia y el defecto vinculado si corresponde. Sin los enlaces entre Test y requisito, lo único que queda es una lista de ejecuciones sueltas, sin forma de responder qué parte del producto está realmente cubierta.

## Alternativas a Xray

Xray no es la única app de gestión de pruebas para Jira. **Zephyr**, en sus distintas variantes, y **QMETRY** son las dos alternativas que más se mencionan en la industria, y las tres resuelven un problema parecido con una jerarquía conceptual similar, aunque con nombres propios: en QMETRY el camino habitual es caso de prueba → Test Cycle → Test Plan → Test Report, según un hilo de la comunidad de Underc0de escrito por **ANTRAX** que describe esa herramienta hermana y menciona explícitamente a Xray y a Zephyr como alternativas (sus datos de precios están desactualizados y no se repiten acá; más detalle en la sección de [fuentes](#fuentes)).

La elección entre las tres suele depender de la integración con el framework de automatización que ya usa el equipo y del licenciamiento vigente, que conviene revisar siempre en el sitio oficial de cada producto.

## Errores frecuentes

- **Creer que Test Plan, Test Set y Test Execution forman una jerarquía padre-hijo.** Son issues al mismo nivel; se relacionan por enlaces funcionales, no por herencia.
- **Confundir Test Set con Test Execution.** Uno agrupa de forma reutilizable, el otro ejecuta y guarda resultado en un entorno concreto.
- **No vincular el Test con el requisito al crearlo.** Sin ese enlace, la cobertura no lo contabiliza aunque el test se ejecute y pase.
- **Organizar el Test Repository por sprint.** Un Test sobrevive muchos sprints; conviene organizarlo por módulo o funcionalidad.
- **Pensar que Xray es la única opción sobre Jira.** Zephyr y QMETRY resuelven un problema equivalente con otra terminología.
- **Mezclar documentación de Xray Cloud con la de Server / Data Center.** Comparten conceptos, pero difieren en pantallas y flujos.

## Preguntas frecuentes

**¿Qué diferencia hay entre Test Set, Test Plan y Test Execution?**
Son tres tipos de issue que se confunden porque los tres «agrupan» tests, pero cada uno responde una pregunta distinta. El Test Set es una colección lógica y reutilizable, por ejemplo todos los tests de seguridad. El Test Plan define qué tests hay que ejecutar para una versión concreta. El Test Execution es la instancia real de ejecución: agrupa tests para correrlos y registrar un resultado en un entorno determinado. En síntesis: el Test Set organiza, el Test Plan planifica, el Test Execution ejecuta. Ninguno es «padre» de los otros: se relacionan por asociación, no por jerarquía nativa.

**¿Cómo se relacionan los casos de prueba con las historias de usuario en Jira?**
Una historia de usuario (Story) y un Test de Xray son dos tipos de issue independientes, al mismo nivel jerárquico: no hay relación padre-hijo automática entre ellos, como sí la hay entre una Epic y sus historias. El vínculo se crea explícitamente con un enlace que Xray agrega, habitualmente «Tests», que conecta el Test con el requisito que verifica. De ese enlace sale la trazabilidad: Xray calcula la cobertura mostrando qué historias tienen tests y qué resultado dieron. Sin el enlace, el Test puede pasar igual, pero el informe de cobertura no lo cuenta. Por eso conviene vincularlo apenas se crea.

**¿Xray es gratis o de pago?**
Xray es un producto comercial: se instala como app sobre Jira Cloud o Server / Data Center, y su uso continuado requiere una licencia. Suele existir una evaluación gratuita por tiempo limitado, pero los planes y precios cambian con el tiempo y varían según el equipo y la versión, así que esta guía no incluye cifras. Para el costo y las condiciones vigentes, la fuente confiable es el sitio oficial de Xray o el Atlassian Marketplace. Si el presupuesto es una limitación, vale comparar contra Zephyr o QMETRY, también comerciales.

**¿Qué alternativas a Xray existen para gestionar pruebas en Jira?**
Xray no es la única app de gestión de pruebas para Jira. Zephyr y QMETRY son las alternativas que más se mencionan, y resuelven un problema parecido con una jerarquía conceptual similar aunque con nombres propios: en QMETRY el camino habitual es caso de prueba, Test Cycle, Test Plan y Test Report, según un hilo de la comunidad de Underc0de escrito por ANTRAX, que menciona explícitamente a Xray y a Zephyr como alternativas. La elección suele depender de la integración con el framework que ya usa el equipo y del licenciamiento vigente, que conviene revisar en el sitio oficial de cada producto.

**¿Se puede automatizar la carga de resultados desde un framework externo?**
Sí, y es una de las razones por las que Xray se integra bien en pipelines de integración continua. Expone una API REST para importar resultados generados por frameworks externos —suites de Selenium, Cypress o Playwright que ya corren en CI—, de modo que el pipeline reporta el resultado sobre un Test Execution existente o recién creado, sin carga manual. Muchos equipos usan además formatos estándar como JUnit o Cucumber, que Xray interpreta para mapear cada test automatizado a su Test correspondiente. Los detalles de autenticación dependen de si se usa Xray Cloud o Server / Data Center.

**¿Cómo se organiza un repositorio grande de casos de prueba?**
La herramienta que da orden es el Test Repository, el séptimo tipo de issue de Xray: una estructura de carpetas donde cada Test vive en un único lugar. Conviene organizar esas carpetas por módulo o funcionalidad —Checkout, Autenticación, Reportes— y no por quién escribió el test ni por el sprint en que se creó, porque un Test sobrevive muchos sprints. Los Test Set sirven para cruzar esa organización con etiquetas transversales que no coinciden con la carpeta, como regresión de humo. Esa combinación permite que un repositorio con miles de tests siga siendo navegable.

## Fuentes

Documentación oficial y aporte de la comunidad consultados para esta guía. Fecha de consulta: 29 de julio de 2026.

### Aportes de la comunidad Underc0de

1. **Underc0de, foro.** [QMETRY desde cero](https://underc0de.org/foro/qa-testing/qmetry-desde-cero/), por *ANTRAX*, sección QA (Quality Assurance). Describe una jerarquía equivalente con una herramienta hermana y menciona a Xray y a Zephyr como alternativas; sus datos de precios y licencias están desactualizados y no se repiten en esta guía.

### Documentación oficial

1. **Xray.** [Xray Test Management for Jira](https://www.getxray.app/blog/xray-test-management-for-jira), blog oficial. Panorama general de la app y sus tipos de issue.
2. **Xray.** [Documentación: Overview (Xray Cloud)](https://docs.getxray.app/display/XRAYCLOUD/Overview). Estructura general de la app y sus componentes.
3. **Xray.** [Documentación: Test Plan (Xray Cloud)](https://docs.getxray.app/display/XRAYCLOUD/Test+Plan). Definición y uso del Test Plan.
4. **Xray.** [Documentación: Test Execution (Xray Cloud)](https://docs.getxray.app/display/XRAYCLOUD/Test+Execution). Definición y uso del Test Execution.
5. **Xray.** [Documentación: Test Set (Xray Cloud)](https://docs.getxray.app/display/XRAYCLOUD/Test+Set). Definición y uso del Test Set.
6. **Atlassian.** [What is an issue?](https://support.atlassian.com/jira-software-cloud/docs/what-is-an-issue/). Concepto base de issue en Jira, sobre el que se apoyan los tipos de Xray.

## Origen comunitario

En el foro de Underc0de no hay hilos dedicados a Jira ni a Xray. El punto de partida comunitario de esta guía es «QMETRY desde cero», de ANTRAX, que describe una jerarquía de gestión de pruebas equivalente con una herramienta hermana. Esta guía traslada esos conceptos a los tipos de issue reales de Xray y suma documentación oficial para completar el mapeo. [Ver el hilo de QMETRY en el foro →](https://underc0de.org/foro/qa-testing/qmetry-desde-cero/)

## Guías relacionadas

- [Qué es un caso de prueba](../que-es-un-caso-de-prueba/index.md)
- [Diseñar casos a partir de requisitos](../disenar-casos-de-prueba-a-partir-de-requisitos/index.md)
- [Cómo reportar un bug correctamente](../como-reportar-un-bug-correctamente/index.md)
- [Cómo crear un plan de pruebas completo](../como-crear-un-plan-de-pruebas-completo/index.md)
- [Estrategias de prueba](../estrategias-de-prueba/index.md)

**URL canónica:** https://underc0de.org/guias/testing/gestionar-casos-de-prueba-con-jira-y-xray/