# Sprint 4 — Etapa 8: Tests de integración + batería de entrega + polish

## Contexto

InQ ROI — React 18 + Vite + TypeScript + TanStack Router + Zustand + shadcn/ui + Tailwind.
Etapas 1–7B completadas. Sprint 4 introdujo auth (Google OAuth + Supabase), PostgreSQL, RLS, catálogo de recursos, y múltiples páginas nuevas.

**Problema crítico detectado:** todos los tests E2E existentes (15 specs en `tests/e2e/`) corren contra `localhost:4173` sin autenticación. Con Sprint 4, todas las rutas protegidas redirigen a `/login`. Es muy probable que la mayoría de los specs existentes estén fallando o saltando pasos silenciosamente.

Esta etapa tiene tres entregables:
1. **Auditoría y corrección** de los tests E2E existentes
2. **Nuevos tests E2E** para los flujos críticos de Sprint 4
3. **`docs/CHECKLIST_ENTREGA.md`** — protocolo exhaustivo que Claude Code ejecuta antes de entregar cualquier etapa, en cualquier sprint futuro

---

## Parte 1 — Auditoría de tests existentes

### 1a. Correr todos los specs actuales y reportar estado

```bash
npx playwright test --reporter=list 2>&1 | tail -50
```

Clasificar cada spec como:
- **VERDE** — pasa sin cambios
- **ROJO-AUTH** — falla porque la app redirige a `/login` antes de que el test llegue al contenido
- **ROJO-OTRO** — falla por otra razón

### 1b. Fix para specs ROJO-AUTH

Los specs que prueban flujos con datos (PDFs, simulaciones, BPMN) necesitan un mecanismo de bypass de auth para tests.

**Estrategia: mock de sesión vía localStorage en global setup**

Crear `tests/e2e/setup/auth-setup.ts`:

```typescript
import { chromium, FullConfig } from '@playwright/test'

async function globalSetup(config: FullConfig) {
  // Usar supabase-js directamente con service role para crear sesión de test
  // O: inyectar una sesión pre-generada en localStorage antes de que el test navegue
  
  // Opción A (recomendada si hay usuario email/password en Supabase):
  // const { data } = await supabase.auth.signInWithPassword({
  //   email: process.env.TEST_USER_EMAIL,
  //   password: process.env.TEST_USER_PASSWORD,
  // })
  // guardar storageState con la sesión
  
  // Opción B (mock mínimo para tests que no necesitan queries reales):
  // Inyectar localStorage key de sesión fake para bypasear el guard de AuthContext
}
```

**Prerequisito para Opción A:** crear un usuario de test en Supabase con email/password (NO Google OAuth) con `platform_role = 'platform_admin'`. Las credenciales van en `.env.test` (ignorado por git) y documentadas en `.env.example`:

```
TEST_USER_EMAIL=test@inquality.com.py
TEST_USER_PASSWORD=...
```

**Si Opción A no es viable ahora:** los specs que prueban PDF/screenshots pueden mockear el store de Zustand directamente (los PDFs no necesitan Supabase para generarse — solo necesitan datos en el store). Revisar si se puede inicializar el store con fixtures sin pasar por la DB.

Documentar la decisión tomada en un comentario al inicio del setup.

### 1c. Specs que prueban solo PDFs/screenshots (sin data de Supabase)

Los specs `etapa-4-pdfs.spec.ts` hasta `etapa-11-polish.spec.ts` y `export-pdf.spec.ts` probablemente cargan BPMNs locales y generan PDFs sin tocar Supabase. Para estos:

- Si el único problema es el redirect a `/login`, agregar el mock de sesión del setup
- Si necesitan datos en el store, cargarlos via fixture antes de navegar

No reescribir la lógica de los tests — solo agregar el mecanismo de auth bypass.

---

## Parte 2 — Nuevos tests E2E para Sprint 4

Crear `tests/e2e/sprint-4-smoke.spec.ts`:

### Tests sin auth (deben pasar sin sesión)

```typescript
test('login page renders — Google button visible', async ({ page }) => {
  await page.goto('/login')
  await expect(page.getByRole('button', { name: /iniciar sesión con google/i })).toBeVisible()
})

test('protected route redirects to login', async ({ page }) => {
  await page.goto('/')
  await expect(page).toHaveURL(/\/login/)
})

test('protected route /workspace redirects to login', async ({ page }) => {
  await page.goto('/workspace/fake-id')
  await expect(page).toHaveURL(/\/login/)
})

test('protected route /recursos redirects to login', async ({ page }) => {
  await page.goto('/recursos')
  await expect(page).toHaveURL(/\/login/)
})
```

