arckode-framework 1.3.2 → 1.4.1

package/skills/testing/SKILL.md

@@ -1,280 +1,48 @@
-# SKILL: Arckode Testing — Patrones, Utilidades y Estructura
+# Testing — Bun Test + Patterns
 
-> Activar cuando: escribir tests, configurar test suite, debuggear tests fallidos, agregar cobertura.
+## Stack
 
----
+`bun test` con `describe`/`it`/`expect` global.
 
-## 1. SETUP DEL TEST (sin BD real)
+## Ejecución
 
-```ts
-import { describe, test, expect, beforeEach, mock } from 'bun:test'
-// NOMBRES REALES: silentLogger (factory), createRecordingDb, createTestClient
-// createRecordingOrm / createSilentLogger / createNullCache NO existen — nunca usar esos nombres
-import { silentLogger, createRecordingDb } from 'arckode-framework/testing'
-import type { RepositoryAdapter, CacheAdapter } from 'arckode-framework'
-import { ProductosService } from '../service'
-import type { ProductoDTO } from '../types'
-
-// silentLogger es factory function — SIEMPRE llamar con ()
-const log = silentLogger()
-const silentCache: CacheAdapter = { get: async () => null, set: async () => {}, delete: async () => {}, flush: async () => {} }
-
-function makeRepo(overrides: Partial<RepositoryAdapter<ProductoDTO>> = {}): RepositoryAdapter<ProductoDTO> {
-  return {
-    findMany: async () => [],
-    findById: async () => null,
-    findOne: async () => null,
-    create: async (data) => ({ id: 'test-id', ...data } as ProductoDTO),
-    update: async (id, data) => ({ id, ...data } as ProductoDTO),
-    delete: async () => true,
-    count: async () => 0,
-    paginate: async () => ({ data: [], total: 0, limit: 20, offset: 0, pages: 0 }),
-    ...overrides,
-  }
-}
-
-describe('ProductosService', () => {
-  let service: ProductosService
-
-  beforeEach(() => {
-    service = new ProductosService(makeRepo(), log, silentCache)
-  })
-})
-```
-
-**Regla de oro:** Testear el service, no el ORM. El ORM ya tiene sus propios tests.
-
----
-
-## 2. UTILIDADES DE TESTING
-
-```ts
-// Exports REALES del módulo arckode-framework/testing:
-import {
-  silentLogger,              // factory: silentLogger() → Logger (NO usarla sin ())
-  createRecordingDb,         // captura SQL sin ejecutar BD real → db.calls, db.lastSql()
-  createTestClient,          // cliente HTTP sin levantar servidor
-  createIntegrationClient,   // cliente HTTP con servidor real (puerto aleatorio)
-  mockAuth,                  // middleware mock para simular autenticación
-} from 'arckode-framework/testing'
-
-// ❌ ESTOS NO EXISTEN — nunca usar:
-// createRecordingOrm, createSilentLogger, createNullCache
-
-// silentLogger — factory, siempre con ()
-const log = silentLogger()
-
-// createRecordingDb — captura SQL sin ejecutar nada
-const db = createRecordingDb({ queryData: [{ id: '1', nombre: 'Laptop' }] })
-// db.calls      → array de { sql, params, type }
-// db.lastSql()  → último SQL ejecutado
-// db.reset()    → limpia el historial
-
-// TestClient — router real, sin HTTP
-const client = createTestClient(router)
-const res = await client.get('/productos')
-expect(res.status).toBe(200)
-```
-
----
-
-## 3. ESTRUCTURA MÍNIMA OBLIGATORIA
-
-Cada módulo necesita al menos 2 casos:
-
-```ts
-describe('ProductosService', () => {
-
-  // CASO 1: Happy path
-  test('listar retorna array (vacío si no hay datos)', async () => {
-    const result = await service.listar()
-    expect(Array.isArray(result)).toBe(true)
-  })
-
-  // CASO 2: Error esperado (validación, not found, conflict, etc.)
-  test('crear lanza error si el nombre está vacío', async () => {
-    await expect(service.crear({ nombre: '', precio: 100 }))
-      .rejects.toThrow()
-  })
-
-  // CASO 3 (recomendado): IDOR / autorización
-  test('getById lanza NotFoundError si no existe', async () => {
-    await expect(service.getById('id-inexistente', { id: 'u1', role: 'user' }))
-      .rejects.toThrow('no encontrado')
-  })
-})
-```
-
-**`arckode analyze` detecta:** `TESTS_WITHOUT_CASES` — archivo test sin ningún `test()`.
-
----
-
-## 4. MOCKEAR DEPENDENCIAS EXTERNAS
-
-```ts
-import { mock } from 'bun:test'
-
-// Mockear el mail service en tests que lo usan
-const mockMail = {
-  send: mock(() => Promise.resolve()),
-}
-
-const service = new AuthService(repo, auth, mockMail as any)
-
-test('registro envía email de bienvenida', async () => {
-  await service.registrar({ email: 'test@test.com', password: '12345678' })
-  expect(mockMail.send).toHaveBeenCalledTimes(1)
-  expect(mockMail.send).toHaveBeenCalledWith(
-    expect.objectContaining({ to: 'test@test.com' })
-  )
-})
-```
+| Comando | Scope |
+|---------|-------|
+| `bun test` | All |
+| `bun test tests/modules/users.test.ts` | Archivo |
+| `bun test --filter="users"` | Match |
+| `bun run typecheck` | tsc --noEmit |
 
