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:

```txt
apps/server/src/testing/http
```

Script disponible:

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

## Entorno requerido

El runtime carga:

```txt
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:

```txt
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:

```txt
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:

```txt
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:

```txt
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