Documentación de Pruebas de Integración: Guía Completa de Contratos API e Interfaces de Sistema

Las pruebas de integración validan cómo diferentes componentes, servicios y sistemas trabajan juntos. La Documentación Comprensiva de Pruebas de Integración asegura que los equipos comprendan los límites del sistema, contratos API, flujos de datos y relaciones de dependencias. Esta guía explora enfoques efectivos para documentar pruebas de integración en sistemas distribuidos modernos.

Entendiendo la Documentación de Pruebas de Integración

Las pruebas de integración se sitúan entre pruebas unitarias (testeando componentes individuales) y pruebas end-to-end (testeando journeys completos de usuario). Verifican que las interfaces entre sistemas se comuniquen correctamente, los datos se transformen apropiadamente y el manejo de errores funcione a través de límites.

Componentes Clave de la Documentación

La documentación efectiva de pruebas de integración incluye:

Especificaciones de Contratos API: Definiciones claras de interfaces y expectativas
Mapas de Interfaces del Sistema: Representaciones visuales y textuales de puntos de integración
Diagramas de Flujo de Datos: Cómo se mueven y transforman los datos entre sistemas
Mapeo de Dependencias: Comprensión de relaciones de servicio y cadenas de llamadas
Requisitos de Datos de Prueba: Datos específicos necesarios para escenarios de integración
Configuración de Entorno: Requisitos de configuración para pruebas de integración
Escenarios de Error: Cómo los sistemas manejan fallos en puntos de integración

Documentación de Contratos API

Enfoque de Pruebas Contract-First

Documenta contratos API antes de la implementación para expectativas claras:

# user-service-contract.yaml
openapi: 3.0.0
info:
  title: API de Servicio de Usuarios
  version: 2.1.0
  description: Servicio de gestión de usuarios y autenticación

paths:
  /api/users/{userId}:
    get:
      summary: Obtener detalles de usuario
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Usuario encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Usuario no encontrado
        '500':
          description: Error interno del servidor

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - status
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        status:
          type: string
          enum: [active, inactive, suspended]

Escenarios de Prueba de Integración desde Contratos

# test_user_service_integration.py
import pytest
import requests

class TestUserServiceIntegration:
    """
    Pruebas de integración para API de Servicio de Usuarios
    Basado en contrato: user-service-contract.yaml v2.1.0
    """

    BASE_URL = "https://api-staging.example.com"

    def test_get_user_success_contract(self, auth_headers):
        """
        Verificar GET /api/users/{userId} retorna datos que coinciden con contrato
        Contrato: respuesta 200 debe coincidir con esquema User
        """
        user_id = "550e8400-e29b-41d4-a716-446655440000"
        response = requests.get(
            f"{self.BASE_URL}/api/users/{user_id}",
            headers=auth_headers
        )

        # Verificar código de estado según contrato
        assert response.status_code == 200

        # Verificar estructura de respuesta coincide con contrato
        data = response.json()
        assert "id" in data
        assert "email" in data
        assert "status" in data
        assert data["status"] in ["active", "inactive", "suspended"]

    def test_create_user_contract_validation(self, auth_headers):
        """
        Verificar POST /api/users valida request según contrato
        Contrato: 400 para request inválido, 201 para éxito
        """
        # Probar formato de email inválido
        invalid_payload = {
            "email": "not-an-email",
            "firstName": "John"
        }
        response = requests.post(
            f"{self.BASE_URL}/api/users",
            json=invalid_payload,
            headers=auth_headers
        )
        assert response.status_code == 400

        # Probar creación válida
        valid_payload = {
            "email": "test@example.com",
            "firstName": "John",
            "lastName": "Doe"
        }
        response = requests.post(
            f"{self.BASE_URL}/api/users",
            json=valid_payload,
            headers=auth_headers
        )
        assert response.status_code == 201

Mapeo de Interfaces del Sistema

Documentación de Puntos de Integración

# Mapa de Integración del Sistema

## Visión General de Arquitectura

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Web Frontend │─────▶│ API Gateway │─────▶│ Servicio Usuario│ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ │ Servicio Pedidos │ │ Servicio Auth │ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Gateway de Pago │ │ (Externo) │ └──────────────────┘


## Puntos de Integración

### 1. Frontend ↔ API Gateway
**Protocolo**: HTTPS/REST
**Autenticación**: JWT Bearer Token
**Formato de Datos**: JSON
**Pruebas de Integración**: `tests/integration/frontend_api/`

| Endpoint | Método | Propósito | Cobertura de Pruebas |
|----------|--------|-----------|----------------------|
| /api/login | POST | Autenticación usuario | ✅ Happy path, credenciales inválidas, token expirado |
| /api/products | GET | Listado de productos | ✅ Paginación, filtrado, resultados vacíos |
| /api/orders | POST | Creación de pedido | ✅ Pedido válido, stock insuficiente, fallo de pago |