### Tests con auth (requieren sesión de test)

Usar el fixture de sesión del global setup:

```typescript
test.use({ storageState: 'tests/e2e/setup/auth-state.json' })

test('library loads after auth — no 500 errors', async ({ page }) => {
  const errors: string[] = []
  page.on('response', r => { if (r.status() >= 500) errors.push(r.url()) })
  
  await page.goto('/')
  await page.waitForLoadState('networkidle')
  
  expect(errors).toHaveLength(0)
})

test('library — no 406 errors in simulations queries', async ({ page }) => {
  const errors406: string[] = []
  page.on('response', r => {
    if (r.status() === 406 && r.url().includes('simulations')) errors406.push(r.url())
  })
  
  await page.goto('/')
  await page.waitForLoadState('networkidle')
  
  expect(errors406).toHaveLength(0)
})

test('catalog page loads at /recursos', async ({ page }) => {
  await page.goto('/recursos')
  await expect(page.getByRole('heading', { name: /catálogo de recursos/i })).toBeVisible()
})

test('app header shows user avatar', async ({ page }) => {
  await page.goto('/')
  // El avatar tiene las iniciales del usuario o una imagen
  await expect(page.locator('[aria-label*="usuario"]').or(
    page.locator('img[alt*="avatar"]')
  )).toBeVisible()
})

test('import BPMN — navigates to workspace', async ({ page }) => {
  await page.goto('/import')
  // Hacer click en "Usar ejemplo" si existe, o subir simple-linear.bpmn
  // Verificar que navega al workspace
  await expect(page).toHaveURL(/\/workspace\//)
})
```

Agregar solo los tests que sean estables y no flaky. Si un flujo es difícil de automatizar (ej: el import con file upload real), documentarlo como "manual" en el checklist.

---

## Parte 3 — `docs/CHECKLIST_ENTREGA.md`

Crear este archivo. Es el protocolo que Claude Code ejecuta **antes de reportar cualquier etapa como completada**, en este sprint y en todos los futuros.

```markdown
# Checklist de entrega — InQ ROI

> Claude Code ejecuta este checklist ANTES de reportar una etapa como completada.
> El director ejecuta la sección "Validación visual" para el OK formal.

---

## Tier 1 — Automatizado (bloquea entrega si falla)

Correr en este orden. Si cualquier comando falla, no entregar — corregir primero.

\`\`\`bash
npm run build          # 0 errores TypeScript, bundle generado
npm run lint           # 0 errores ESLint
npm run test           # todos los tests Vitest verdes (reportar N/N)
npx playwright test    # todos los E2E verdes (reportar N/N)
\`\`\`

Reportar en el mensaje de entrega:
- Build: ✅ limpio / ❌ N errores
- Lint: ✅ limpio / ❌ N warnings/errors  
- Tests unitarios: ✅ N/N verdes
- Tests E2E: ✅ N/N verdes

---

## Tier 2 — Deploy check (post-deploy en inq-roi.inqualityhq.com)

Abrir DevTools → Network tab. Realizar estas acciones y verificar:

| Acción | Verificar |
|--------|-----------|
| Cargar biblioteca (`/`) | Sin 500, sin 406 en `simulations` |
| Abrir cualquier proceso en workspace | Sin 500, `activities` y `gateways` con 200 |
| Abrir catálogo de recursos (`/recursos`) | Sin 500, tabla carga con datos |
| Exportar PDF (cualquier proceso simulado) | Sin errores en consola, archivo descargado |

---

## Tier 3 — Validación visual (director)

> Esta sección la completa el director. Claude Code NO puede aprobarla.

### Siempre verificar
- [ ] Header muestra avatar del usuario logueado
- [ ] Ningún texto dice "Process Cost Platform" (nombre viejo)
- [ ] Marca "InQ" escrita correctamente (no INQ, no Inq)
- [ ] Botones primarios en naranja `#F59845`

### Por área (verificar si la etapa tocó esa área)

