DEV Community

Cover image for Herramienta mock API headless: servidores mock para CI sin GUI
Roobia
Roobia

Posted on • Originally published at apidog.com

Herramienta mock API headless: servidores mock para CI sin GUI

Un motor de simulación de API sin interfaz (headless) crea una versión falsa y funcional de tu API desde una especificación o configuración y la ejecuta desde la línea de comandos, sin una ventana gráfica. Es el tipo de mock que puedes usar en CI, Docker o scripts de desarrollo frontend. En esta guía verás qué significa “sin interfaz”, cómo usar opciones reales como Prism, WireMock y Mockoon CLI, y dónde encaja Apidog. Si necesitas la base conceptual, empieza por qué es una API mock.

Prueba Apidog hoy

Qué significa “sin interfaz” para una simulación de API

Un servidor mock responde a solicitudes HTTP con respuestas falsas pero realistas. Esto permite que un frontend, una suite de pruebas o un entorno de integración funcionen antes de que el backend real esté listo.

“Sin interfaz” significa que el mock no depende de una GUI. Lo arrancas con un comando, le pasas una especificación o archivo de configuración, y queda escuchando en un puerto o en una URL alojada.

Casos típicos:

  • Ejecutar pruebas en una pipeline de CI.
  • Levantar un mock dentro de docker-compose.
  • Compartir un backend falso con el equipo.
  • Crear entornos de preview por cada pull request.
  • Desarrollar frontend sin bloquearte por el backend.

Una GUI puede ser útil para diseñar respuestas. Pero cuando necesitas automatización, necesitas una de estas opciones:

  • Un comando CLI.
  • Una imagen Docker.
  • Un servidor local accesible por red.
  • Una URL mock alojada.

Simulaciones impulsadas por especificaciones vs. por configuración

Antes de elegir herramienta, define cuál será la fuente de verdad del mock.

Simulación impulsada por especificaciones

La herramienta lee un documento OpenAPI y genera respuestas desde el contrato.

Ejemplo de flujo:

openapi.yaml -> mock server -> frontend/tests
Enter fullscreen mode Exit fullscreen mode

Ventajas:

  • El mock se mantiene cerca del contrato.
  • Menos configuración manual.
  • Útil para APIs diseñadas con enfoque contract-first.
  • Cambias el esquema y el mock refleja el cambio.

Este enfoque encaja bien cuando tu API ya está documentada en OpenAPI.

Simulación impulsada por configuración

La herramienta usa archivos propios, reglas, stubs o respuestas grabadas.

Ejemplo:

