FactuGES_ERP/docs/testing/backend-http-integration.md

Tests HTTP backend

Esta guía pone en marcha un entorno real de integración HTTP para el backend del ERP usando:

• Express real
• módulos reales
• middleware real de auth y tenant
• MariaDB real
• Sequelize real

Estado actual

La suite vive en:

apps/server/src/testing/http

Script disponible:

cd /home/david/dev/factuges-erp
pnpm --filter @erp/factuges-server test:http

Entorno requerido

El runtime carga:

apps/server/.env.test

Contrato mínimo:

• NODE_ENV=test
• DB_NAME debe contener test
• la base se recrea en cada arranque de runtime
• el usuario configurado debe poder hacer CREATE DATABASE y DROP DATABASE

Para evitar colisiones entre suites o casos concurrentes:

• el runtime genera un nombre de base efímero a partir de DB_NAME
• cada test trabaja sobre una base distinta

Runtime reutilizable

Pieza principal:

apps/server/src/testing/http/http-test-runtime.ts

Responsabilidades:

• cargar .env.test
• resetear registries globales del server
• validar configuración segura de test
• recrear la base de datos
• arrancar la app real en un puerto efímero
• exponer request() y stop()

Fixtures actuales

Helpers disponibles:

apps/server/src/testing/http/http-test-fixtures.ts

Cobertura inicial:

• cuentas de identity
• companies
• memberships account-company
• payment terms
• login real por API
• consulta directa a la fila persistida de companies

Suite piloto actual

Archivo:

apps/server/src/testing/http/companies-current.http.test.ts

Cobertura inicial confirmada:

• GET /api/v1/companies/current
• PATCH /api/v1/companies/current
• 401 sin auth
• 403 sin X-Company-Id
• 403 con membership inactiva
• update parcial
• limpieza explícita con null
• asignación y desasignación de default_payment_term_id
• default_payment_term_id cross-company => 422
• default_payment_term_id inactivo => 422
• rollback transaccional cuando falla la asignación de default_payment_term_id
• 422 por payload inválido

Convenciones prácticas

• usar login real en vez de fabricar JWTs
• sembrar solo los datos mínimos del caso
• cerrar siempre el runtime con stop()
• no compartir base de datos entre tests
• validar tanto respuesta HTTP como persistencia cuando la mutación lo requiera

Contrato de default_payment_term_id

Semántica actual:

omitido -> conservar
null -> desvincular
UUID activo de la misma company -> asignar
UUID no asignable -> 422

Se considera no asignable:

• un PaymentTerm de otra company
• un PaymentTerm inactivo

Además, el PATCH /companies/current es transaccional:

• si falla default_payment_term_id
• no se persisten otros cambios del mismo request