### 2. API Gateway ↔ Servicio de Usuario
**Protocolo**: gRPC
**Autenticación**: mTLS Servicio-a-Servicio
**Formato de Datos**: Protobuf
**Pruebas de Integración**: `tests/integration/gateway_user/`

| Método RPC | Propósito | Escenarios de Error Testeados |
|------------|-----------|-------------------------------|
| GetUser | Obtener detalles de usuario | Usuario no encontrado, timeout de servicio |
| ValidateToken | Verificación de token | Token inválido, token expirado, token revocado |
| UpdateProfile | Actualización de datos de usuario | Errores de validación, actualizaciones concurrentes |

Grafo de Dependencias

# service-dependencies.yaml
servicios:
  api-gateway:
    depende_de:
      - servicio-usuario
      - servicio-pedidos
      - servicio-productos
    pruebas_integracion:
      - test_flujo_autenticacion_usuario
      - test_flujo_colocacion_pedido
      - test_flujo_busqueda_productos

  servicio-pedidos:
    depende_de:
      - servicio-usuario (autenticación)
      - servicio-inventario (validación de stock)
      - gateway-pago (externo)
      - servicio-notificaciones (confirmación de pedido)
    pruebas_integracion:
      - test_creacion_pedido_con_auth
      - test_validacion_inventario
      - test_procesamiento_pago
      - test_notificaciones_pedido
    escenarios_fallo:
      - servicio_inventario_caido: "Fallback a niveles de stock en caché"
      - timeout_gateway_pago: "Encolar para reintento, notificar usuario"
      - servicio_notificaciones_caido: "Encolar notificaciones, pedido procede"

Documentación de Flujo de Datos

Mapeo de Flujo Request/Response

## Flujo de Datos de Creación de Pedido

### Flujo de Request

Request Cliente ↓ [API Gateway] - Valida JWT, rate limiting ↓ (gRPC) [Servicio Auth] - Verifica permisos de usuario ↓ (retorna user_id, permisos) [API Gateway] - Enriquece request con contexto de usuario ↓ (REST) [Servicio Pedidos] - Recibe request de pedido ↓ (gRPC) [Servicio Inventario] - Verifica disponibilidad de stock ↓ (retorna stock_status) [Servicio Pedidos] - Crea registro de pedido (status: pending) ↓ (REST) [Gateway de Pago] - Procesa pago ↓ (webhook) [Servicio Pedidos] - Actualiza pedido (status: confirmed) ↓ (Message Queue) [Servicio Notificaciones] - Envía email de confirmación ↓ Respuesta a Cliente


### Transformación de Datos

| Etapa | Esquema de Entrada | Esquema de Salida | Transformación |
|-------|-------------------|-------------------|----------------|
| Cliente → Gateway | `{ items: [{productId, qty}], shipping: {...} }` | + `userId`, `timestamp`, `requestId` | Enriquecimiento |
| Gateway → Pedidos | Request enriquecido | + `userEmail`, `userName` de Auth | Búsqueda de usuario |
| Pedidos → Inventario | `{ productId: string, quantity: number }[]` | `{ available: boolean, reservationId?: string }` | Verificación de stock |

Mejores Prácticas

Checklist de Pruebas de Integración

Aspecto	Verificación	Estado
Validación de Contrato	✅ Request/response coinciden con esquema
Autenticación	✅ Auth válido aceptado, inválido rechazado
Autorización	✅ Permisos aplicados correctamente
Validación de Datos	✅ Datos inválidos rechazados con errores claros
Manejo de Errores	✅ Errores se propagan correctamente
Idempotencia	✅ Requests duplicados manejados apropiadamente
Manejo de Timeout	✅ Timeouts activan comportamiento de fallback
Circuit Breaker	✅ Se abre en fallos, se recupera apropiadamente
Consistencia de Datos	✅ Transacciones distribuidas completan o rollback
Rendimiento	✅ Tiempos de respuesta dentro de SLA

Conclusión

La Documentación Comprensiva de Pruebas de Integración asegura que los equipos entiendan cómo interactúan los servicios, qué contratos gobiernan esas interacciones y cómo fluyen los datos a través del sistema. Al documentar contratos API, mapear dependencias, visualizar flujos de datos y probar escenarios de error, creas una base robusta para sistemas distribuidos confiables.

Recuerda: las pruebas de integración son tu red de seguridad para la comunicación de servicios. Invierte en documentación clara, mantén contratos rigurosamente y prueba tanto happy paths como escenarios de fallo para construir sistemas resilientes y bien integrados.