Mocking y pruebas de API autohospedados en un VPS
Ejecuta WireMock y Hurl en tu VPS: stubs versionados en Git, suites en CI y reportes persistentes incluso tras reconstruir el servidor.
Dos trabajos que comparten un repositorio
Alojar internamente el mock de una API y ejecutar pruebas son dos trabajos distintos. Tratarlos como uno solo puede hacer perder una semana. Un servidor mock sustituye una dependencia a la que no puede llamar desde CI: un proveedor de pagos, una API de un socio, un servicio upstream con límites de tasa o un servicio que otro equipo todavía no ha publicado. Un ejecutor de pruebas de API llama a sus propios endpoints en un orden fijo y comprueba las respuestas. También transfiere valores de una respuesta a la siguiente solicitud.
Algunas herramientas realizan ambos trabajos. La función principal de un servidor mock es responder a las solicitudes. Un ejecutor de pruebas no determina qué devuelve un proveedor de pagos cuando se rechaza una tarjeta. La mayoría de los equipos que ya alquilan un servidor terminan ejecutando uno de cada tipo. Ambos se inician con el mismo archivo de Docker Compose y se revisan en la misma solicitud de incorporación de cambios.
¿Por qué alojar uno mismo el mocking y las pruebas de API?
Tus fixtures tienen la estructura de los datos de producción. El cuerpo de una petición en una prueba de API puede ser un registro real de un cliente con el nombre cambiado, o con el nombre sin cambiar porque nadie lo comprobó. Los stubs grabados son peores: la grabación mediante proxy almacena lo que devolvió realmente el upstream, por lo que un directorio de stubs creado mediante grabación contiene tokens activos y direcciones de correo de clientes hasta que alguien lee todos los archivos. En un servicio alojado, esos datos se convierten en un incidente de otra entidad y en una divulgación de información por tu parte.
La segunda razón es la accesibilidad de red. Un servicio enlazado a una dirección privada necesita una conexión de red privada para que un runner alojado pueda acceder a él. Cada solución alternativa tiene un coste. Publicar la API en Internet para probarla elimina el motivo por el que era privada. Un túnel o una copia pública de staging es otro sistema que mantener, y una copia de staging se desincroniza de producción entre versiones. Los runners alojados por GitHub también admiten acceso privado mediante una red superpuesta WireGuard o una Azure Virtual Network. Un runner en la misma red privada llama directamente al servicio y no necesita nada de eso. Este es el argumento práctico a favor de un runner de GitHub Actions autohospedado.
¿Qué servidor mock autoalojado debe ejecutar?
Cada uno se ejecuta como un contenedor en un equipo que administra. La cuestión importante es qué considera cada uno como fuente de verdad, porque eso determina si reconstruir el contenedor no cuesta nada o le lleva toda una tarde.
- WireMock guarda cada stub como un archivo JSON en un directorio
mappings/, y almacena los cuerpos de respuesta grandes en__files/. La imagen eswiremock/wiremock, su directorio raíz dentro del contenedor es/home/wiremocky también funciona como proxy de grabación. Los archivos en disco permiten mantener el mock en git como cualquier otro código. - Mockoon CLI guarda una API mock completa en un único archivo de datos JSON. Instálelo con
npm install -g @mockoon/clie inícielo conmockoon-cli start --data ./data-file.json, o ejecute la imagenmockoon/clicon ese archivo montado mediante un bind mount. La aplicación de escritorio edita el mismo archivo, por lo que diseñar en una interfaz gráfica y confirmar el resultado en git siguen siendo compatibles. - MockServer se ejecuta desde la imagen
mockserver/mockservery escucha en el puerto 1080. Las expectativas llegan mediante su propia API REST, lo que resulta práctico desde el código de pruebas, pero introduce riesgos en un despliegue: de forma predeterminada, una expectativa creada mediante una llamada HTTP desaparece cuando se reinicia el contenedor. Use su archivo de inicialización JSON para los stubs que deban ser permanentes. Para conservar los cambios realizados durante la ejecución, habilitepersistExpectations, almacene el archivo de salida fuera del contenedor y cárguelo medianteinitializationJsonPathdurante el arranque. - Prism crea el mock a partir del documento OpenAPI, en lugar de usar archivos de stubs independientes. Instálelo con
npm install -g @stoplight/prism-cliy ejecútelo conprism mock openapi.yaml. Dentro de un contenedor, añada-h 0.0.0.0, porque Prism se vincula a localhost de forma predeterminada y, de lo contrario, no será accesible desde fuera del contenedor. - Microcks es la opción más completa: ofrece una interfaz web que importa documentos OpenAPI y colecciones de Postman, los sirve como mocks y ejecuta pruebas de contrato. Una instalación completa necesita MongoDB y Keycloak, además de Kafka para sus funciones asíncronas. La imagen
microcks-ubertodo en uno incluye un MongoDB en memoria, que el proyecto documenta como adecuado para uso efímero. Por tanto, trate como desechable todo lo que cree en esa interfaz y conserve los artefactos de origen en git.
¿Qué ejecutor de pruebas de API autoalojado debe ejecutar?
El trabajo consiste en una secuencia: autenticarse, crear un pedido, leerlo de nuevo y comprobar que el estado haya cambiado. Para ello, debe capturar un valor de una respuesta y usarlo en la siguiente solicitud. Una herramienta que no puede conservar el estado entre llamadas sirve para comprobar el estado del servicio, no para probar una API.
- Hurl ejecuta archivos de texto sin formato con solicitudes HTTP desde un único binario. Una sección
[Captures]extrae valores de una respuesta, una sección[Asserts]los comprueba y--testlo convierte en un ejecutor de pruebas con un resumen y un código de salida. La versión 8.0.1 es la actual en agosto de 2026. - Bruno CLI ejecuta una carpeta de archivos
.bru. Instálelo connpm install -g @usebruno/cliy ejecútelo conbru run folder --env Local --reporter-junit results.xml. El formato de la colección consiste deliberadamente en archivos de texto dentro de un directorio, por lo que las diferencias son fáciles de revisar. - Newman ejecuta colecciones de Postman fuera de Postman:
npm install -g newmany despuésnewman run collection.json -r cli,junit --reporter-junit-export results.xml. El inconveniente es el formato. Newman ejecuta colecciones exportadas en formato JSON v2.1. Postman también admite ahora un formato de colección v3 y flujos de trabajo Native Git mediante Postman CLI. La documentación de Postman indica que Newman no recibirá más actualizaciones ni correcciones, y recomienda migrar los scripts y las canalizaciones de CI a Postman CLI. - Schemathesis realiza un tipo de comprobación diferente. Lee un esquema OpenAPI y genera casos que intentan producir respuestas que el esquema indica que son imposibles:
uvx schemathesis run https://your.api/openapi.json. Detecta bloqueos y violaciones del contrato, pero no conoce las reglas de negocio. Por tanto, complementa una suite con scripts en lugar de sustituirla. - Hoppscotch autoalojado es la opción con interfaz web y requiere una instancia de Postgres. Tenga en cuenta esa decisión antes de instalarlo: las colecciones se almacenan en una base de datos, no en el repositorio.
Hay una opción que debe evitar. Step CI todavía aparece en comparativas de herramientas y su formato de flujo de trabajo YAML es fácil de leer, pero el repositorio recibió su último commit en agosto de 2024. Un programa situado entre su CI y su API es un punto inadecuado para usar código sin mantenimiento.
Coloque el servidor simulado detrás del firewall
La configuración siguiente ejecuta WireMock como sustituto de un proveedor de pagos. Si no conoce el formato del archivo de Compose, Docker Compose en un VPS explica los comandos del ciclo de vida que se usan en esta sección.
services:
mock-payments:
image: wiremock/wiremock:3.13.2
command: ["--verbose"]
volumes:
- ./mocks/payments:/home/wiremock
ports:
- "127.0.0.1:8080:8080"
restart: unless-stoppedEl prefijo 127.0.0.1: del puerto es la parte importante. Un 8080:8080 sin prefijo publica el servidor simulado en todas las interfaces, incluida la IP pública, y sigue siendo accesible aunque ufw bloquee ese puerto, porque Docker dirige el tráfico publicado a través de la tabla nat antes de que llegue a las reglas INPUT de ufw. Enlace el puerto a la dirección de loopback para que sólo sea accesible desde el host con la red bridge predeterminada de Docker en Engine 28.0.0 o posterior. Las versiones anteriores permiten que los hosts de la misma red de capa 2 accedan a los puertos publicados en localhost. Enlazarlo a la dirección de una interfaz privada también permite el acceso desde las redes que puedan enrutar hacia esa dirección.
A continuación, el servicio que se está probando apunta al servidor simulado. Cuando el servicio se ejecuta en el mismo proyecto de Compose, la URL base del servidor simulado es http://mock-payments:8080, porque Compose resuelve los nombres de servicio en su propia red. Cuando el servicio se ejecuta en el host, es http://127.0.0.1:8080. Configure este valor mediante una variable de entorno, nunca en el código, o la URL de prueba se incorporará a producción.
Los stubs se guardan en ./mocks/payments/mappings/, un archivo JSON por cada uno.
{
"request": {
"method": "POST",
"urlPath": "/v1/charges",
"bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
},
"response": {
"status": 201,
"headers": { "Content-Type": "application/json" },
"jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
}
}Inícielo y compruebe qué se cargó realmente.
docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings--wait espera hasta que el contenedor informa de que está saludable. Esto funciona porque la imagen de WireMock incluye un HEALTHCHECK para su endpoint /__admin/health. La llamada mappings muestra todos los stubs que el servidor leyó. Si un stub que escribió no aparece en esa lista, nunca se cargó: compruebe que el archivo esté en mappings/ y no en la raíz montada, y compruebe que el JSON se pueda analizar.
Cuando llega una petición y ningún stub coincide, WireMock responde 404. Si encuentra una coincidencia aproximada, el cuerpo comienza con Request was not matched, seguido de una diferencia respecto al stub más cercano. Si no hay mappings de stubs, el cuerpo es No response could be served as there are no stub mappings in this WireMock instance. Lea la diferencia cuando esté presente antes de cambiar nada, porque indica el campo exacto que difiere. Normalmente es una ruta con /v1/charge donde el stub indica /v1/charges.
Escriba la prueba como una secuencia con estado entre las llamadas
Los archivos de Hurl son texto sin formato. Instale el paquete deb desde las versiones publicadas del proyecto.
VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.debUna suite que prueba su propia API contra el mock se encuentra en tests/checkout.hurl.
POST {{base_url}}/orders
Content-Type: application/json
{
"sku": "ssd-1tb",
"amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"
GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"El bloque [Captures] es lo que convierte esto en una prueba de API y no en dos solicitudes independientes. order_id se lee de la primera respuesta y se interpola en la URL de la segunda. La aserción sobre charge_id es el objetivo de todo el ejercicio: demuestra que el servicio llamó al proveedor de pagos y almacenó la respuesta recibida, y el valor con el que se compara es el que escribió en el stub de WireMock. Ahora un solo archivo cubre las dos partes del flujo.
hurl --test --variable base_url=http://127.0.0.1:3000 \
--report-junit reports/junit.xml \
--report-json reports/json \
tests/Una ejecución correcta muestra una línea por archivo y un resumen.
tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files: 1
Executed requests: 2 (30.1/s)
Succeeded files: 1 (100.0%)
Failed files: 0 (0.0%)
Duration: 64 msUna ejecución fallida muestra error: Assert failure con el archivo y el número de línea, seguido del valor obtenido y el valor esperado. Después, hurl termina con un código distinto de cero para que CI se detenga. Si status lee pending cuando esperaba paid, el servicio no procesó la respuesta del mock. Lo siguiente que debe revisar es el registro de solicitudes de WireMock en /__admin/requests, que muestra si la llamada llegó al mock.
Ejecutar la suite desde su propio runner de CI
Con un runner registrado en el mismo equipo, el flujo es breve. El runner es un proceso normal del host, por lo que docker y hurl deben estar instalados en ese host. No hereda nada de una imagen alojada.
name: api-tests
on: [push]
jobs:
hurl:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Start the mock
run: docker compose up -d --wait mock-payments
- name: Run the suite
run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
- name: Archive the reports
if: always()
run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
- name: Stop the mock
if: always()
run: docker compose downif: always() en el paso de archivado es importante. Sin esta opción, una ejecución de pruebas fallida omite la copia y se pierde exactamente el informe que se quería consultar. La copia también debe quedar fuera del workspace, porque actions/checkout@v4 ejecuta git clean -ffdx de forma predeterminada antes de obtener los cambios. Esto elimina los informes sin seguimiento del directorio del repositorio en la siguiente extracción.
Conserve los resultados, no sólo los de la última ejecución
Un archivo XML de JUnit por commit responde a una pregunta: si la ejecución pasó. No indica cuándo un endpoint empezó a responder más despacio, porque nadie lee esos archivos después de dejar de abrirlos. Para obtener una tendencia, añada una fila por ejecución a una base de datos pequeña en el mismo equipo. Basta con una tabla que contenga el SHA del commit, el nombre del archivo, el número de pruebas correctas, el número de pruebas fallidas y la duración. SQLite en producción en un VPS es un lugar razonable para almacenarla: un solo archivo, sin un proceso de servidor, y todo el historial queda incluido en la copia de seguridad que ya realiza. Analice la salida --report-json de Hurl para obtener datos detallados de la ejecución; tanto JSON como XML de JUnit son legibles por máquina.
Qué debe sobrevivir a la reconstrucción de un contenedor
Las definiciones de mocks y las suites de pruebas son código fuente. Deben estar en un repositorio junto al servicio que describen y cambiar en la misma pull request que modifica un endpoint. Un stub editado en una interfaz web o una expectativa enviada a MockServer mediante su API REST durante la ejecución necesita una configuración de exportación o persistencia para sobrevivir a una reconstrucción. Ejecute docker compose down y la memoria del contenedor y las capas escribibles se perderán; los datos almacenados en bind mounts o named volumes sobreviven. Si sus repositorios también se ejecutan en hardware propio, un servidor git autohospedado mantiene los fixtures y el servicio dentro del mismo límite de confianza.
Estas son las reglas prácticas. Fije las etiquetas de imagen, porque latest puede cambiar la forma en que el mock compara las solicitudes sin que cambie nada en su repositorio, y es muy difícil relacionar ese fallo con su causa. Monte los directorios de stubs como de solo lectura cuando la herramienta no necesite escribir en ellos. Nunca coloque los stubs de un mock en un named Docker volume, porque el volumen se convierte entonces en la fuente de verdad y la copia de git queda desactualizada sin que nadie lo advierta.
Hay otra regla que suele causar problemas. Si crea stubs grabando tráfico real a través de un proxy, lea todos los archivos generados antes de confirmarlos. Una grabación contiene exactamente lo que devolvió el upstream, incluidos los bearer tokens y las direcciones de correo electrónico de clientes. Al confirmarla, esos datos quedan permanentemente en el repositorio, porque git conserva el contenido eliminado en el historial.
FAQ
¿Cuál es la diferencia entre un servidor mock de API y un ejecutor de pruebas de API?
Un servidor mock responde a las peticiones. Sustituye una dependencia que no puede invocar desde CI; algunas herramientas también ejecutan pruebas de contrato e informan de sus resultados. Un ejecutor de pruebas de API envía peticiones a su propio servicio, comprueba las respuestas, transfiere valores de una llamada a la siguiente y termina con un código distinto de cero cuando falla una comprobación. Resuelven problemas distintos y una configuración habitual ejecuta ambos al mismo tiempo: el ejecutor llama a su servicio y su servicio llama al mock.
¿Puedo probar una API interna desde un ejecutor de CI alojado?
Sí, mediante una red privada. Los ejecutores alojados por GitHub admiten una superposición WireGuard o una Azure Virtual Network para acceder a recursos privados sin publicar la API. Publicar la API, ejecutar un túnel o mantener una copia pública de staging son otras opciones, y cada una añade un sistema que puede fallar o filtrar información. Un ejecutor en la misma red privada llama directamente al servicio. Esta es la principal razón práctica por la que los equipos alojan esta tarea por su cuenta.
¿Dónde deben residir los stubs de mock y las suites de pruebas de API?
En git, junto al servicio que describen. Las herramientas que almacenan las definiciones como archivos, como el directorio mappings/ de WireMock, el archivo de datos de Mockoon, los archivos de Hurl y la carpeta .bru de Bruno, permiten revisar el código y reconstruir un contenedor sin coste adicional. Las herramientas que almacenan las definiciones en una base de datos o en una interfaz web necesitan un plan de copias de seguridad y un paso de exportación. La exportación es precisamente la parte que se olvida hasta que el contenedor ya ha desaparecido.
¿Por qué mi mock devuelve 404 cuando el stub parece correcto?
WireMock sirve un stub sólo cuando la petición cumple sus matchers configurados. Una petición sin coincidencias recibe 404; cuando existe una coincidencia aproximada, el cuerpo comienza con Request was not matched, seguido de una diferencia con respecto al stub más cercano. Esa diferencia indica el campo que no coincide. Si no hay mappings de stubs, el cuerpo explica en su lugar que la instancia no tiene ninguno. Las causas habituales son una barra final en la ruta, una cabecera Content-Type que requiere el stub pero que el cliente no envió, urlPath usado cuando el stub necesita urlPathPattern para un segmento variable y un matcher del cuerpo que no se ajusta a la carga útil. Compruebe primero /__admin/requests para confirmar que la petición llegó al mock.
¿Sigo necesitando mocks si tengo un entorno de staging?
Sí, por dos razones. Una copia de staging de un upstream que no controla puede dejar de estar disponible y seguir aplicando límites de tasa. Por tanto, la suite falla por motivos que no tienen relación con su código. Además, no puede generar las respuestas que más necesita probar, como una tarjeta rechazada o un timeout del gateway. Un mock devuelve esas respuestas bajo demanda y a la velocidad de la red local. Así, una suite que tarda minutos contra un sandbox puede tardar segundos. Mantenga staging para la comprobación final antes de una release y use mocks en CI.