mappings/*.json -> mock server -> frontend/tests
Enter fullscreen mode Exit fullscreen mode

Ventajas:

  • Más control sobre casos límite.
  • Buena para simular estados, errores y reglas complejas.
  • Útil cuando no tienes una especificación formal.
  • Permite grabar tráfico real y reproducirlo.

El patrón más práctico suele ser combinar ambos: usar la especificación para el camino feliz y reglas personalizadas para errores, estados y casos extremos. Para profundizar, revisa esta guía de simulación de API.

Opciones reales para ejecutar mocks sin interfaz

Estas herramientas se pueden ejecutar sin GUI y son útiles en entornos automatizados.

Prism, de Stoplight

Prism convierte un archivo OpenAPI 2/3 o una colección de Postman en un servidor mock.

Instalación típica:

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

Ejecuta un mock desde OpenAPI:

prism mock openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Por defecto, Prism escucha en:

http://127.0.0.1:4010
Enter fullscreen mode Exit fullscreen mode

Prism mock

Si tu especificación contiene examples, Prism los devolverá como respuesta.

Ejemplo mínimo de OpenAPI:

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          description: Lista de usuarios
          content:
            application/json:
              example:
                - id: 1
                  name: Ana
                  email: ana@example.com
Enter fullscreen mode Exit fullscreen mode

Arranca el mock:

prism mock openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Prueba el endpoint:

curl http://127.0.0.1:4010/users
Enter fullscreen mode Exit fullscreen mode

Para generar datos dinámicos desde el esquema:

prism mock -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Prism también soporta Faker mediante la extensión x-faker.

Úsalo cuando:

  • Tu contrato vive en un archivo OpenAPI.
  • Quieres un mock rápido desde CLI.
  • Prefieres un flujo spec-first.
  • No necesitas una GUI.

WireMock

WireMock es un servidor mock HTTP maduro basado en Java. Es especialmente útil cuando necesitas reglas de coincidencia avanzadas, escenarios con estado o grabación/reproducción de tráfico.

Ejecuta el jar independiente:

java -jar wiremock-standalone-3.x.x.jar --port 9099
Enter fullscreen mode Exit fullscreen mode

WireMock

Un stub básico se define con JSON.

Estructura típica:

.
└── mappings
    └── get-users.json
Enter fullscreen mode Exit fullscreen mode

Ejemplo de mappings/get-users.json:

{
  "request": {
    "method": "GET",
    "url": "/users"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": [
      {
        "id": 1,
        "name": "Ana",
        "email": "ana@example.com"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Arranca WireMock cargando los mappings:

java -jar wiremock-standalone-3.x.x.jar --port 9099
Enter fullscreen mode Exit fullscreen mode

Prueba:

curl http://localhost:9099/users
Enter fullscreen mode Exit fullscreen mode

WireMock destaca cuando necesitas:

  • Coincidencia por headers, query params o body.
  • Escenarios con estado.
  • Simular errores, delays y respuestas condicionales.
  • Grabar tráfico de un backend real.
  • Integración con stacks JVM.

Mockoon CLI

Mockoon combina una aplicación de escritorio con un CLI para ejecutar entornos sin interfaz.

El flujo habitual es:

  1. Diseñas el entorno en la GUI.
  2. Exportas el archivo de entorno.
  3. Lo ejecutas con el CLI en local, CI o Docker.

Comando básico:

mockoon-cli start --data ./environment.json --port 3000
Enter fullscreen mode Exit fullscreen mode

Mockoon CLI

Ejemplo en CI:

mockoon-cli start --data ./environment.json --port 3000 &
MOCK_PID=$!

npm test

kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

Mockoon también ofrece imagen Docker oficial y un comando dockerize para generar un Dockerfile autocontenido.

Úsalo cuando:

  • Prefieres diseñar rutas visualmente.
  • Quieres luego ejecutar el mock sin GUI.
  • Necesitas reglas de respuesta, plantillas o proxy.
  • Tu equipo trabaja mejor con configuración visual que con OpenAPI puro.

Servidor Mock de Apidog

Apidog es una plataforma API todo en uno. Su servidor mock se basa en el esquema por defecto: cuando defines o importas una API, Apidog puede generar respuestas simuladas sin configurar cada endpoint manualmente.

Su Smart Mock interpreta nombres y tipos de campos para generar datos más realistas. Por ejemplo, puede reconocer campos como:

  • email
  • avatar
  • username
  • phone
  • date
  • IP

En lugar de devolver siempre "string" o 0, genera valores más útiles para desarrollar y probar.

También puedes usar expresiones de Faker.js, por ejemplo:

{{$person.fullName}}
{{$number.int(min=1,max=100)}}
Enter fullscreen mode Exit fullscreen mode

Y puedes crear reglas personalizadas para condiciones específicas de la solicitud.

Apidog mock server

Para ejecución sin interfaz, Apidog ofrece dos opciones prácticas:

  1. Cloud Mock URL: una URL alojada como https://mock.apidog.com/..., accesible desde CI o por cualquier miembro del equipo.
  2. Mock local: un servidor local en 127.0.0.1, que también puede vincularse a la IP de intranet para compartirlo en la red.

La ventaja operativa es que el mock vive en el mismo proyecto donde están el diseño, la documentación y las pruebas. Así reduces el riesgo de mantener una configuración mock separada que se desactualiza.

Comparación rápida

Herramienta Fuente de verdad Ejecución sin interfaz Datos realistas Ideal para
Prism Archivo OpenAPI / Postman prism mock spec.yaml Modo dinámico -d + x-faker Simulación CLI spec-first
WireMock Reglas de stub / grabaciones Jar independiente Plantillas de respuesta Coincidencia compleja, JVM, grabación/reproducción
Mockoon CLI Entornos creados con GUI mockoon-cli start + Docker Ayudas de plantillas Diseño visual y despliegue sin interfaz
Apidog Esquema de API en el proyecto Cloud Mock URL + servidor local Smart Mock + Faker.js Mocks ligados a diseño, docs y pruebas

No hay un ganador universal:

  • Usa Prism si tu API está en un OpenAPI único y quieres CLI puro.
  • Usa WireMock si necesitas reglas avanzadas, estados o grabación.
  • Usa Mockoon CLI si prefieres diseñar visualmente y ejecutar sin GUI.
  • Usa Apidog si quieres mantener contrato, mock, documentación y pruebas en un mismo proyecto.

Para más opciones, consulta este resumen de las mejores herramientas de simulación de API.

Cómo ejecutar una simulación sin interfaz en CI

El patrón general es el mismo:

  1. Arrancar el mock.
  2. Esperar a que esté disponible.
  3. Ejecutar pruebas contra la URL mock.
  4. Detener el proceso.

Ejemplo con Prism:

# iniciar el mock en segundo plano
prism mock ./openapi.yaml &
MOCK_PID=$!

# ejecutar pruebas contra http://127.0.0.1:4010
npm test

# limpiar
kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

Un ejemplo más robusto puede esperar hasta que el mock responda:

prism mock ./openapi.yaml &
MOCK_PID=$!

until curl -s http://127.0.0.1:4010/users > /dev/null; do
  echo "Esperando al mock..."
  sleep 1
done

npm test

kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

Si usas Docker Compose, el patrón suele verse así:

services:
  mock-api:
    image: stoplight/prism:4
    command: mock -h 0.0.0.0 /tmp/openapi.yaml
    volumes:
      - ./openapi.yaml:/tmp/openapi.yaml
    ports:
      - "4010:4010"

  frontend:
    build: .
    environment:
      API_BASE_URL: http://mock-api:4010
    depends_on:
      - mock-api
Enter fullscreen mode Exit fullscreen mode

Tus pruebas frontend pueden leer la URL desde una variable de entorno:

API_BASE_URL=http://127.0.0.1:4010 npm test
Enter fullscreen mode Exit fullscreen mode

Ejemplo en JavaScript:

const API_BASE_URL = process.env.API_BASE_URL;

test("obtiene usuarios desde el mock", async () => {
  const response = await fetch(`${API_BASE_URL}/users`);
  const users = await response.json();

  expect(response.status).toBe(200);
  expect(Array.isArray(users)).toBe(true);
});
Enter fullscreen mode Exit fullscreen mode

Con Apidog, puedes evitar arrancar un proceso local si apuntas tus pruebas a la URL de Cloud Mock. Esto reduce piezas móviles en la pipeline:

API_BASE_URL=https://mock.apidog.com/your-project npm test
Enter fullscreen mode Exit fullscreen mode

Si prefieres un mock local, el flujo es similar: arrancas el servidor, ejecutas pruebas y lo detienes.

Ejecutar pruebas de API desde línea de comandos

El siguiente paso después de levantar un mock es probar contra él desde CI.

El CLI de Apidog, apidog-cli, también funciona sin interfaz. Con apidog run puedes ejecutar escenarios de prueba en CI, usar datos desde CSV o JSON y generar reportes en CLI, HTML o JSON.

Ejemplo conceptual:

apidog run
Enter fullscreen mode Exit fullscreen mode

Este flujo sirve para validar que tus escenarios funcionan contra:

  • Un backend real.
  • Un entorno de staging.
  • Una URL Cloud Mock.
  • Un mock local.

Puedes revisar el tutorial para probar una API REST desde la línea de comandos, la guía completa del CLI y la comparación Apidog CLI vs Postman CLI.

Simulaciones y agentes de codificación de IA

Si trabajas con Cursor, Claude o VS Code, un agente de IA puede generar mejor código si conoce el contrato real de la API.

El servidor Apidog MCP permite que un agente lea directamente tus especificaciones de API. Así puede generar código de cliente alineado con el mismo esquema que usa tu mock.

El flujo queda así:

Especificación API -> Mock -> Agente IA -> Código cliente
Enter fullscreen mode Exit fullscreen mode

Esto ayuda a evitar que el agente invente campos, rutas o formatos que no existen en el contrato.

Checklist para elegir una herramienta headless

Antes de integrar un mock en CI, valida estos puntos:

  • ¿La herramienta puede ejecutarse sin GUI?
  • ¿Tiene CLI, Docker o URL alojada?
  • ¿Puede cargarse desde OpenAPI si trabajas contract-first?
  • ¿Permite datos dinámicos o realistas?
  • ¿Soporta respuestas de error y casos límite?
  • ¿Es fácil apuntar tus tests con API_BASE_URL?
  • ¿El mock se mantiene sincronizado con el contrato?
  • ¿Puede ejecutarse igual en local y CI?

Si la respuesta es “no” en varios puntos, probablemente tu mock será útil para demos locales, pero frágil para automatización.

Preguntas frecuentes

¿Una simulación sin interfaz es lo mismo que un servidor mock?

Sí, con una precisión. Un servidor mock responde con datos falsos. “Sin interfaz” indica que se ejecuta sin GUI: mediante CLI, Docker o una URL alojada. Por eso puede usarse en CI, scripts y entornos automatizados.

¿Puedo generar una simulación sin interfaz desde OpenAPI?

Sí. Prism lee archivos OpenAPI directamente. Apidog también genera mocks desde el esquema de API en tu proyecto. Este enfoque reduce mantenimiento manual porque el mock se deriva del contrato. Para ver el flujo completo, consulta la guía de simulación de API.

¿Cómo devuelven datos realistas en lugar de placeholders?

Depende de la herramienta. Prism puede usar modo dinámico y x-faker. Apidog usa Smart Mock para asociar campos como email, phone o username con valores realistas, y permite expresiones de Faker.js para mayor control. Sin un motor de datos, muchos mocks terminan devolviendo cadenas vacías, ceros o ejemplos demasiado estáticos.

¿Necesito ejecutar un servidor local?

No siempre. WireMock, Prism y Mockoon CLI ejecutan un proceso que tú gestionas. Apidog añade una URL Cloud Mock alojada que puede usarse desde CI o por el equipo sin levantar nada localmente.

¿Qué herramienta conviene para CI?

Depende de tu fuente de verdad:

  • Si tienes OpenAPI: Prism o Apidog.
  • Si necesitas reglas complejas: WireMock.
  • Si quieres diseñar con GUI y ejecutar en CLI: Mockoon.
  • Si quieres unir diseño, docs, mock y pruebas: Apidog.

Conclusión

Una simulación de API sin interfaz convierte un mock local en una pieza automatizable de tu pipeline. Prism, WireMock y Mockoon CLI resuelven bien este problema desde enfoques distintos: especificación, stubs avanzados o diseño visual.

Si quieres que el mock permanezca ligado al diseño, la documentación y las pruebas de tu API, Apidog mantiene todo dentro del mismo proyecto. Puedes usar un mock local o una URL alojada y apuntar tus pruebas directamente a esa simulación. Descarga Apidog para crear un mock desde tu especificación y conectarlo a tu flujo de CI.

Top comments (0)