Package Exports

@machina.ai/openapi-contract-tester
@machina.ai/openapi-contract-tester/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@machina.ai/openapi-contract-tester) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

OpenAPI Contract Tester - MCP Server

✅ Status: COMPLETE MVP - Fases 1-18 Implementadas

Servidor MCP (Model Context Protocol) para testing comprehensivo de APIs basado en especificaciones OpenAPI 3.x con soporte para contract testing usando Pact.

🎯 Características

Generación de Tests

✅ Happy Path Tests: Tests con datos válidos para casos exitosos
✅ Edge Case Tests: Boundary Value Analysis (valores límite, enums, campos opcionales)
✅ Error Case Tests: Tests de errores 400/401/404 (campos faltantes, formatos inválidos, constraints)

Ejecución de Tests

✅ HTTP Client con Playwright: Cliente robusto con soporte para todos los métodos HTTP
✅ Ejecución Paralela: Ejecuta múltiples tests en paralelo
✅ Validación de Schemas: Valida responses contra schemas OpenAPI usando ajv
✅ Soporte de Autenticación: Bearer, API Key, Basic, OAuth2

Contract Testing

✅ Generación de Contratos Pact: Convierte OpenAPI a contratos Pact
✅ Pact Matchers: Matching flexible basado en tipos
✅ Verificación de Provider: Verifica que el provider implementa el contrato
✅ Pact Broker: Publicación y descarga de contratos

Error Handling & Resilience

✅ Custom Error Classes: Errores semánticos con códigos (E001-E999) y mensajes user-friendly
✅ Retry Logic: Exponential backoff para errores transitorios (timeout, network)
✅ Circuit Breaker: Previene cascading failures con estados CLOSED/OPEN/HALF_OPEN
✅ Error Wrapping: Conversión automática de errores nativos a errores custom
✅ Structured Logging: Sistema de logs compatible con STDIO que escribe a archivo en modo MCP

MCP Tools (4 herramientas principales)

generate-tests: Genera tests inteligentes desde especificaciones OpenAPI
- Happy path, edge cases, error cases
- Auto-detección de dependencias entre tests
- Generación de datos con IA contextual
run-tests: Ejecuta tests contra APIs con análisis avanzado
- Ejecución paralela con control de dependencias
- Auto-detección de tokens (24 campos conocidos)
- Validación de schemas automática
- AI-powered failure analysis
export-results: Exporta resultados con análisis profundo
- Formatos: JSON, HTML profesional, Markdown
- Auto-comparación: Si detecta specPath + codeEndpoints, ejecuta compare-sources automáticamente
- Root Cause Analysis: Correlaciona fallos con discrepancias conocidas
- Coverage analysis integrado
- AI-powered insights y recomendaciones
compare-sources: Compara OpenAPI spec vs Código vs PRD
- Priorización inteligente: Critical/High/Medium/Low según keywords
- Reporte HTML visual: Matriz de endpoints, discrepancias color-coded
- Detección semántica IA: Encuentra matches no obvios (POST /users ≈ POST /register)
- Business rule mappings (PRD → código)
- Sugerencias de remediación accionables

📊 Reportes Profesionales

HTML: Diseño moderno con gradientes, cards interactivos, tablas responsivas y progress bars
Markdown: Tablas con emojis, executive summary, métricas de performance y detalles de fallos
Contenido: Summary dashboard, breakdown por categoría/endpoint, failed tests con errores detallados

📦 Instalación

Instalación para Desarrollo

npm install
npm run build

Instalación desde npm (Cuando esté publicado)

npm install -g openapi-contract-tester

🧪 Testing Local (Pre-Publicación)

Para probar el paquete como si estuviera instalado desde npm:

Opción 1: npm link (desarrollo activo)

npm run build
npm link

# Ahora puedes usar el comando globalmente
which openapi-contract-tester

Uso: Ideal para desarrollo cuando haces cambios frecuentes. Los cambios se reflejan inmediatamente.

