how-it-works · agentic-qa · test-documentation
Scopes, nomenclatura perfecta, técnicas de diseño, parametrización y el arte de priorizar con ROI — el puente entre la QA manual y la automatización, con o sin Xray.
la forma sana
qué cubriremos
4 quizzes interactivos a lo largo del recorrido — haz clic en las respuestas.
qué es este skill
Identifica escenarios reales (flujos de usuario), separa lo transversal (XSS, perf, a11y se validan DENTRO de otros TCs, no son TCs).
Cada escenario pasa 3 filtros + fórmula ROI → un veredicto: Candidate, Manual o Deferred. Nunca se salta.
Crea TC/ATP/ATR en el TMS con trazabilidad completa, según la modalidad (Xray o Jira-native).
Solo se documenta comportamiento ya validado (US QA Approved, bug cerrado, sesión exploratoria terminada). El TMS es herramienta de documentación y protección de regresión — no de exploración.
PARTE 01
Cuatro scopes comparten el mismo pipeline Analyze→Prioritize→Document. Solo cambian la fuente de entrada y los defaults. El input decide el scope.
los cuatro scopes
| Scope | Input | Volumen | Cuándo |
|---|---|---|---|
| Module-driven | Un módulo explorado end-to-end | 20-100+ | Batch bajo el Epic de Regresión. La mayoría será Deferred. |
| Ticket-driven | Una US QA Approved de sprint | 3-8 | Salida de una sesión sprint-testing. ATP/ATR por US. |
| Bug-driven | Un bug cerrado con fix verificado | 0-2 | Corre la decisión bug-driven. ROI sesgado arriba: "falló una vez, puede fallar de nuevo". |
| Ad-hoc / Exploratorio | Escenarios nuevos de testing exploratorio | 1-10 | Aplica los 3 filtros con dureza — suelen ser validaciones de una sola vez. |
El scope NO cambia el método (Analyze→Prioritize→Document); cambia de dónde sacas los escenarios y qué labels por defecto aplicas.
los dos scopes de volumen
Exploras un módulo completo. 20-100+ escenarios. Batch bajo el Epic de Regresión, agrupado por un Test Set (1:1 con el Epic/feature). La mayoría termina Deferred — derivas amplio, persistes poco.
Una US aprobada en sprint. 3-8 escenarios. ATP/ATR creados por historia. Es la salida natural de una sesión de /sprint-testing que pasa a documentarse.
El ATP se escribió ANTES del código. Antes de crear cualquier TC: grep data-testid=, rutas, formatos de texto. Corrige divergencias en una sección Refinement Notes. Saltarlo = la causa #1 de tests automatizados inválidos después.
la regla de oro
No todo bug se vuelve TC de regresión. Pero si ES regression-worthy, debe terminar con un Test — en ambas modalidades.
# 1. ¿Es candidato de regresión? (filtros Phase-0 + ROI; la regla de bug previo sesga arriba) NO → Sin Test nuevo. Trátalo como test fallido (fix ya verificado) → Deferred. YES → paso 2. # 2. ¿El bug salió de un Test ya ejecutado que falló? YES → REUSA ese Test para retest + regresión. Ya existe; enlázalo (tests / is tested by). NO dupliques. NO → CREA + diseña el Test correspondiente. Enlázalo al bug (tests / is tested by).
Escenarios sueltos de exploración. Aplica los 3 filtros con dureza — son a menudo validaciones de una sola vez → casi siempre Deferred.
quiz · parte 1
PARTE 02
Una sola regla de nombrado, una sola regla de identidad. Un nombre mal puesto es un test que nadie encuentra, nadie entiende y nadie mantiene.
la regla que más importa
qué hace el sistema: log in successfully, show an authentication error, create the order.
when credentials are valid, when password is incorrect, when exceeding 5 failed attempts.
Separador literal : (dos puntos + espacio). El verbo should abre el comportamiento; el conector when (o if) introduce la condición — opcional, igual que un given <precondición> al final. TC# = TC + número, sin guion ni ceros (TC1, no TC-01). El prefijo es SIEMPRE el US_ID de la Story, en toda modalidad; la membresía a un Test Set es un link, nunca el prefijo.
anti-patrones a rechazar
| ❌ Mal | ✓ Bien | Por qué |
|---|---|---|
| Login test | GX-101: TC1: should log in successfully when credentials are valid | Falta ID, TC#, behavior, condition |
| Login - error | GX-101: TC2: should show an authentication error when password is incorrect | Demasiado vago |
| TC1: Test form | GX-101: TC1: should submit the form when all fields are valid | Falta ID; behavior no específico |
| should work | GX-101: TC1: should log in successfully when credentials are valid | should sin behavior ni condición concretos |
Positivo: should log in successfully when credentials are valid · Negativo: should show an authentication error when password is incorrect · Boundary: should enforce the limit when entering exactly 50 chars · Edge: should merge quantities when the cart has multiple same items.
la segunda regla de oro
Todos los resultados esperados del mismo par (precondición, acción) pertenecen al mismo TC — no a TCs separados.
Partir un (precondición, acción) en "TC1: check panel A", "TC2: check panel B"… es el error más diagnosticado. Es un TC con múltiples assertions, no tres TCs.
el sistema completo de nombrado
| Artefacto | Formato | Ejemplo |
|---|---|---|
| User Story | {KEY}-{n} | PROJ-123 |
| ATP — Story Test Plan | ATP: {STORY-KEY}: {story title} | ATP: PROJ-123: Apply discount at checkout |
| ATR — Story Test Execution | ATR: {STORY-KEY}: Story Testing | ATR: PROJ-123: Story Testing |
| STP/STR — Sprint | STP/STR: Sprint#{N}: Regression[ Testing] | STR: Sprint#30: Regression Testing |
| Test Set (agrupa) | TS: {EPIC-KEY|module}: Validate <feature> | TS: GX-101: Validate credit card payment |
| Test Case (asevera) | {US_ID}: TC#: should <BEHAVIOR> when <COND> | GX-101: TC1: should log in successfully when… |
| ReTesting (bug) | ReTest: {BUG-KEY}: {summary} | ReTest: GX-202: wrong error on bad password |
| Precondition | PRC: {COMPONENT}: {required state} | PRC: Payment: Authenticated user with a saved card |
El Set nombra la feature — TS: GX-101: Validate login — y bajo él cada TC asevera un comportamiento: should redirect to dashboard when credentials are valid, should show an error when password is incorrect. El prefijo acrónimo (ATP/ATR/STP/STR/TS/PRC) revela altitud y plan-vs-run en el primer token; el verbo te dice el nivel: Validate = suite, should = caso.
trazabilidad end-to-end
GX-101: TC1: should log in successfully when credentials are valid
Voz BDD: should <behavior> when <condition>.
@atc('GX-101')
test('GX-101: should log in when credentials valid', …)
Voz BDD: should <behavior> when <condition>.
El título del TC y el nombre del test() hablan ambos should…when y llevan el mismo key del TMS. No solo coincide el identificador — coincide la frase. Eso es trazabilidad sin costuras: el outline, el TC y el código dicen lo mismo.
quiz · parte 2
PARTE 03
Cómo se escribe un TC: Gherkin para candidatos, tablas para manual; técnicas de diseño que deciden el SET de TCs; parametrización con variables, nunca datos hardcodeados.
cómo escribir el cuerpo
| Criterio | Gherkin | Tradicional |
|---|---|---|
| Candidato a automatización | Sí | No |
| Pasos deterministas | Sí | Pueden variar |
| Resultados esperados exactos | Sí | Subjetivos |
| Requiere juicio humano | No | Sí |
Columnas fijas: Step | Action | Test Data | Expected Result. Dato vacío = -. Úsala para verificación visual/subjetiva, elementos exploratorios o TCs marcados manual-only.
el patrón de alta calidad
@critical @regression @automation-candidate @{US_ID} Scenario Outline: should <behavior> when <condition> """ Bugs covered: BUG-1, BUG-2 · Related Story: {US_ID} · ROI: 5.2 """ # === PRECONDITIONS (tester / script las construye) === Given a <entity> exists with <identifier> where <quantity> <condition> # === ACTION === When the user navigates to "<route>" and <main_action> # === VALIDATIONS === Then <ui_element> is displayed with format "<expected_format>" # === EQUIVALENT PARTITIONS === Examples: Happy path | Edge case | Singular vs plural
Tags (priority + @regression + @automation-candidate + @{US_ID}) · docstring con metadata · banners # === … === · variables, nunca datos hardcodeados · un Examples por partición de equivalencia.
1 AC → N TCs (deriva por técnica)
| Disparador en el AC | Técnica | TCs que produce |
|---|---|---|
| Cualquier input (siempre) | Equivalence Partitioning | mismo output → 1 TC parametrizado; distinto output → TCs separados |
| Rango / límite / longitud / fecha | Boundary Value Analysis | min-1·min·min+1 … max-1·max·max+1 + zero/empty/null/overflow |
| Un estado / ciclo de vida | State-Transition | 1 TC por transición válida + 1 por inválida |
| 2+ condiciones que interactúan | Decision Table | enumera combos, colapsa equivalentes, 1 TC por regla |
| 3+ factores combinables | Pairwise | set all-pairs (registra la reducción) |
Estas son candidatas derivadas por técnica — aún no work items del TMS. La técnica gobierna la forma de lo que documentas, no el cuánto. EP siempre; BVA donde haya rango; el resto por disparador.
técnica 1/5 · teoría
Particiona el dominio de entrada en clases donde todos los miembros se comportan igual. Prueba UN representante por clase — reduce infinitas entradas a pocos casos.
Cualquier input (siempre aplica). Es el piso de todo diseño de TC.
Mismo output → 1 TC parametrizado. Distinto output → TCs separados. Cubre clases válidas E inválidas.
Probar 5 emails válidos distintos es desperdiciar 4 TCs: todos viven en la misma clase. Un representante basta. El valor está en cubrir todas las clases, no en repetir dentro de una.
técnica 1/5 · en la práctica
credenciales correctas
1 TC representante
password mala · user inexistente · formato roto
1 TC parametrizado (mismo 401)
cuenta con 5 intentos fallidos
TC separado (distinto output)
Las 3 razones de fallo "credencial inválida" comparten salida (401) → un Scenario Outline con 3 filas de Examples. Pero 423 es otra clase de salida → su propio TC. EP decidió el SET: 3 TCs, no 5.
técnica 2/5 · teoría
Los defectos se concentran en los bordes de las clases de equivalencia. EP elige el representante; BVA ataca justo donde el código suele equivocarse: el límite.
Rango · límite · longitud · ventana de fecha · cuota · paginación. Donde haya un número que marque una frontera.
min-1 · min · min+1
max-1 · max · max+1
+ zero / empty / null / overflow
EP probaría "un valor válido y uno inválido" y se perdería el clásico off-by-one (< vs <=). BVA es obligatoria siempre que un AC nombre un rango o límite.
técnica 2/5 · en la práctica
| Longitud | Posición | Esperado |
|---|---|---|
| 0 / vacío | zero / empty | reject "campo requerido" |
| 7 | min − 1 | reject "mínimo 8" |
| 8 | min | accept |
| 9 | min + 1 | accept |
| 19 | max − 1 | accept |
| 20 | max | accept |
| 21 | max + 1 | reject "máximo 20" |
Esos cuatro valores prueban que la comparación usa >=8 y <=20 exactos. Como comparten salida por lado, van como filas de un Examples dentro de uno o dos TCs — no siete TCs sueltos.
técnica 3/5 · teoría
Para entidades con estado, modela los estados y las transiciones entre ellos. Cada movimiento permitido y cada movimiento prohibido es un caso de prueba.
Un campo de estado o ciclo de vida: orden, suscripción, ticket, cuenta, documento.
1 TC por transición válida + 1 por transición inválida. Intentar lo prohibido debe ser rechazado limpiamente.
En las transiciones inválidas. El happy path (avanzar de estado) casi siempre funciona; lo que rompe es cuando alguien intenta saltar o retroceder un estado que el negocio no permite.
técnica 3/5 · en la práctica
técnica 4/5 · teoría
Cuando 2+ condiciones interactúan para decidir una acción, enumera todas las combinaciones de condiciones → su resultado. Colapsa las imposibles o equivalentes. 1 TC por regla sobreviviente.
2+ condiciones que se combinan: reglas de negocio con AND/OR, permisos, pricing, elegibilidad.
2 condiciones → 2² = 4 combos. 3 → 8. Enumera, colapsa reglas equivalentes, queda un set mínimo que cubre toda la lógica.
Garantiza que ninguna combinación de condiciones queda sin probar — el hueco típico cuando se diseñan TCs a ojo.
técnica 4/5 · en la práctica
Regla: envío gratis si es miembro O el carrito > $50.
| Regla | ¿Miembro? | ¿Carrito > $50? | Acción | TC |
|---|---|---|---|---|
| R1 | Sí | Sí | Envío gratis | colapsan → 1 TC |
| R2 | Sí | No | Envío gratis | |
| R3 | No | Sí | Envío gratis | TC propio |
| R4 | No | No | Cobra envío | TC propio |
R1 y R2 dan el mismo resultado porque ser miembro ya basta — el carrito es irrelevante ahí. Colapsan en 1 TC ("miembro → gratis sin importar carrito"). 4 combos → 3 TCs que cubren toda la lógica.
técnica 5/5 · teoría
Con 3+ factores combinables, la combinación completa explota. Pairwise cubre cada par de valores con muchísimos menos casos — porque la mayoría de defectos surgen de la interacción de dos factores, no de cinco a la vez.
3+ factores que se combinan: browser × OS × plan, rol × permiso × feature flag, idioma × moneda × región.
Genera el set all-pairs y registra la reducción — que se vea "apliqué pairwise: 72 → 9", nunca un recorte silencioso.
Pairwise asume que los bugs por interacción de 3+ factores simultáneos son raros. Si tu dominio sí los tiene (ej. seguridad), complementa con casos dirigidos.
técnica 5/5 · en la práctica
Chrome · Firefox · Safari
Windows · macOS · Linux
Free · Pro
Un solo TC parametrizado: Scenario Outline con 9 filas de Examples (browser, os, plan) + la nota "pairwise: 18→9" para que la reducción sea auditable.
las 5 técnicas en una mirada
| Técnica | Disparador en el AC | Produce | Ejemplo del deck |
|---|---|---|---|
| Equivalence Partitioning | Cualquier input (siempre) | 1 TC por clase de salida | login: inválidas→401 (1 TC) vs bloqueada→423 (1 TC) |
| Boundary Value Analysis | Rango · límite · longitud · fecha | min±1, max±1 + zero/null | password 8-20: prueba 7·8·9 y 19·20·21 |
| State-Transition | Un campo de estado / ciclo de vida | 1 TC por transición válida + inválida | orden: cancelar un Shipped → rechazo |
| Decision Table | 2+ condiciones que interactúan | 1 TC por regla (colapsa equivalentes) | envío gratis: 4 combos → 3 TCs |
| Pairwise | 3+ factores combinables | set all-pairs (log de la reducción) | browser×OS×plan: 18 → 9 |
EP es el piso (siempre aplica); las demás se gatillan por la forma del AC. Derivas amplio por técnica (1:N), persistes por ROI. La técnica gobierna la forma de lo que documentas, no el cuánto.
quiz · las 5 técnicas (1/2)
quiz · las 5 técnicas (2/2)
data-driven sin hardcodear
Los valores que varían por corrida, una tabla por partición de equivalencia. Un valor que cambia el caso → columna de Examples.
En la Description: explica cómo obtener cada variable en runtime (la query SQL). No varía por corrida. Un valor que buscas para correr → fila de Variables.
# MAL — hardcoded Given a mentor exists with user_id "550e8400-e29b-41d4-a716-446655440000" # BIEN — patrón variable + tabla Variables que dice cómo obtenerlo Given a verified mentor exists with {mentor_id} in the database # {mentor_id} → SELECT id FROM profiles WHERE role='mentor' AND is_verified=true LIMIT 1
Cuando el AC mismo define el valor: Then the field must accept maximum 500 characters o Then the rating is displayed in "X.X/5.0" format. Beneficios: durabilidad, portabilidad, claridad, automatización.
quiz · parametrización
PARTE 04
La mayoría de los escenarios deben terminar Deferred. El ROI decide cuáles valen el costo de mantener: Valor sobre Costo, sesgado por Riesgo.
deriva amplio, persiste poco
Considera muchos casos por técnica (1:N). Vive en el análisis de priorización, no aún en el TMS. Gratis.
Crea un TC persistente solo para lo que vale re-ejecutar: Candidate + Manual. Deferred va al reporte, no al TMS.
Los Candidates fluyen a /test-automation. Los pocos.
Analizaste 80, documentaste 12, automatizaste 8 — nunca "documenta los 80". Un test entra al repositorio porque se va a re-ejecutar, jamás para llegar a un conteo. Si >50% queda Candidate/Manual, re-aplica el filtro más duro.
el gate antes del ROI
Si fue un typo de una sola vez en área estable, la respuesta es no → Defer.
Sí → prioriza aun con ROI moderado ("falló una vez, puede fallar de nuevo"). La regla de bug previo sobreescribe los umbrales.
XSS / a11y / performance / responsive son suites a nivel app, no TCs por feature → Defer de este scope (handoff explícito, no drop silencioso).
"Mobile responsive", "XSS", "Performance" se validan dentro de otros TCs o en una suite a nivel app — nunca como TC propio.
valor sobre costo
cada factor, escala 1-5
| Factor | 1 | 2 | 3 | 4 | 5 |
|---|---|---|---|---|---|
| Frequency (cuán seguido corre) | Anual | Por release | Por sprint | Diario | Por PR/commit |
| Impact (si falla) | Cosmético | Molestia menor | Degrada UX | Bloquea feature | Revenue / core |
| Stability (del flujo) | Muy volátil | Inestable | Moderado | Estable | Sin cambios meses |
| Effort ÷ (automatizar) | Trivial | Bajo (horas) | Medio (1-2 días) | Alto (varios días) | Muy alto (semana+) |
| Dependencies ÷ | Ninguna | 1-2 simples | 3-4 | 5+ | Externos complejos |
Si un TC se reutiliza en N flujos E2E: Component Value = Base ROI × (1 + 0.2 × N). Un átomo de ROI bajo como authenticateSuccessfully se vuelve automatizable puro por reutilización.
cada escenario termina en uno
| Veredicto | Lo dispara | A dónde va |
|---|---|---|
| Candidate | ROI > 3.0, O (ROI 1.5-3.0 Y bug previo), O happy path crítico | Alimenta /test-automation. Draft→In Design→Ready→In Review→Candidate |
| Manual | ROI 0.5-1.5 Y no automatizable (juicio humano, inspección visual) | Terminal: suite de regresión manual. No es callejón sin salida — puede volver a In Review si el ROI cambia |
| Deferred | ROI < 0.5, O falla un filtro Phase-0, O validación de una sola vez | Terminal: NO entra a regresión. jira-native: no se crea TC, va al reporte. jira-xray: el Test de sprint queda sin promover |
El veredicto ROI es idéntico en ambas modalidades. jira-native: Phase 3 crea Tests para Candidate+Manual. jira-xray: los Tests ya existen del sprint; Phase 3 los promueve al Test Plan de regresión y los enriquece.
scoreando un escenario real
> 3.0 + happy path crítico → Candidate
Sin bug previo + validación de una vez → falla Phase-0 → Deferred
quiz · parte 4
PARTE 05
Los mismos conceptos (ATP, ATR, TC) viven en contenedores distintos según la modalidad. Resuélvela en Phase 0, antes de documentar.
mismos conceptos, distinto contenedor
| Artefacto | Modality jira-xray | Modality jira-native |
|---|---|---|
| ATP | Issue Test Plan, enlazado al Story | Campo {{acceptance_test_plan}} del Story (o comment fallback). Sin issue. |
| ATR | Issue Test Execution con Test Runs por TC, Environment, fechas | Campo {{acceptance_test_results}} del Story. Sin issue. |
| TC | Issue Test (Manual / Cucumber / Generic) | Issue type Test nativo; Description lleva el template completo |
| Test Set / Precondition | Issue types de primera clase de Xray | No existen — labels + agrupación por Epic |
| Sync de resultados | CI importa JUnit/Cucumber → Test Runs auto-actualizan | Script custom actualiza el campo Test Status por TC |
¿El proyecto tiene Xray instalado y licenciado? Auto-resuelve por {{TMS_CLI}}, luego master-test-plan.md, luego listando issue types. Solo pregunta si los 3 fallan. Sticky — no la re-resuelvas a mitad de sesión.
la distinción que arregla los dashboards
"¿Dónde está el TC en su vida de documentación/automatización?" Persiste entre corridas.
"¿Pasó la última vez que se corrió?" Resetea cada ejecución.
Automated (workflow) + FAIL (última corrida) es una combinación válida y común: el TC está vivo en CI, pero hoy falló. El rollup PASSED/FAILED del ATR viene del Execution Status, no del Test Status. Confundirlos es la causa #1 de dashboards y JQL malos.
el state machine del TC
Draft no salta a Automated.
Solo "back to In Design" y "→ Deprecated".
Manual puede volver a In Review si el ROI cambia.
Mueve cuantos razonables a Automated.
cómo cuelgan los artefactos
User Story (PROJ-123) ├── is tested by ──→ ATP (ATP: PROJ-123: Apply discount at checkout) └── is tested by ──→ ATR (ATR: PROJ-123: Story Testing) ATP designs ATR executes ╲ ╱ ▼ ▼ [ TC-1, TC-2, … TC-N ] # cada uno cubre un AC # El Story enlaza SOLO a ATP y ATR. Los TCs agregan vía ATP/ATR — nunca directo.
El TC nunca se enlaza al Story directo. ATP designs TC, ATR executes TC. Evita ruido de links. Crea ATP y ATR antes del primer TC.
Sin issues ATP/ATR, el TC sí se enlaza al Story vía is tested by — es la única arista de trazabilidad disponible.
Scope por el input → título de 4 segmentos + un (precond, acción) por TC → Gherkin con técnicas y variables → ROI = Valor/Costo sesgado por Riesgo → el TMS correcto, con o sin Xray.
← → navegar · S notas del orador · O resumen · T tema