10.3 Taller E10: demostrar CU-01 con evidencia

Al terminar esta lección

• Producir la matriz de riesgo y los 12 casos de CU-01, cada uno con nivel, oráculo y criterio de aceptación asociado.
• Diseñar integration tests de rollback, idempotencia y concurrencia con oráculo de efectos y de ausencia de efectos.
• Diseñar dos contract tests y un plan de medición de NFR-01 que otra persona pueda repetir.
• Armar una RTM ejecutable y revisar el gate contra evidencia, dejando visibles los criterios que todavía no podés demostrar.

Práctica E10 · Demostrar CU-01

Situación. Diseñá la evidencia de aceptación del slice sin perseguir un porcentaje arbitrario de cobertura.

Entregá. matriz de riesgo; 12 casos; tests automatizados seleccionados; evidencia de ejecución; RTM mínima.

Está listo cuando. cada test defiende una propiedad; hay bordes, negativos, carrera y fallo externo; el oráculo mira efectos y ausencia de efectos; la evidencia se puede mostrar.

Solución comentada: Solución comentada E10. Comparala después de producir tu entrega.

Diseñá un plan de pruebas de CU-01 partiendo de riesgos. Para cada riesgo indicá nivel de prueba, preparación, estímulo, oráculo y evidencia.

1. Escribí casos normal, frontera y negativo para crédito, cantidad y precio.
2. Diseñá al menos tres integration tests: rollback, idempotencia y concurrencia real.
3. Diseñá dos contract tests para una integración externa, incluyendo timeout o respuesta inválida.
4. Elegí un NFR y explicá un entorno reproducible para medirlo. Incluí dataset, patrón de carga, duración y umbral.
5. Tomá un bug ficticio de producción y escribí el test de regresión que conservarías después de corregirlo.

Ejecutá una suite real o simulada y prepará un paquete de evidencia: comandos, outputs relevantes, defectos encontrados, correcciones y trazabilidad a RN y AC.

Criterio de revisión. Podés decir "está probado" solo cuando sabés qué propiedad defendiste, con qué mecanismo, en qué entorno y qué evidencia podría repetir otra persona.

Antes de empezar

Necesitás tres cosas a mano: el caso de uso CU-01 (versión 4, la que ya validó el equipo con Laura y Marta), la matriz de 10.3 con T01 a T12 y el catálogo de criterios de aceptación. Este es el catálogo completo, que es la fuente para la columna AC de tu RTM:

• AC-01: happy path. Pedido confirmado, precio snapshot y reserva creada.
• AC-02: exactamente en el límite de crédito. Aprobado según RN-01.
• AC-03: un centavo sobre el límite. Rechazo sin efectos.
• AC-04: precio calculado en servidor (RN-03). El cliente no fija el precio.
• AC-05: SKU inválido. Sin pedido parcial ni reservas.
• AC-06: última unidad concurrente. Exactamente una reserva (RN-05).
• AC-07: reintento idempotente y conflicto por requestId (RN-06).
• AC-08: autorización de crédito. Pedido pendiente con registro de la solicitud (CU-02).
• AC-09: cantidad inválida y múltiplos de venta (RN-08).
• AC-10: falla de persistencia. Rollback completo.
• AC-11: handoff a preparación por outbox.
• AC-12: proveedor externo caído. El pedido permanece válido.

Si una AC no tiene caso en tu matriz, eso es un hueco y se declara. No se resuelve escribiendo una fila que no defiende nada.

Recorrido guiado

El taller tiene siete pasos. Cada uno tiene objetivo, tiempo sugerido, un ejemplo parcial ya trabajado y un ejercicio. Las pistas y las soluciones parciales aparecen plegadas. La solución completa vive en 14.4 y la comparás al final, no antes.

Paso 1 · Matriz de riesgo (15 minutos)

Objetivo. Listar los riesgos de CU-01 y, para cada uno, la propiedad que amenaza.

Ejemplo parcial. Así se ve una fila completa:

• Riesgo: última unidad concurrente en CBA.
• Propiedad: RN-05, la disponibilidad nunca es negativa.
• Mecanismo: lectura y escritura separadas de stock_level.
• Nivel: integration concurrente con dos conexiones y barrera.
• Oráculo: un Reserved, un InsufficientStock, disponibilidad final 0 y una sola fila en reservation.

Paso 2 · Los 12 casos con criterio y nivel (25 minutos)

Objetivo. Completar la matriz T01 a T12 y cruzarla con el catálogo de AC.

Ejemplo parcial. T03 tiene estos campos:

• Riesgo: un centavo sobre el límite.
• Preparación: cliente estándar, saldo de 480.000, límite de 500.000, pedido de 20.000,01.
• Resultado: rechazo por crédito, sin pedido, sin reserva, sin débito.
• Nivel: unit para la regla e integration para los efectos.
• AC: AC-03, con RN-01 como fuente.

