sinapse-ai 5.0.8 → 6.0.1

package/docs/es/guides/testing-guide.md

@@ -1,1215 +0,0 @@
-# Guia de Testing de SINAPSE
-
-> [EN](../../guides/testing-guide.md) | [PT](../../pt/guides/testing-guide.md) | **ES**
-
----
-
-> Guia completa de la estrategia de testing, herramientas y mejores practicas para SINAPSE.
-
-**Version:** 2.1.0
-**Ultima Actualizacion:** 2026-01-29
-
----
-
-## Tabla de Contenidos
-
-1. [Vision General](#vision-general)
-2. [Estrategia de Testing](#estrategia-de-testing)
-3. [Tests Unitarios](#tests-unitarios)
-4. [Tests de Integracion](#tests-de-integracion)
-5. [Tests End-to-End](#tests-end-to-end)
-6. [Tests de Agentes](#tests-de-agentes)
-7. [Testing Cross-Platform](#testing-cross-platform)
-8. [Cobertura y Metricas](#cobertura-y-metricas)
-9. [Integracion CI/CD](#integracion-cicd)
-10. [Escribiendo Buenos Tests](#escribiendo-buenos-tests)
-11. [Mocking y Fixtures](#mocking-y-fixtures)
-12. [Referencia de Comandos NPM](#referencia-de-comandos-npm)
-13. [Solucion de Problemas](#solucion-de-problemas)
-
----
-
-## Vision General
-
-SINAPSE sigue una estrategia de testing integral que asegura la calidad del codigo en todas las capas del framework. Nuestra filosofia de testing esta construida sobre:
-
-- **Desarrollo Guiado por Tests (TDD)** para funcionalidad core
-- **Testing por Capas** con tests unitarios, de integracion y E2E
-- **Verificacion Cross-Platform** para Windows, macOS y Linux
-- **Testing Especifico de Agentes** para comportamientos de agentes IA
-- **Quality Gates Automatizados** integrados con CI/CD
-
-### Piramide de Testing
-
-```
-                    ┌─────────────┐
-                    │     E2E     │  ← Pocos, Lentos, Costosos
-                    │   Tests     │
-                    ├─────────────┤
-                    │ Integracion │  ← Algunos, Velocidad Media
-                    │   Tests     │
-                    ├─────────────┤
-                    │  Unitarios  │  ← Muchos, Rapidos, Economicos
-                    │   Tests     │
-                    └─────────────┘
-```
-
-| Capa        | Cantidad | Velocidad | Objetivo de Cobertura |
-| ----------- | -------- | --------- | --------------------- |
-| Unitarios   | 100+     | < 30s     | 80%+ lineas           |
-| Integracion | 30-50    | 1-5m      | Rutas criticas        |
-| E2E         | 10-20    | 5-15m     | Flujos de usuario     |
-
----
-
-## Estrategia de Testing
-
-### Estructura de Directorios
-
-```
-tests/
-├── unit/                    # Tests unitarios
-│   ├── quality-gates/       # Componentes de quality gate
-│   ├── squad/               # Tests del sistema de squads
-│   ├── mcp/                 # Tests de configuracion MCP
-│   ├── manifest/            # Tests de manejo de manifests
-│   └── documentation-integrity/  # Tests del generador de docs
-├── integration/             # Tests de integracion
-│   ├── squad/               # Integracion del squad designer
-│   ├── windows/             # Tests especificos de Windows
-│   └── *.test.js            # Tests de integracion generales
-├── e2e/                     # Tests end-to-end
-│   └── story-creation-clickup.test.js
-├── performance/             # Benchmarks de rendimiento
-│   ├── decision-logging-benchmark.test.js
-│   └── tools-system-benchmark.test.js
-├── security/                # Tests de seguridad
-│   └── core-security.test.js
-├── health-check/            # Tests del sistema de health check
-│   ├── engine.test.js
-│   └── healers.test.js
-├── regression/              # Tests de regresion
-│   └── tools-migration.test.js
-├── setup.js                 # Setup global de tests
-└── fixtures/                # Fixtures y mocks de tests
-```
-
-### Convencion de Nombres de Tests
-
-| Tipo        | Patron                        | Ejemplo                              |
-| ----------- | ----------------------------- | ------------------------------------ |
-| Unitario    | `*.test.js` o `*.spec.js`     | `greeting-builder.test.js`           |
-| Integracion | `*.test.js` en `integration/` | `contextual-greeting.test.js`        |
-| E2E         | `*.test.js` en `e2e/`         | `story-creation-clickup.test.js`     |
-| Benchmark   | `*-benchmark.test.js`         | `decision-logging-benchmark.test.js` |
-
----
-
-## Tests Unitarios
-
-Los tests unitarios verifican funciones y clases individuales de forma aislada.
-
-### Configuracion (jest.config.js)
-
-```javascript
-module.exports = {
-  testEnvironment: 'node',
-  coverageDirectory: 'coverage',
-
-  testMatch: [
-    '**/tests/**/*.test.js',
-    '**/tests/**/*.spec.js',
-    '**/.sinapse-ai/**/__tests__/**/*.test.js',
-  ],
-
-  testTimeout: 30000,
-  verbose: true,
-
-  setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],
-
-  coverageThreshold: {
-    global: {
-      branches: 25,
-      functions: 30,
-      lines: 30,
-      statements: 30,
-    },
-    '.sinapse-ai/core/': {
-      lines: 45,
-    },
-  },
-};
-```
-
-### Escribiendo Tests Unitarios
-
-```javascript
-/**
- * Tests Unitarios del Quality Gate Manager
- *
- * @story 2.10 - Quality Gate Manager
- */
-
-const {
-  QualityGateManager,
-} = require('../../../.sinapse-ai/core/quality-gates/quality-gate-manager');
-
-describe('QualityGateManager', () => {
-  let manager;
-
-  beforeEach(() => {
-    manager = new QualityGateManager({
-      layer1: { enabled: true },
-      layer2: { enabled: true },
-      layer3: { enabled: true },
-    });
-  });
-
-  describe('constructor', () => {
-    it('deberia crear manager con config por defecto', () => {
-      const defaultManager = new QualityGateManager();
-      expect(defaultManager).toBeDefined();
-      expect(defaultManager.layers).toBeDefined();
-    });
-
-    it('deberia crear manager con config personalizada', () => {
-      const customManager = new QualityGateManager({
-        layer1: { enabled: false },
-      });
-      expect(customManager.layers.layer1.enabled).toBe(false);
-    });
-  });
-
-  describe('runLayer', () => {
-    it('deberia lanzar error para numero de capa invalido', async () => {
-      await expect(manager.runLayer(4)).rejects.toThrow('Invalid layer number: 4');
-    });
-  });
-
-  describe('formatDuration', () => {
-    it('deberia formatear milisegundos', () => {
-      expect(manager.formatDuration(500)).toBe('500ms');
-    });
-
-    it('deberia formatear segundos', () => {
-      expect(manager.formatDuration(5000)).toBe('5.0s');
-    });
-
-    it('deberia formatear minutos', () => {
-      expect(manager.formatDuration(120000)).toBe('2.0m');
-    });
-  });
-});
-```
-
-### Mejores Practicas de Organizacion de Tests
-
-```javascript
-describe('ComponentName', () => {
-  // Setup y teardown
-  beforeAll(() => {
-    /* Setup global */
-  });
-  afterAll(() => {
-    /* Limpieza global */
-  });
-  beforeEach(() => {
-    /* Setup por test */
-  });
-  afterEach(() => {
-    /* Limpieza por test */
-  });
-
-  // Agrupar por metodo/funcionalidad
-  describe('methodName', () => {
-    it('deberia manejar entrada valida', () => {});
-    it('deberia lanzar error con entrada invalida', () => {});
-    it('deberia manejar casos limite', () => {});
-  });
-
-  describe('otro metodo', () => {
-    // Mas tests...
-  });
-});
-```
-
----
-
-## Tests de Integracion
-
-Los tests de integracion verifican que multiples componentes funcionen correctamente juntos.
-
-### Setup para Tests de Integracion
-
-```javascript
-// tests/setup.js
-process.env.NODE_ENV = 'test';
-process.env.SINAPSE_DEBUG = 'false';
-
-// Omitir tests de integracion por defecto
-if (process.env.SKIP_INTEGRATION_TESTS === undefined) {
-  process.env.SKIP_INTEGRATION_TESTS = 'true';
-}
-
-// Timeout global de tests (aumentado para CI)
-jest.setTimeout(process.env.CI ? 30000 : 10000);
-
-// Helper para omitir condicionalmente tests de integracion
-global.describeIntegration =
-  process.env.SKIP_INTEGRATION_TESTS === 'true' ? describe.skip : describe;
-
-global.testIntegration = process.env.SKIP_INTEGRATION_TESTS === 'true' ? test.skip : test;
-```
-
-### Escribiendo Tests de Integracion
-
-```javascript
-/**
- * Tests de Integracion para Sistema de Saludo Contextual
- *
- * Testing end-to-end de:
- * - Los 3 tipos de sesion
- * - Git configurado vs no configurado
- * - Filtrado de visibilidad de comandos
- * - Escenarios de fallback
- */
-
-const GreetingBuilder = require('../../.sinapse-ai/development/scripts/greeting-builder');
-
-describe('Tests de Integracion de Saludo Contextual', () => {
-  let builder;
-
-  beforeEach(() => {
-    builder = new GreetingBuilder();
-  });
-
-  describeIntegration('Generacion de Saludo End-to-End', () => {
-    test('deberia generar saludo completo de sesion nueva', async () => {
-      const greeting = await builder.build({
-        sessionType: 'new',
-        agent: 'dev',
-        gitConfigured: true,
-      });
-
-      expect(greeting).toContain('Welcome');
-      expect(greeting).toContain('Quick Commands');
-    });
-
-    test('deberia manejar git no configurado graciosamente', async () => {
-      const greeting = await builder.build({
-        sessionType: 'new',
-        agent: 'dev',
-        gitConfigured: false,
-      });
-
-      expect(greeting).not.toContain('git commit');
-    });
-  });
-});
-```
-
-### Ejecutando Tests de Integracion
-
-```bash
-# Ejecutar todos los tests incluyendo integracion
-SKIP_INTEGRATION_TESTS=false npm test
-
-# Ejecutar solo tests de integracion
-npm test -- --testPathPattern=integration
-
-# Ejecutar test de integracion especifico
-npm test -- tests/integration/contextual-greeting.test.js
-```
-
----
-
-## Tests End-to-End
-
-Los tests E2E verifican flujos de usuario completos de principio a fin.
-
-### Estructura de Tests E2E
-
-```javascript
-/**
- * Test E2E: Creacion de Story con ClickUp
- *
- * Prueba el flujo completo:
- * 1. Usuario inicia creacion de story
- * 2. Story se genera desde template
- * 3. Story se sincroniza a ClickUp
- * 4. Archivo local se actualiza con ID de ClickUp
- */
-
-describe('E2E Creacion de Story', () => {
-  const TEST_PROJECT = 'test-project';
-
-  beforeAll(async () => {
-    // Configurar entorno de test
-    await setupTestProject(TEST_PROJECT);
-  });
-
-  afterAll(async () => {
-    // Limpiar artefactos de test
-    await cleanupTestProject(TEST_PROJECT);
-  });
-
-  test('deberia crear story y sincronizar a ClickUp', async () => {
-    // Paso 1: Crear story
-    const story = await createStory({
-      title: 'Test Story',
-      type: 'feature',
-    });
-
-    expect(story.id).toBeDefined();
-    expect(story.file).toMatch(/\.md$/);
-
-    // Paso 2: Verificar sincronizacion con ClickUp
-    const clickupTask = await getClickUpTask(story.clickupId);
-    expect(clickupTask.name).toBe('Test Story');
-
-    // Paso 3: Verificar actualizacion de archivo local
-    const localContent = await readFile(story.file);
-    expect(localContent).toContain(story.clickupId);
-  }, 60000); // Timeout extendido para E2E
-});
-```
-
-### Mejores Practicas de Tests E2E
-
-| Practica                  | Descripcion                                      |
-| ------------------------- | ------------------------------------------------ |
-| **Entorno Aislado**       | Cada test E2E debe tener sus propios datos       |
-| **Limpieza Explicita**    | Siempre limpiar recursos creados                 |
-| **Timeouts Extendidos**   | Tests E2E necesitan timeouts mas largos (30-60s) |
-| **Servicios Reales**      | Usar servicios reales, no mocks                  |
-| **Idempotente**           | Los tests deben ser repetibles                   |
-
----
-
-## Tests de Agentes
-
-Probar agentes IA requiere consideraciones especiales para comportamiento de persona y ejecucion de comandos.
-
-### Categorias de Tests de Agentes
-
-| Categoria         | Prueba               | Proposito                              |
-| ----------------- | -------------------- | -------------------------------------- |
-| **Persona**       | Estilo de respuesta  | Verificar que agente mantiene caracter |
-| **Comandos**      | Ejecucion de tareas  | Verificar que comandos funcionan       |
-| **Fallback**      | Manejo de errores    | Verificar degradacion gracil           |
-| **Compatibilidad**| Soporte legacy       | Verificar que agentes viejos funcionan |
-
-### Tests de Compatibilidad Retroactiva de Agentes
-
-```javascript
-/**
- * Tests de Compatibilidad Retroactiva de Agentes
- *
- * Asegura que agentes de versiones anteriores de SINAPSE continuen funcionando.
- */
-
-const { loadAgent } = require('../../.sinapse-ai/core/registry/agent-loader');
-
-describe('Compatibilidad Retroactiva de Agentes', () => {
-  describe('Formato de Agente Legacy (v1.x)', () => {
-    test('deberia cargar agente sin metadata de visibilidad', async () => {
-      const agent = await loadAgent('legacy-agent-v1');
-
-      expect(agent).toBeDefined();
-      expect(agent.name).toBeDefined();
-      expect(agent.commands).toBeDefined();
-    });
-
-    test('deberia aplicar visibilidad por defecto cuando falta', async () => {
-      const agent = await loadAgent('legacy-agent-v1');
-
-      // Visibilidad por defecto deberia aplicarse
-      agent.commands.forEach((cmd) => {
-        expect(cmd.visibility).toBeDefined();
-      });
-    });
-  });
-
-  describe('Formato de Agente Actual (v2.x)', () => {
-    test('deberia cargar agente con metadata completa', async () => {
-      const agent = await loadAgent('dev');
-
-      expect(agent.slashPrefix).toBeDefined();
-      expect(agent.icon).toBeDefined();
-      expect(agent.persona).toBeDefined();
-    });
-  });
-});
-```
-
-### Probando Comandos de Agentes
-
-```javascript
-describe('Comandos de Agentes', () => {
-  let agent;
-
-  beforeAll(async () => {
-    agent = await activateAgent('dev');
-  });
-
-  test('*help deberia mostrar comandos disponibles', async () => {
-    const result = await agent.executeCommand('*help');
-
-    expect(result.output).toContain('Available Commands');
-    expect(result.exitCode).toBe(0);
-  });
-
-  test('*create-story deberia validar campos requeridos', async () => {
-    await expect(agent.executeCommand('*create-story')).rejects.toThrow(
-      'Missing required field: title'
-    );
-  });
-});
-```
-
----
-
-## Testing Cross-Platform
-
-SINAPSE soporta Windows, macOS y Linux. El testing cross-platform asegura comportamiento consistente.
-
-### Archivos de Test Especificos por Plataforma
-
-```
-tests/
-├── integration/
-│   ├── windows/
-│   │   └── shell-compat.test.js    # Tests de shell Windows
-│   ├── macos/
-│   │   └── permission.test.js      # Tests de permisos macOS
-│   └── linux/
-│       └── symlink.test.js         # Tests de symlinks Linux
-```
-
-### Utilidades de Test Cross-Platform
-
-```javascript
-/**
- * Utilidades de test cross-platform
- */
-
-const os = require('os');
-const path = require('path');
-
-const isWindows = process.platform === 'win32';
-const isMacOS = process.platform === 'darwin';
-const isLinux = process.platform === 'linux';
-
-// Describe especifico por plataforma
-const describeWindows = isWindows ? describe : describe.skip;
-const describeMacOS = isMacOS ? describe : describe.skip;
-const describeLinux = isLinux ? describe : describe.skip;
-
-// Normalizar separadores de path para assertions
-function normalizePath(p) {
-  return p.replace(/\\/g, '/');
-}
-
-// Obtener directorio temporal apropiado para la plataforma
-function getTempDir() {
-  return path.join(os.tmpdir(), 'sinapse-tests');
-}
-
-module.exports = {
-  isWindows,
-  isMacOS,
-  isLinux,
-  describeWindows,
-  describeMacOS,
-  describeLinux,
-  normalizePath,
-  getTempDir,
-};
-```
-
-### Tests Especificos de Windows
-
-```javascript
-/**
- * Tests de Compatibilidad de Shell de Windows
- */
-
-const { describeWindows } = require('../utils/platform');
-
-describeWindows('Compatibilidad de Shell de Windows', () => {
-  test('deberia manejar separadores de path de Windows', () => {
-    const path = 'C:\\Users\\test\\project';
-    const normalized = normalizePath(path);
-
-    expect(normalized).toBe('C:/Users/test/project');
-  });
-
-  test('deberia ejecutar comandos PowerShell', async () => {
-    const result = await executeShell('Get-Location', { shell: 'powershell' });
-
-    expect(result.exitCode).toBe(0);
-  });
-
-  test('deberia manejar fallback a cmd.exe', async () => {
-    const result = await executeShell('dir', { shell: 'cmd' });
-
-    expect(result.exitCode).toBe(0);
-  });
-});
-```
-
-### Configuracion de Matriz CI
-
-```yaml
-# .github/workflows/test.yml
-name: Tests Cross-Platform
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        node-version: [18, 20, 22]
-
-    runs-on: ${{ matrix.os }}
-
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - run: npm ci
-      - run: npm test
-
-      - name: Ejecutar Tests Especificos de Plataforma
-        run: npm run test:platform
-```
-
----
-
-## Cobertura y Metricas
-
-### Configuracion de Cobertura
-
-```javascript
-// jest.config.js - Seccion de cobertura
-module.exports = {
-  collectCoverageFrom: [
-    'src/**/*.js',
-    '.sinapse-ai/**/*.js',
-    'bin/**/*.js',
-    'packages/**/*.js',
-    'scripts/**/*.js',
-    '!**/node_modules/**',
-    '!**/tests/**',
-    '!**/coverage/**',
-    '!**/__tests__/**',
-    '!**/*.test.js',
-    '!**/*.spec.js',
-    // Excluir templates y archivos generados
-    '!.sinapse-ai/development/templates/**',
-    '!.sinapse-ai/product/templates/**',
-    '!**/dist/**',
-    // Excluir modulos con I/O intensivo (mejor para tests de integracion)
-    '!.sinapse-ai/core/health-check/checks/**',
-    '!.sinapse-ai/core/config/**',
-    '!.sinapse-ai/core/manifest/**',
-    '!.sinapse-ai/core/registry/**',
-    '!.sinapse-ai/core/utils/**',
-  ],
-
-  coverageThreshold: {
-    global: {
-      branches: 25,
-      functions: 30,
-      lines: 30,
-      statements: 30,
-    },
-    '.sinapse-ai/core/': {
-      lines: 45,
-    },
-  },
-
-  coveragePathIgnorePatterns: ['/node_modules/', '/coverage/', '/.husky/', '/dist/'],
-};
-```
-
-### Objetivos de Cobertura
-
-| Modulo            | Objetivo | Actual | Notas               |
-| ----------------- | -------- | ------ | ------------------- |
-| **Global**        | 30%      | ~31%   | Linea base minima   |
-| **Core**          | 45%      | ~47%   | Logica de negocio   |
-| **Quality Gates** | 80%      | TBD    | Ruta critica        |
-| **Sistema Squad** | 70%      | TBD    | Cara al usuario     |
-
-### Viendo Reportes de Cobertura
-
-```bash
-# Generar reporte de cobertura
-npm run test:coverage
-
-# Abrir reporte HTML (macOS)
-open coverage/lcov-report/index.html
-
-# Abrir reporte HTML (Windows)
-start coverage/lcov-report/index.html
-
-# Abrir reporte HTML (Linux)
-xdg-open coverage/lcov-report/index.html
-```
-
-### Estructura del Reporte de Cobertura
-
-```
-coverage/
-├── lcov-report/          # Reporte HTML
-│   ├── index.html        # Vista general
-│   └── .sinapse-ai/       # Cobertura por modulo
-├── lcov.info             # Formato LCOV (para CI)
-├── coverage-summary.json # Resumen JSON
-└── clover.xml            # Formato Clover
-```
-
----
-
-## Integracion CI/CD
-
-### Workflow de GitHub Actions
-
-```yaml
-# .github/workflows/test.yml
-name: Tests
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  unit-tests:
-    name: Tests Unitarios
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          cache: 'npm'
-
-      - name: Instalar dependencias
-        run: npm ci
-
-      - name: Ejecutar tests unitarios
-        run: npm test
-
-      - name: Subir cobertura
-        uses: codecov/codecov-action@v4
-        with:
-          files: ./coverage/lcov.info
-          fail_ci_if_error: true
-
-  integration-tests:
-    name: Tests de Integracion
-    runs-on: ubuntu-latest
-    needs: unit-tests
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          cache: 'npm'
-
-      - name: Instalar dependencias
-        run: npm ci
-
-      - name: Ejecutar tests de integracion
-        run: SKIP_INTEGRATION_TESTS=false npm test -- --testPathPattern=integration
-        env:
-          CLICKUP_API_KEY: ${{ secrets.CLICKUP_API_KEY }}
-
-  quality-gate:
-    name: Quality Gate
-    runs-on: ubuntu-latest
-    needs: [unit-tests, integration-tests]
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-
-      - run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-      - name: TypeCheck
-        run: npm run typecheck
-
-      - name: Umbral de cobertura
-        run: npm run test:coverage -- --coverageReporters=text-summary
-```
-
-### Hook Pre-commit
-
-```bash
-#!/bin/sh
-# .husky/pre-commit
-
-# Ejecutar lint-staged
-npx lint-staged
-
-# Ejecutar tests unitarios rapidos
-npm test -- --passWithNoTests --testPathIgnorePatterns=integration,e2e
-```
-
-### Integracion con Quality Gate
-
-El Sistema de Quality Gate de SINAPSE (ver [Guia de Quality Gates](./quality-gates.md)) integra testing en multiples capas:
-
-| Capa        | Tipo de Test                  | Cuando         |
-| ----------- | ----------------------------- | -------------- |
-| **Capa 1**  | Unitario + Lint + TypeCheck   | Pre-commit     |
-| **Capa 2**  | Integracion + Review IA       | Creacion de PR |
-| **Capa 3**  | E2E + Review Humano           | Antes de merge |
-
----
-
-## Escribiendo Buenos Tests
-
-### Estructura de Test (Patron AAA)
-
-```javascript
-test('deberia calcular precio total con descuento', () => {
-  // Arrange - Configurar datos y condiciones de test
-  const cart = new ShoppingCart();
-  cart.addItem({ name: 'Widget', price: 100 });
-  cart.addItem({ name: 'Gadget', price: 50 });
-  const discount = 0.1; // 10% de descuento
-
-  // Act - Ejecutar el codigo bajo prueba
-  const total = cart.calculateTotal(discount);
-
-  // Assert - Verificar los resultados
-  expect(total).toBe(135); // (100 + 50) * 0.9
-});
-```
-
-### Guias de Nombres de Tests
-
-| Malo            | Bueno                                                       |
-| --------------- | ----------------------------------------------------------- |
-| `test('test1')` | `test('deberia retornar null para entrada vacia')`          |
-| `test('works')` | `test('deberia calcular impuesto correctamente')`           |
-| `test('error')` | `test('deberia lanzar ValidationError para email invalido')`|
-
-### Casos Limite a Probar
-
-```javascript
-describe('validateEmail', () => {
-  // Camino feliz
-  test('deberia aceptar email valido', () => {
-    expect(validateEmail('user@example.com')).toBe(true);
-  });
-
-  // Casos limite
-  test('deberia rechazar string vacio', () => {
-    expect(validateEmail('')).toBe(false);
-  });
-
-  test('deberia rechazar null', () => {
-    expect(validateEmail(null)).toBe(false);
-  });
-
-  test('deberia rechazar undefined', () => {
-    expect(validateEmail(undefined)).toBe(false);
-  });
-
-  // Condiciones de frontera
-  test('deberia aceptar email con parte local de un caracter', () => {
-    expect(validateEmail('a@example.com')).toBe(true);
-  });
-
-  test('deberia rechazar email sin simbolo @', () => {
-    expect(validateEmail('userexample.com')).toBe(false);
-  });
-
-  // Caracteres especiales
-  test('deberia aceptar email con signo mas', () => {
-    expect(validateEmail('user+tag@example.com')).toBe(true);
-  });
-});
-```
-
-### Patrones de Tests Asincronos
-
-```javascript
-// Usando async/await (recomendado)
-test('deberia obtener datos de usuario', async () => {
-  const user = await fetchUser(123);
-  expect(user.name).toBe('John');
-});
-
-// Probando rechazo de promesa
-test('deberia rechazar para usuario inexistente', async () => {
-  await expect(fetchUser(999)).rejects.toThrow('User not found');
-});
-
-// Probando con callback done (legacy)
-test('deberia llamar callback con datos', (done) => {
-  fetchUserCallback(123, (err, user) => {
-    expect(err).toBeNull();
-    expect(user.name).toBe('John');
-    done();
-  });
-});
-```
-
-### Aislamiento de Tests
-
-```javascript
-describe('FileManager', () => {
-  let tempDir;
-  let fileManager;
-
-  beforeEach(async () => {
-    // Crear directorio temporal aislado para cada test
-    tempDir = await createTempDir();
-    fileManager = new FileManager(tempDir);
-  });
-
-  afterEach(async () => {
-    // Limpiar despues de cada test
-    await removeTempDir(tempDir);
-  });
-
-  test('deberia crear archivo', async () => {
-    await fileManager.write('test.txt', 'content');
-    const exists = await fileManager.exists('test.txt');
-    expect(exists).toBe(true);
-  });
-
-  test('no deberia ver archivos de otros tests', async () => {
-    // Este test comienza con un directorio limpio
-    const files = await fileManager.list();
-    expect(files).toHaveLength(0);
-  });
-});
-```
-
----
-
-## Mocking y Fixtures
-
-### Basicos de Mocking en Jest
-
-```javascript
-// Mock de un modulo
-jest.mock('fs-extra');
-const fs = require('fs-extra');
-
-// Implementacion mock
-fs.readFile.mockResolvedValue('file content');
-fs.writeFile.mockResolvedValue(undefined);
-
-// Valor de retorno mock
-fs.existsSync.mockReturnValue(true);
-
-// Implementacion mock para llamada especifica
-fs.readFile.mockImplementation((path) => {
-  if (path === 'config.json') {
-    return Promise.resolve('{"key": "value"}');
-  }
-  return Promise.reject(new Error('File not found'));
-});
-```
-
-### Creando Fixtures de Test
-
-```javascript
-// tests/fixtures/agent-fixtures.js
-const MOCK_AGENT = {
-  name: 'test-agent',
-  slashPrefix: 'test',
-  icon: '🧪',
-  persona: {
-    role: 'Test Agent',
-    expertise: ['testing'],
-  },
-  commands: [
-    {
-      name: '*test',
-      description: 'Run tests',
-      visibility: 'all',
-    },
-  ],
-};
-
-const MOCK_SQUAD = {
-  name: 'test-squad',
-  version: '1.0.0',
-  agents: [MOCK_AGENT],
-  tasks: [],
-};
-
-module.exports = {
-  MOCK_AGENT,
-  MOCK_SQUAD,
-};
-```
-
-### Usando Fixtures en Tests
-
-```javascript
-const { MOCK_AGENT, MOCK_SQUAD } = require('../fixtures/agent-fixtures');
-
-describe('AgentLoader', () => {
-  test('deberia cargar agente desde fixture', async () => {
-    // Mock del sistema de archivos para retornar datos de fixture
-    jest.spyOn(fs, 'readFile').mockResolvedValue(JSON.stringify(MOCK_AGENT));
-
-    const agent = await loadAgent('test-agent');
-
-    expect(agent.name).toBe(MOCK_AGENT.name);
-    expect(agent.commands).toHaveLength(1);
-  });
-});
-```
-
-### Mocking de Servicios Externos
-
-```javascript
-// Mock de API de ClickUp
-jest.mock('../../.sinapse-ai/integrations/clickup-client');
-const clickupClient = require('../../.sinapse-ai/integrations/clickup-client');
-
-describe('Sincronizacion de Story', () => {
-  beforeEach(() => {
-    // Resetear mocks antes de cada test
-    jest.clearAllMocks();
-
-    // Configurar implementaciones mock por defecto
-    clickupClient.createTask.mockResolvedValue({
-      id: 'task-123',
-      name: 'Test Task',
-    });
-
-    clickupClient.updateTask.mockResolvedValue({
-      id: 'task-123',
-      status: 'in progress',
-    });
-  });
-
-  test('deberia crear tarea en ClickUp', async () => {
-    const result = await syncStory({ title: 'New Feature' });
-
-    expect(clickupClient.createTask).toHaveBeenCalledWith({
-      name: 'New Feature',
-      list_id: expect.any(String),
-    });
-    expect(result.clickupId).toBe('task-123');
-  });
-
-  test('deberia manejar errores de API de ClickUp', async () => {
-    clickupClient.createTask.mockRejectedValue(new Error('API rate limited'));
-
-    await expect(syncStory({ title: 'New Feature' })).rejects.toThrow(
-      'Failed to sync: API rate limited'
-    );
-  });
-});
-```
-
-### Testing de Snapshots
-
-```javascript
-describe('GreetingBuilder', () => {
-  test('deberia generar formato de saludo consistente', async () => {
-    const builder = new GreetingBuilder();
-    const greeting = await builder.build({
-      agent: 'dev',
-      sessionType: 'new',
-      timestamp: new Date('2025-01-01T00:00:00Z'), // Timestamp fijo
-    });
-
-    // Comparacion de snapshot
-    expect(greeting).toMatchSnapshot();
-  });
-});
-```
-
----
-
-## Referencia de Comandos NPM
-
-### Comandos Basicos
-
-| Comando                 | Descripcion                          |
-| ----------------------- | ------------------------------------ |
-| `npm test`              | Ejecutar todos los tests             |
-| `npm run test:watch`    | Ejecutar tests en modo watch         |
-| `npm run test:coverage` | Ejecutar tests con reporte cobertura |
-
-### Comandos de Tests Filtrados
-
-```bash
-# Ejecutar tests que coincidan con patron
-npm test -- --testPathPattern=unit
-
-# Ejecutar archivo de test especifico
-npm test -- tests/unit/greeting-builder.test.js
-
-# Ejecutar tests que coincidan con nombre
-npm test -- --testNamePattern="should validate"
-
-# Ejecutar tests en directorio especifico
-npm test -- tests/integration/
-```
-
-### Comandos de Cobertura
-
-```bash
-# Generar reporte completo de cobertura
-npm run test:coverage
-
-# Cobertura con reporter especifico
-npm test -- --coverage --coverageReporters=text
-
-# Cobertura para archivos especificos
-npm test -- --coverage --collectCoverageFrom="src/**/*.js"
-```
-
-### Opciones de Modo Watch
-
-```bash
-# Watch todos los tests
-npm run test:watch
-
-# Watch archivos especificos
-npm test -- --watch --testPathPattern=unit
-
-# Watch solo archivos modificados
-npm test -- --watchAll=false --watch
-```
-
-### Modo Debug
-
-```bash
-# Ejecutar con salida verbose
-npm test -- --verbose
-
-# Ejecutar test individual para debugging
-npm test -- --runInBand tests/unit/specific.test.js
-
-# Ejecutar con debugger de Node
-node --inspect-brk node_modules/.bin/jest --runInBand
-```
-
-### Comandos Especificos de CI
-
-```bash
-# Ejecutar en modo CI (sin colores, cobertura, etc.)
-npm test -- --ci
-
-# Ejecutar con max workers
-npm test -- --maxWorkers=4
-
-# Detener en primer fallo
-npm test -- --bail
-
-# Ejecutar solo archivos modificados (Git)
-npm test -- --changedSince=main
-```
-
----
-
-## Solucion de Problemas
-
-### Problemas Comunes
-
-| Problema             | Solucion                                             |
-| -------------------- | ---------------------------------------------------- |
-| Tests timeout        | Aumentar `testTimeout` en config o test especifico   |
-| Tests async cuelgan  | Asegurar que todas las promesas estan awaited        |
-| Mock no funciona     | Verificar que mock esta antes de `require()`         |
-| Cobertura baja       | Agregar patrones `--collectCoverageFrom`             |
-| Tests inestables     | Verificar estado compartido, usar limpieza `beforeEach` |
-
-### Debuggeando Tests que Cuelgan
-
-```javascript
-// Agregar timeout a test especifico
-test('operacion lenta', async () => {
-  // ...
-}, 60000); // 60 segundos de timeout
-
-// Debug con salida de consola
-test('debug test', async () => {
-  console.log('Paso 1');
-  await step1();
-  console.log('Paso 2');
-  await step2();
-  console.log('Listo');
-});
-```
-
-### Arreglando Problemas de Mock
-
-```javascript
-// Incorrecto: Mock despues de require
-const myModule = require('./myModule');
-jest.mock('./myModule');
-
-// Correcto: Mock antes de require
-jest.mock('./myModule');
-const myModule = require('./myModule');
-
-// O usar jest.doMock para mocking dinamico
-beforeEach(() => {
-  jest.resetModules();
-  jest.doMock('./myModule', () => ({
-    func: jest.fn().mockReturnValue('mocked'),
-  }));
-});
-```
-
-### Resolviendo Problemas de Cobertura
-
-```javascript
-// Cobertura no recolecta? Verificar paths
-module.exports = {
-  collectCoverageFrom: [
-    // Usar paths relativos desde raiz del proyecto
-    'src/**/*.js',
-    // Patrones de exclusion
-    '!**/node_modules/**',
-  ],
-  // Directorios raiz para buscar
-  roots: ['<rootDir>'],
-};
-```
-
----
-
-## Documentacion Relacionada
-
-- [Guia de Quality Gates](./quality-gates.md) - Chequeos automatizados de calidad
-- [Arquitectura CI/CD](../../architecture/ci-cd.md) - Configuracion de pipeline
-- [Guia de Contribucion](../../how-to-contribute-with-pull-requests.md) - Workflow de desarrollo
-
----
-
-_Guia de Testing de SINAPSE v4_