----
+## Reglas
 
-## 5. INTEGRATION TESTS (router + controller)
+1. Test por módulo: `tests/modules/{modulo}.test.ts`
+2. Service test: mock RepositoryAdapter, NUNCA ORM real
+3. Controller test: mock Service, solo valida HTTP contract
+4. Integration test: DB real con `beforeAll` setup + `afterAll` cleanup
+5. NO testear helpers ni config (salvo lógica crítica)
+6. Nombre: `UserService.create → crea usuario con datos válidos`
 
-```ts
-import { Router } from 'arckode-framework'
-import { createTestClient } from 'arckode-framework/testing'
-
-describe('Productos API', () => {
-  let client: ReturnType<typeof createTestClient>
-
-  beforeEach(() => {
-    const router = new Router()
-    // montar el módulo de prueba
-    const service = new ProductosService(makeRepo(), log, silentCache)
-    const controller = new ProductosController(service)
-
-    router.get('/productos',     req => controller.index(req))
-    router.post('/productos',    req => controller.store(req))
-    router.delete('/productos/:id', req => controller.destroy(req))
-
-    client = createTestClient(router)
-  })
-
-  test('GET /productos → 200', async () => {
-    const res = await client.get('/productos')
-    expect(res.status).toBe(200)
-    expect(Array.isArray(res.body)).toBe(true)
-  })
-
-  test('POST /productos sin nombre → 400', async () => {
-    const res = await client.post('/productos', { body: { precio: 100 } })
-    expect(res.status).toBe(400)
-    expect(res.body).toHaveProperty('errors')
-  })
-
-  test('POST /productos con datos válidos → 201', async () => {
-    const res = await client.post('/productos', {
-      body: { nombre: 'Zapato', precio: 999 }
-    })
-    expect(res.status).toBe(201)
-    expect(res.body).toHaveProperty('id')
-  })
-})
-```
-
----
-
-## 6. TESTEAR AUTH (con middleware)
-
-```ts
-import { Auth } from 'arckode-framework'
-import { jwtTokenAdapter } from 'arckode-framework/adapters/jwt'
-
-const auth = new Auth(jwtTokenAdapter, 'test-secret-12345678901234567890', silentLogger())
-const token = auth.createToken({ id: 'user-1', role: 'user' })
-const adminToken = auth.createToken({ id: 'admin-1', role: 'admin' })
-
-test('GET /pedidos sin token → 401', async () => {
-  const res = await client.get('/pedidos')
-  expect(res.status).toBe(401)
-})
-
-test('GET /pedidos con token → 200', async () => {
-  const res = await client.get('/pedidos', {
-    headers: { Authorization: `Bearer ${token}` }
-  })
-  expect(res.status).toBe(200)
-})
-
-test('DELETE /admin/algo sin admin → 403', async () => {
-  const res = await client.delete('/admin/algo', {
-    headers: { Authorization: `Bearer ${token}` }  // user, no admin
-  })
-  expect(res.status).toBe(403)
-})
-```
-
----
-
-## 7. CORRER TESTS
-
-```bash
-# Todos los tests
-bun test
-
-# Tests de un módulo específico
-bun test modules/productos
-
-# Un archivo específico
-bun test modules/productos/tests/service.test.ts
-
-# Con watch (re-corre al cambiar archivos)
-bun test --watch
-
-# Con cobertura
-bun test --coverage
-```
-
----
-
-## 8. QUÉ NO TESTEAR
-
-- **Los adapters del framework** (SqliteAdapter, jwtTokenAdapter): ya tienen tests propios
-- **El ORM** directamente: testealo via RepositoryAdapter en tu service
-- **El router**: testear el controller con `createTestClient`, no el router directamente
-- **Casos imposibles**: no testear `if` que nunca puede ser `false` con TypeScript strict
-
----
-
-## 9. ERRORES COMUNES EN TESTS
+## Patrón
 
 ```ts
-// ❌ Olvidar el await — el test pasa siempre (false positive)
-test('lanza error', () => {
-  expect(service.crear({})).rejects.toThrow()  // sin await → siempre pasa
-})
-
-// ✅ Siempre await en expects async
-test('lanza error', async () => {
-  await expect(service.crear({})).rejects.toThrow()
-})
+// Arrange
+const mockRepo = new MockRepositoryAdapter<UserDTO>() // implementa RepositoryAdapter<T>
+mockRepo.setData(mockUsers)
+const service = new UsersService(mockRepo)
 
-// ❌ Describir implementación en lugar de comportamiento
-test('llama a repo.create con los datos correctos', ...)
+// Act
+const result = await service.findById('1')
 
-// ✅ Describir el comportamiento observable
-test('crear retorna el producto con id asignado', ...)
-
-// ❌ Test que testea el ORM en lugar del service
-test('ORM recibe query INSERT', async () => {
-  const orm = createRecordingOrm()
-  await service.crear(...)
-  expect(orm.getRecordedQueries()[0]).toContain('INSERT')  // testear el framework, no tu código
-})
+// Assert
+expect(result).toEqual(mockUsers[0])
 ```
 
----
-
-## 10. CHECKLIST TESTING
+## Errores silenciosos
 
-- [ ] Mínimo 2 test cases: happy path + error esperado
-- [ ] `silentLogger()` — con paréntesis, es factory function (no objeto)
-- [ ] Cache mock inline (`get: async () => null`, etc.) — no hay createNullCache
-- [ ] `RepositoryAdapter<T>` mock inline con `makeRepo()` — no hay createRecordingOrm
-- [ ] Todo `expect(...).rejects` tiene `await`
-- [ ] Los nombres de test describen comportamiento, no implementación
-- [ ] `bun test` pasa sin errores antes del commit
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Service test con ORM real | DB connection en test | Mock RepositoryAdapter |
+| Test sin cleanup | Datos entre tests | `afterEach` reset |
+| Mock sin tipo | `as any` en todo | Usar `MockRepositoryAdapter<T>` |
+| Cobertura baja | <70% branch | `bun run analyze` |
+| `bun test` no encuentra tests | Archivos sin `.test.ts` | Renombrar |