Antes de escribir los casos, revisá qué criterios ya tienen una fila y cuáles quedan afuera.

Paso 3 · Integration tests: rollback, idempotencia y concurrencia (30 minutos)

Objetivo. Escribir tres integration tests que observen efectos y ausencia de efectos. Los tres son obligatorios para E10.

Ejemplo parcial. Este es el esqueleto del rollback (T09). Suponé que el helper fixture y la inyección de fallos están disponibles en tests/support. Lo que falta son los oráculos:

1import { test } from "node:test";
2import assert from "node:assert/strict";
3import { fixture } from "../support/fixture";
4​
5test("T09: falla antes del commit no deja efectos (AC-10)", async () => {
6  const env = await fixture({
7    client: { id: "CLI-0042", tier: "estandar", balanceCents: 0, creditLimitCents: 50_000_000 },
8    stock: { "AX-442": { CBA: 10 } },
9    priceCents: { "AX-442": 1_190_000 },
10  });
11  env.failBefore("commit"); // inyecta el error justo antes del commit
12​
13  await assert.rejects(env.createOrder({
14    requestId: "req-903",
15    sellerId: "SEL-01",
16    clientId: "CLI-0042",
17    deliveryMethod: "pickup",
18    items: [{ sku: "AX-442", quantity: 1 }],
19  }));
20​
21  // completar: los oráculos de efectos ausentes
22});

Un detalle que el caso todavía no resuelve: el canon no define qué kind de resultado devuelve una falla de persistencia. Aquí usamos assert.rejects y dejamos la decisión registrada. Si el API tiene que responder con un código concreto, esa decisión va a la matriz de 10.2 como contrato.

Paso 4 · Dos contract tests para una integración externa (20 minutos)

Objetivo. Diseñar dos contract tests sobre el proveedor fiscal: timeout con efecto posible y respuesta inválida.

Ejemplo parcial. El timeout después de procesar es el caso más útil para practicar. El proveedor emitió el comprobante y nuestro adaptador no lo sabe. El oráculo tiene que verificar que el sistema no vuelve a emitir a ciegas: consulta por la clave de idempotencia y converge al estado real. Los estados posibles y sus transiciones están en el diagrama de 10.2.

Paso 5 · Plan de medición de NFR-01 (15 minutos)

Objetivo. Escribir un plan de medición que otra persona pueda repetir sin preguntarte nada.

Ejemplo parcial. NFR-01 pide que el p95 del registro de pedido, excluyendo el servicio fiscal, sea menor a 800 ms con 30 usuarios concurrentes. El plan tiene que dejar escrito todo lo que cambia el resultado:

1nfr: NFR-01
2escenario: registro de pedido, p95 menor a 800 ms con 30 usuarios concurrentes
3excluye: servicio fiscal (no participa de CU-01 en el primer release)
4entorno:
5  base: PostgreSQL 16 con la misma configuración de aislamiento que producción
6  aplicacion: una instancia del nodo de aplicación y el worker, mismo build del release candidate
7  hardware: completar
8dataset:
9  skus: 8000
10  vendedores: 25
11  clientes: 600 # completar con el criterio de muestreo
12  stock_inicial: completar # que no genere rechazos durante la medición
13carga:
14  rampa: de 0 a 30 usuarios en 2 minutos
15  estable: 30 usuarios durante 10 minutos
16  pausa_entre_pedidos: completar
17  calentamiento_descartado: completar
18medicion:
19  metrica: p95 y p99 de la duracion de POST /orders hasta la respuesta
20  corridas: completar
21criterio:
22  exito: completar
23  evidencia: completar

Paso 6 · Test de regresión sobre un bug ficticio (10 minutos)

Objetivo. Convertir un defecto ya corregido en una barrera automática.

Bug ficticio. En la versión 2.3 de la app de prueba, el endpoint de pedidos aplicaba un campo discountPercentage que el cliente enviaba en el request, y lo restaba del total antes de calcular el crédito. El defecto ya fue corregido. Ahora tenés que decidir qué test conservar.

Paso 7 · RTM ejecutable y paquete de evidencia (20 minutos)

Objetivo. Convertir la matriz en un artefacto que el código pueda verificar, y reunir la evidencia.

Una RTM en un documento de texto envejece en silencio. Una RTM ejecutable tiene su versión en el repositorio y un test que falla cuando una AC no tiene test asociado. Así, cada hueco queda visible en la salida de la suite.

1cu: CU-01
2rtm:
3  - ac: AC-06
4    rn: RN-05
5    riesgo: última unidad concurrente
6    nivel: integration concurrente
7    tests:
8      - tests/integration/stock-race.test.ts
9    evidencia: evidencia/stock-race-salida.txt
10    estado: probado
11  - ac: AC-03
12    rn: RN-01
13    riesgo: un centavo sobre el límite
14    nivel: unit + integration
15    tests:
16      - tests/integration/credit-boundary.test.ts
17    evidencia: evidencia/credit-boundary-salida.txt
18    estado: probado
19  - ac: AC-09
20    rn: RN-08
21    riesgo: cantidad inválida y múltiplos de venta
22    nivel: unit + integration
23    tests: []
24    estado: pendiente

