testing-kit

testing-kit — TDD + Unit + E2E + Quality Gate para Next.js

Parte 1: TDD — Test First, Code Second

3 Reglas de Hierro

1. TEST FIRST, CODE SECOND — sin excepciones
2. NUNCA codigo de produccion sin un test que falle primero
3. CADA route.ts tiene route.test.ts, CADA page.tsx tiene .spec.ts

Ciclo RED → GREEN → REFACTOR

RED: Escribir UN test que describe UN comportamiento → ejecutar → DEBE FALLAR GREEN: Escribir el codigo MINIMO para que pase → ejecutar → DEBE PASAR REFACTOR: Limpiar sin romper tests → ejecutar → SIGUE PASANDO

Repetir. Un test a la vez. SIEMPRE vertical (test → codigo → green), NUNCA horizontal (todos los tests → luego todo el codigo).

Test List (antes de escribir codigo)

Listar todos los comportamientos a testear. Ejemplo para POST /api/users:

1. 201 — crea usuario con datos validos
2. 401 — rechaza sin autenticacion
3. 400 — rechaza campos requeridos vacios
4. 400 — rechaza email invalido
5. 404 — recurso padre no existe
6. 500 — maneja error de base de datos

Cada item = un ciclo RED → GREEN.

---

Parte 2: Unit Tests con Vitest

Template de 6 Casos (minimo obligatorio)

import { describe, it, expect, vi, beforeEach } from 'vitest'

// Mocks ANTES de los imports del codigo
const mockGetUser = vi.fn()
const mockFrom = vi.fn()

vi.mock('@/lib/supabase/server', () => ({
  createClient: vi.fn(() => Promise.resolve({
    auth: { getUser: mockGetUser },
    from: mockFrom,
  })),
}))

// Import del codigo a testear
import { POST } from './route'

const MOCK_USER = { id: 'user-123', email: '[email protected]' }

function createRequest(body?: unknown): Request {
  return new Request('http://localhost/api/resource', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    ...(body ? { body: JSON.stringify(body) } : {}),
  })
}

beforeEach(() => { vi.clearAllMocks() })

describe('POST /api/resource', () => {
  // CASO 1: Happy path (200/201)
  it('returns 201 with created resource', async () => {
    mockGetUser.mockResolvedValue({ data: { user: MOCK_USER } })
    mockFrom.mockReturnValue({
      insert: vi.fn().mockReturnThis(),
      select: vi.fn().mockReturnThis(),
      single: vi.fn().mockResolvedValue({ data: { id: '1', name: 'Test' }, error: null }),
    })

    const res = await POST(createRequest({ name: 'Test' }))
    expect(res.status).toBe(201)
  })

  // CASO 2: Sin autenticacion (401)
  it('returns 401 when not authenticated', async () => {
    mockGetUser.mockResolvedValue({ data: { user: null } })
    const res = await POST(createRequest({ name: 'Test' }))
    expect(res.status).toBe(401)
  })

  // CASO 3: Input invalido (400)
  it('returns 400 on invalid input', async () => {
    mockGetUser.mockResolvedValue({ data: { user: MOCK_USER } })
    const res = await POST(createRequest({})) // body vacio
    expect(res.status).toBe(400)
  })

  // CASO 4: No encontrado (404)
  it('returns 404 when resource not found', async () => {
    mockGetUser.mockResolvedValue({ data: { user: MOCK_USER } })
    mockFrom.mockReturnValue({
      select: vi.fn().mockReturnThis(),
      eq: vi.fn().mockReturnThis(),
      single: vi.fn().mockResolvedValue({ data: null, error: null }),
    })

    const res = await POST(createRequest({ parentId: 'not-found' }))
    expect(res.status).toBe(404)
  })

  // CASO 5: Error de BD (500)
  it('returns 500 on database error', async () => {
    mockGetUser.mockResolvedValue({ data: { user: MOCK_USER } })
    mockFrom.mockReturnValue({
      insert: vi.fn().mockReturnThis(),
      select: vi.fn().mockReturnThis(),
      single: vi.fn().mockResolvedValue({ data: null, error: { message: 'DB error' } }),
    })

    const res = await POST(createRequest({ name: 'Test' }))
    expect(res.status).toBe(500)
    // Verificar que NO expone el error interno
    const body = await res.json()
    expect(body.error).not.toContain('DB error')
  })

  // CASO 6: Extra (especifico del endpoint — SIEMPRE implementar, nunca dejar vacio)
  it('returns 409 when duplicate name exists', async () => {
    mockGetUser.mockResolvedValue({ data: { user: MOCK_USER } })
    mockFrom.mockReturnValue({
      insert: vi.fn().mockReturnThis(),
      select: vi.fn().mockReturnThis(),
      single: vi.fn().mockResolvedValue({
        data: null,
        error: { message: 'unique_violation', code: '23505' },
      }),
    })

    const res = await POST(createRequest({ name: 'Duplicado' }))
    expect(res.status).toBe(409)
  })
})