Probar Payment Emulator Lab

Índice / Index · English

Traducción de docs/en/operations/testing.md, que es el original. Si discrepan, manda el inglés.

El espacio de trabajo de la API usa Vitest 4. La suite combina pruebas unitarias puras, pruebas de propiedades, pruebas de integración con NestJS y Supertest, conformidad de proveedores y comprobaciones de compatibilidad con los SDK oficiales. Las aplicaciones Nuxt no tienen hoy una suite propia de navegador; las protegen el typecheck estricto, las compilaciones de producción y la humareda de pila entera.

#Órdenes

La suite completa:

npm test

La raíz delega en cada espacio de trabajo que tenga script de test. Ahora mismo sólo lo define @payment-emulator/api. El JSON de los escenarios lo compila automáticamente el pretest de la API.

Un solo fichero, o modo vigilancia:

npm test --workspace @payment-emulator/api -- test/money.spec.ts
npm run test:watch --workspace @payment-emulator/api

Las puertas de verificación más anchas:

npm run docs:check
npm run typecheck
npm run lint
npm run build
npm run smoke

No hay orden de cobertura ni umbral configurado. No afirmes un porcentaje de cobertura sólo porque el paquete esté instalado.

#Capas de prueba

#Base de datos para integración

Los ficheros de integración usan describe.skipIf(!hasDatabase). Sin DATABASE_URL, npm test corre igual las suites puras y estáticas y da las de base por saltadas. Para correrlo todo en local, expón una URL desechable:

$env:DATABASE_URL = 'postgresql://payment:payment@localhost:54329/payment_emulator_test'
npm test

Un driver se salta cuando lo que necesita no está configurado, con la misma regla que aplica hasDatabase: MONGO_URL para mongo, REDIS_URL para bullmq. El transporte postgres corre siempre que corra la base, que es justo su gracia.

El arnés de apps/api/test/integration/harness.ts construye el AppModule real, llama al mismo configureApp() que producción y aplica las migraciones antes de las pruebas. Los ficheros de integración se serializan desde vitest.config.ts porque comparten una base y si no competirían por inicializar los metadatos de migración.

Usa una base de pruebas, no una de desarrollo con datos que te importen. Las pruebas crean y quitan estado por endpoints y migraciones reales — aunque no todas limpian: varios specs dejan aplicaciones detrás, y las personas Harness ARS/Harness USD del propio arnés no se borran nunca. Apuntar la suite a una base cuya consola vas a mirar después te llenará sus listados.

#Suites de conformidad

apps/api/test/conformance.spec.ts recorre cada plugin registrado para las declaraciones estáticas. apps/api/test/integration/conformance.spec.ts corre las mismas garantías de comportamiento para Mercado Pago y Stripe:

• repetición con la misma clave de idempotencia y el mismo cuerpo;
• conflicto con la forma del proveedor cuando el cuerpo cambia;
• un solo recurso bajo peticiones idénticas concurrentes;
• una sola devolución bajo reintentos concurrentes;
• autorización separada de la captura;
• contabilidad cuadrada y comportamiento de devolución total y parcial;
• fallos deterministas de escenario y proyección del estado.

Añade un proveedor a esos casos parametrizados. Una prueba feliz a medida no sustituye a la conformidad.

#Pruebas con los SDK oficiales

Los SDK instalados son hoy stripe@22.6.0 y mercadopago@3.6.0 (según el lockfile).

• Stripe permite apuntar a otro host y puerto, así que stripe-sdk.spec.ts conduce el servidor Nest de pruebas con el SDK sin modificar. La telemetría se desactiva para conservar la garantía de que no se toca la red de ningún proveedor.
• El SDK de Mercado Pago no puede apuntar al emulador para las peticiones, pero su validador de webhooks, que no tiene estado, sí puede verificar nuestras firmas. Esa limitación está explícita en docs/en/fidelity/mercadopago.md.

#Escribir una prueba útil

1. Elige la capa más estrecha que pueda fallar por esa regla.
2. Reutiliza startEmulator(), operator(), anonymous() y fundingSource() para montar la integración.
3. Para reglas de concurrencia, solapa de verdad varias llamadas; dos peticiones pueden cruzarse por tiempos y hacer que un lock roto parezca bueno.
4. Afirma salida con forma de proveedor en las rutas de proveedor, y vocabulario del emulador en las de control y checkout.
5. Para autorización, incluye el rol equivocado y otro inquilino, no sólo la falta de token.
6. Para escrituras del libro mayor, afirma que el debe iguala al haber e inspecciona los saldos de las cuentas que importan económicamente.

#Integración continua

.github/workflows/ci.yml tiene dos trabajos:

• checks: instala desde el lockfile, y luego typecheck, lint, pruebas, build y la humareda pura contra PostgreSQL 17.
• stack: construye la pila de Compose, espera a los health checks, ejecuta scripts/stack-smoke.mjs, imprime los registros y borra sus volúmenes.

La humareda de pila cubre el acceso a la consola, el registro de una aplicación por Nitro, un pago anónimo en el checkout, el rechazo del pago con saldo sin sesión, la liquidación cuadrada del libro mayor y un flujo de Stripe con formulario, captura manual y devolución.

El smoke del stack también prueba OAuth, aprobación y captura de PayPal. Su éxito no demuestra la entrega de un webhook por el worker ni todos los transportes opcionales; esas rutas se comprueban con las pruebas de colas.