1import { test } from "node:test";
2import assert from "node:assert/strict";
3import { readFileSync } from "node:fs";
4import { parse } from "yaml";
5​
6const rtm = parse(readFileSync("docs/rtm-cu-01.yaml", "utf8")) as {
7  rtm: Array<{ ac: string; tests: string[]; estado: string }>;
8};
9​
10for (const row of rtm.rtm) {
11  test(`${row.ac} tiene al menos un test o está declarado pendiente`, () => {
12    if (row.estado === "pendiente") return; // el hueco es visible en la RTM, no oculto
13    assert.ok(row.tests.length > 0, `${row.ac} no tiene tests asociados`);
14  });
15}

Esta versión deja pasar AC-09 porque está marcada como pendiente, y eso es correcto: el hueco existe y queda declarado. Si alguien cambia el estado a "probado" sin agregar un test, la suite se pone roja. Para AC-11, si la fila no existe en absoluto, el test no la ve: por eso la RTM tiene que listar todas las AC del catálogo, incluso las pendientes.

Antes de dar por buena la evidencia, ejecutá la secuencia en este orden y guardá cada salida:

Cuando armes el paquete de evidencia, incluí el comando exacto, el commit, la versión del entorno, la cantidad de ejecuciones de las pruebas concurrentes y la salida textual. El paquete tiene que permitir que otra persona reproduzca el resultado sin preguntarte nada. Si la evidencia depende de que vos la expliques, todavía no está lista.

Hoja de entrega 10 · completá antes de pasar el gate

Este bloque no se completa de memoria. Volvé a tus artefactos, a la evidencia y a los resultados de ejecución. El objetivo es hacer explícito qué vas a defender frente a un mentor o un cliente.

• Artefacto que entrego y versión:
• Tres evidencias que sostienen mis decisiones:
• Decisiones que tomé yo y que un agente no podía tomar:
• Desconocidos o riesgos que siguen abiertos:
• Feedback o propuesta de IA que rechacé, y por qué:
• Qué tendría que ocurrir para que yo mismo cambie esta conclusión:
• Revisión de calidad: qué corregí antes de enviar o presentar:
• Firma del mentor o reviewer, o referencia del feedback:

Gate 10 · podés afirmar que el comportamiento está probado

Guardá tu entrega

Cuando termines tu entrega, compará tu razonamiento con la solución comentada E10. No hay una única respuesta correcta: la comparación busca fuentes, decisiones y evidencia.

Errores frecuentes

• Síntoma: la matriz tiene doce filas, todas verdes, y la RTM tiene menos AC que el catálogo. Causa: la matriz se armó para llenar la tabla y no desde el catálogo de criterios. Corrección: partí del catálogo de AC y declará los huecos en lugar de omitirlos.
• Síntoma: el test de concurrencia pasa en la primera corrida y nadie guardó la cantidad de corridas. Causa: la evidencia depende de una ejecución y no de una secuencia. Corrección: repetí la prueba, guardá cada resultado y anotá el número en el paquete de evidencia.
• Síntoma: el contract test confirma el formato de la respuesta feliz y nada más. Causa: el fake solo modela el éxito. Corrección: agregá al menos timeout antes y después de procesar, rechazo permanente y respuesta sin identificador.
• Síntoma: el plan de NFR tiene el umbral pero no el dataset ni el calentamiento. Causa: se escribió el criterio antes de definir cómo medir. Corrección: completá entorno, dataset, carga, calentamiento, duración, percentil y corridas antes de medir, y no ajustes el umbral después.
• Síntoma: el gate se marca completo porque el agente informó que todo pasa. Causa: la evidencia es la afirmación del agente y no una salida guardada. Corrección: ejecutá la secuencia de evidencia y revisá la salida con tus propios ojos antes de marcar cada criterio.

Para llevarte

• La matriz sale del catálogo de criterios de aceptación. Los huecos se declaran, no se disimulan con filas que no defienden nada.
• Cada integration test de E10 observa efectos y ausencia de efectos en la base real. Si el oráculo solo mira el status, el test no está terminado.
• Los contract tests defienden la traducción a un tercero, sobre todo el timeout con efecto posible y la respuesta sin identificador.
• Un NFR se mide con un plan que otra persona pueda repetir: entorno, dataset, carga, calentamiento, corridas y criterio escritos antes de medir.
• La RTM ejecutable convierte la trazabilidad en algo que el código verifica. Un hueco declarado es información; un hueco escondido es un riesgo.
• Un criterio del gate se marca solo con evidencia guardada. Lo que no podés demostrar se deja visible con su motivo.