Opción 2: npm pack (testing de publicación)

npm run build
npm pack
# Crea: openapi-contract-tester-1.0.0.tgz

# Instalar globalmente desde el tarball
npm install -g ./openapi-contract-tester-1.0.0.tgz

# Verificar instalación
which openapi-contract-tester
# Output: /usr/local/lib/node_modules/openapi-contract-tester/dist/index.js

Uso: Prueba exacta de cómo funcionará cuando se publique en npm. Útil para validación final antes de npm publish.

Configuración en cell-cli (después de instalar con cualquier opción):

{
  "mcpServers": {
    "openapi-contract-tester": {
      "command": "openapi-contract-tester",
      "env": {
        "MCP_ROOT": "~/.openapi-contract-tester",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Nota: Por defecto usa gemini-3-flash-preview. Puedes cambiar el modelo con AI_MODEL en env.

Limpiar instalación de prueba:

# Si usaste npm link
npm unlink -g openapi-contract-tester

# Si usaste npm install -g
npm uninstall -g openapi-contract-tester

# Limpiar tarball
rm openapi-contract-tester-*.tgz

⚙️ Configuración

Variables de Entorno

Todas las configuraciones pueden ser controladas vía variables de entorno:

Directorios y Logging

MCP_ROOT=~/.openapi-contract-tester     # Directorio raíz (default: ~/.openapi-contract-tester)
LOG_LEVEL=info                           # Nivel de log: debug, info, warn, error (default: info)
LOG_DIR=/custom/path/logs                # Override del directorio de logs
MAX_LOG_FILE_SIZE=10485760               # Tamaño máximo antes de rotación en bytes (default: 10MB)
MAX_LOG_FILES=5                          # Número de archivos rotados a mantener (default: 5)

AI/LLM Configuration

# Opción 1: Solo cambiar el modelo (recomendado)
AI_MODEL=gemini-3-flash-preview          # Nombre del modelo (default: gemini-3-flash-preview)

# Opción 2: Cambiar modelo a versión anterior
AI_MODEL=gemini-2.5-flash                # Usa gemini-2.5-flash en lugar del default

# Opción 3: URL completa personalizada (override total)
AI_API_URL=https://custom-api.com/v1/generate

# Opción 4: Configuración avanzada
AI_BASE_URL=http://localhost:13800/cell_apps/v1.1/gemini/v1beta/models  # Base URL (default)
AI_MODEL=gemini-3-flash-preview          # Modelo específico
AI_ENDPOINT=generateContent              # Endpoint de generación (default: generateContent)

Prioridad de configuración:

AI_API_URL - URL completa (ignora otras variables)
AI_MODEL + AI_BASE_URL + AI_ENDPOINT - Construcción dinámica
Valores por defecto (gemini-3-flash-preview)

HTTP y Performance

HTTP_TIMEOUT=5000                        # Timeout para requests HTTP en ms (default: 5000)
MAX_PARALLEL_REQUESTS=5                  # Requests HTTP paralelos (default: 5)
MAX_PARALLEL_TESTS=5                     # Tests paralelos (default: 5)
TEST_TIMEOUT=30000                       # Timeout de test execution en ms (default: 30000)

Retry Logic

RETRY_MAX_ATTEMPTS=3                     # Máximo de reintentos (default: 3)
RETRY_INITIAL_DELAY=1000                 # Delay inicial en ms (default: 1000)
RETRY_MAX_DELAY=10000                    # Delay máximo en ms (default: 10000)
RETRY_BACKOFF_MULTIPLIER=2               # Multiplicador para backoff (default: 2)

Circuit Breaker

CIRCUIT_BREAKER_THRESHOLD=5              # Failures antes de abrir (default: 5)
CIRCUIT_BREAKER_TIMEOUT=60000            # Tiempo antes de HALF_OPEN en ms (default: 60000)
CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2      # Éxitos para cerrar en HALF_OPEN (default: 2)

Estructura de Directorios

Cuando se configura MCP_ROOT, se crea la siguiente estructura:

~/.openapi-contract-tester/
└── logs/
    ├── mcp-server-2025-01-19.log
    └── mcp-server-2025-01-19-2025-01-19T10-30-00-123Z.log (rotados)

🚀 Uso

Como MCP Server para cell-cli

Configura cell-cli para usar este servidor MCP:

{
  "mcpServers": {
    "openapi-contract-tester": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp_testing/dist/index.js"],
      "env": {
        "MCP_ROOT": "~/.openapi-contract-tester",
        "LOG_LEVEL": "info",
        "AI_MODEL": "gemini-3-flash-preview",
        "HTTP_TIMEOUT": "10000",
        "MAX_PARALLEL_TESTS": "10",
        "RETRY_MAX_ATTEMPTS": "3",
        "CIRCUIT_BREAKER_THRESHOLD": "5"
      }
    }
  }
}

Configuración Mínima:

{
  "mcpServers": {
    "openapi-contract-tester": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp_testing/dist/index.js"],
      "env": {
        "MCP_ROOT": "~/.openapi-contract-tester",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Nota: Si no especificas AI_MODEL, usa gemini-3-flash-preview por defecto.

Usa los tools desde cell-cli:

> Genera tests para mi API usando el archivo ./api.yml
> Ejecuta los tests contra http://localhost:8080
> Crea un contrato Pact entre mi-app y user-api

Uso Directo (sin cell-cli)

1. Generar Tests

import { parseOpenAPISpec, extractEndpoints } from './dist/parsers/openapi-parser.js';
import { generateHappyPathTests } from './dist/generators/happy-path-generator.js';
import { generateEdgeCaseTests } from './dist/generators/edge-case-generator.js';
import { generateErrorCaseTests } from './dist/generators/error-case-generator.js';

// Parsear especificación
const spec = await parseOpenAPISpec('./api.yml');
const endpoints = extractEndpoints(spec);

// Generar tests
const happyTests = generateHappyPathTests(endpoints, { seed: 42 });
const edgeTests = generateEdgeCaseTests(endpoints, { seed: 42 });
const errorTests = generateErrorCaseTests(endpoints, spec, { seed: 42 });

console.log(`Generated ${happyTests.length + edgeTests.length + errorTests.length} tests`);

2. Ejecutar Tests

import { TestRunner } from './dist/executor/test-runner.js';

const environment = {
  name: 'local',
  baseUrl: 'http://localhost:8080',
  timeout: 5000,
  auth: {
    type: 'bearer',
    token: 'your-token-here'
  }
};

const runner = new TestRunner(environment);
const { results, summary } = await runner.runTests(allTests, endpoints, {
  parallel: 5,
  validateSchemas: true,
  onProgress: (completed, total, current) => {
    console.log(`Progress: ${completed}/${total} - ${current.name}`);
  }
});

console.log(`Passed: ${summary.passed}/${summary.total}`);
console.log(`Failed: ${summary.failed}/${summary.total}`);
console.log(`Avg Response Time: ${summary.avgResponseTime}ms`);

3. Contract Testing con Pact

import { generatePactContract, pactContractToJSON } from './dist/pact/pact-generator.js';
import { verifyPactProvider } from './dist/pact/pact-executor.js';
import fs from 'fs/promises';

// Generar contrato
const contract = generatePactContract(endpoints, {
  consumer: 'my-app',
  provider: 'user-api',
  useMatchers: true
});

// Guardar contrato
await fs.writeFile(
  './pacts/my-app-user-api.json',
  pactContractToJSON(contract, true)
);

// Verificar provider
const result = await verifyPactProvider({
  provider: 'user-api',
  providerBaseUrl: 'http://localhost:8080',
  pactUrls: ['./pacts/my-app-user-api.json']
});

console.log(`Verification: ${result.success ? 'PASSED' : 'FAILED'}`);

📊 Ejemplo de Salida

Generación de Tests

Desde una API de 5 endpoints + 3 archivos de documentación:

✅ Happy Path Tests: 4
✅ Edge Case Tests: 24
✅ Error Case Tests: 34
✅ Business Rules Tests: 48 (desde docs/)
📈 Total: 110 tests

Ejecución de Tests

Summary:
  Total: 62
  Passed: 58 (93.55%)
  Failed: 4 (6.45%)
  Duration: 2,345ms
  Avg Response Time: 156ms

By Category:
  happy-path: 4 passed, 0 failed
  edge-case: 22 passed, 2 failed
  error-case: 32 passed, 2 failed

By Endpoint:
  GET /users: 7 tests (7 passed)
  POST /users: 28 tests (26 passed, 2 failed)
  GET /users/{id}: 4 tests (4 passed)
  PUT /users/{id}: 24 tests (22 passed, 2 failed)
  DELETE /users/{id}: 3 tests (3 passed)

📁 Estructura del Proyecto

mcp_testing/
├── src/
│   ├── types/
│   │   └── index.ts (800+ líneas de tipos con JSDoc)
│   ├── parsers/
│   │   └── openapi-parser.ts (400+ líneas)
│   ├── generators/
│   │   ├── data-generator.ts (500+ líneas)
│   │   ├── happy-path-generator.ts (300+ líneas)
│   │   ├── edge-case-generator.ts (450+ líneas)
│   │   └── error-case-generator.ts (450+ líneas)
│   ├── validators/
│   │   ├── schema-validator.ts (400+ líneas)
│   │   └── openapi-validator.ts (400+ líneas)
│   ├── executor/
│   │   ├── http-client.ts (400+ líneas)
│   │   └── test-runner.ts (500+ líneas)
│   ├── pact/
│   │   ├── pact-generator.ts (450+ líneas)
│   │   └── pact-executor.ts (500+ líneas)
│   ├── utils/
│   │   ├── logger.ts (400+ líneas)
│   │   ├── errors.ts (450+ líneas)
│   │   └── resilience.ts (350+ líneas)
│   ├── mcp/
│   │   └── server.ts (650+ líneas)
│   └── index.ts (Entry point)
├── examples/
│   └── user-service.yml
├── LOGGING.md (Logging documentation)
├── ERROR-HANDLING.md (Error handling documentation)
├── package.json
├── tsconfig.json
└── README.md

Total: ~7,700+ líneas de código TypeScript con 100% JSDoc

🧪 Testing

# Ejecutar tests de validación
node quick-test.js
node test-all-generators.js
node test-schema-validator.js
node test-openapi-validator.js
node test-business-rules.js
node test-logger.js
node test-error-handling.js
node test-config.js

# Test con variables de entorno personalizadas
HTTP_TIMEOUT=10000 MAX_PARALLEL_TESTS=10 LOG_LEVEL=debug node test-config.js

🔧 Tecnologías

TypeScript: Strict mode con tipos completos
Playwright: HTTP client robusto
Pact: Contract testing consumer-driven
ajv: Validación de JSON Schemas
Faker.js: Generación de datos realistas
MCP SDK: Integración con CLI conversacional con MCP
Node.js 18+: ES Modules, async/await

📖 Mejores Prácticas Aplicadas

✅ TypeScript strict mode
✅ 100% JSDoc coverage
✅ ESLint + Prettier
✅ Node.js 2025 best practices
✅ Error handling comprehensivo con retry & circuit breaker
✅ Async/await patterns
✅ ES Modules (type: "module")
✅ Reproducible test generation (seeds)
✅ STDIO-safe logging para protocolo MCP
✅ Structured error codes (E001-E999)

📚 Documentación

LOGGING.md - Sistema de logging compatible con MCP
ERROR-HANDLING.md - Error handling, retry logic y circuit breaker

📝 Licencia

MIT

Servidor MCP completo para testing de APIs con OpenAPI 3.x, Playwright, y Pact.