FactuGES_ERP/docs/testing/frontend-node-test.md

# Tests frontend con `node:test`

El harness frontend vigente del ERP usa:

- `node:test` como runner
- `tsx` como transpiler
- renderizado en Node puro
- `react-dom/server` para tests React sin DOM real

No existe infraestructura activa de `vitest`, `jest`, `jsdom` ni `happy-dom` en el monorepo.

## Requisitos

Ejecuta los tests en Ubuntu desde la raíz del repo:

```bash
cd /home/david/dev/factuges-erp
node --version
pnpm --version
```

El runtime esperado del repo es Node `>= 24`.

## Comandos canónicos

### Test React individual

```bash
cd /home/david/dev/factuges-erp
pnpm test:frontend -- modules/customer-invoices/src/web/proformas/update/ui/components/proforma-update-help-popover.test.tsx
```

### Tests frontend de un módulo

```bash
cd /home/david/dev/factuges-erp
pnpm test:frontend -- modules/customer-invoices/src/web/**/*.test.tsx
```

### Tests frontend de `apps/web`

```bash
cd /home/david/dev/factuges-erp
pnpm test:frontend -- apps/web/src/**/*.test.tsx
```

### Test TypeScript puro

```bash
cd /home/david/dev/factuges-erp
pnpm test:unit -- packages/rdx-utils/src/helpers/__tests__/maybe.test.ts
```

## Mocking

Los tests frontend que necesitan mocks de módulos deben usar `mock.module()` de `node:test`.

Eso obliga a ejecutar el runner con:

```bash
node --experimental-test-module-mocks --import tsx --test
```

Por eso el script oficial es `pnpm test:frontend`.

## Qué no hacer

- No ejecutar tests React con `pnpm dlx tsx --test` si el test usa `mock.module()`.
- No asumir `jsdom` o `@testing-library/react` si el test actual solo necesita SSR.
- No importar barrels amplios si el test solo necesita un componente o helper local.

## Criterios prácticos

- Usa `pnpm test:unit` para tests `.ts` o `.tsx` que no dependan de `mock.module()`.
- Usa `pnpm test:frontend` cuando el test React necesite `mock.module()`.
- Si un componente necesita traducciones, mockea `../../../../i18n` o el helper local antes de arrancar el `manifest` del módulo.