**Biblioteca**
- [ ] Procesos cargan sin spinner infinito
- [ ] "Actualizado por [nombre]" visible en tarjetas
- [ ] Toggle Todos/Míos funciona

**Workspace**
- [ ] BPMN canvas renderiza el diagrama
- [ ] ActivityPanel abre al hacer click en una actividad
- [ ] ResourcesPanel muestra recursos usados en el proceso

**Catálogo de recursos**
- [ ] Tabla muestra recursos con badges de tipo coloreados
- [ ] Búsqueda por nombre funciona
- [ ] Filtro por tipo funciona
- [ ] Crear/editar recurso guarda en Supabase y aparece en la lista
- [ ] VPS con costo `0.037` muestra `$0.037` (no `$0.04`)

**Auth**
- [ ] Login muestra selector de cuentas de Google
- [ ] Logout redirige a `/login`
- [ ] Sin sesión, cualquier ruta protegida redirige a `/login`

**PDF** (si la etapa tocó PDF)
- [ ] Footer dice "Powered by InQuality"
- [ ] Sin caracteres rotos ni encodings incorrectos

---

## Tier 4 — Integridad de datos (si la etapa tocó schema o repos)

Correr en Supabase Studio SQL Editor:

\`\`\`sql
-- Sin procesos huérfanos (sin owner)
SELECT COUNT(*) FROM processes WHERE owner_id IS NULL;  -- debe ser 0

-- Sin actividades huérfanas
SELECT COUNT(*) FROM activities a
LEFT JOIN processes p ON p.id = a.process_id
WHERE p.id IS NULL;  -- debe ser 0

-- Sin recursos con tipo inválido
SELECT DISTINCT type FROM resources;
-- debe mostrar solo: person, role, system, equipment, supply
\`\`\`

---

## Nota sobre regresiones de PDF

Los tests E2E de PDFs (`etapa-4-pdfs.spec.ts` etc.) son la red de contención para regresiones de PDF.
Si se tocó cualquier cosa de exportación o cálculos, correr específicamente:
\`\`\`bash
npx playwright test tests/e2e/export-pdf.spec.ts tests/e2e/export-roi.spec.ts
\`\`\`
```

---

## Parte 4 — Polish

Revisar y corregir cualquiera de estos si existe:

- En la biblioteca, si el `OwnershipBadge` todavía tiene texto "Solo vos" / "De otro consultor" en inglés o hardcodeado — corregir a español
- Verificar que el texto de "Compartir con equipo" en el menú ⋮ sigue siendo visible aunque sea no-op (con un tooltip o texto secundario que diga "Disponible próximamente" si el director lo prefiere — **consultar antes de implementar**)
- Revisar que `npm run lint` pasa sin warnings en los archivos nuevos de Sprint 4

---

## Qué NO entra en esta etapa

- Implementación real de `setShared` (diferida — ver OBSERVATIONS.md)
- Keycloak / migración de auth
- Features de producto nuevas
- Cambios en PDF o simulación

---

## Orden de ejecución

1. Correr todos los E2E existentes y clasificar estado (verde/rojo-auth/rojo-otro)
2. Implementar estrategia de auth bypass para tests (Opción A o B según viabilidad)
3. Corregir specs ROJO-AUTH con el nuevo setup
4. Crear `tests/e2e/sprint-4-smoke.spec.ts`
5. Crear `docs/CHECKLIST_ENTREGA.md`
6. Polish (lint warnings, textos)
7. `npm run test` — mantener 521+ tests Vitest verdes
8. `npx playwright test` — reportar estado completo (verde/rojo con razón)
9. Commit: `test(sprint-4/etapa-8): batería E2E Sprint 4 + CHECKLIST_ENTREGA + polish`

---

## Criterios de validación

- [ ] Todos los specs E2E clasificados como verde, rojo-auth, o rojo-otro
- [ ] Specs ROJO-AUTH corregidos con estrategia de auth bypass documentada
- [ ] `tests/e2e/sprint-4-smoke.spec.ts` creado con al menos los 4 tests sin-auth
- [ ] `docs/CHECKLIST_ENTREGA.md` creado con las 4 secciones (Tier 1–4)
- [ ] `npm run lint` sin warnings en archivos de Sprint 4
- [ ] 521+ tests Vitest verdes
- [ ] E2E: reportar N verdes / M rojos con razón para cada rojo
- [ ] **Validación visual del director** antes del OK formal
