Cómo Devolver Datos Mock Condicionales en Apidog (Reglas Personalizadas y Scripts Mock)

Smart mock te proporciona una API falsa en segundos. Lee el esquema de tu endpoint y devuelve datos plausibles: un correo electrónico de aspecto real, una marca de tiempo sensata y un nombre que no es xJ8kQ. Para la mayoría de las tareas de frontend, esto basta para desbloquearte.

Prueba Apidog hoy

El límite aparece cuando necesitas que la respuesta dependa de la solicitud. Por ejemplo: POST /login debe devolver 200 para un usuario conocido y 401 para el resto; /orders/{id} debe devolver pedidos con estados distintos según el ID; o necesitas provocar un 500 para probar el manejo de errores antes de producción. Smart mock devuelve una única forma por endpoint, así que no puede ramificarse según la solicitud.

Apidog cubre este caso con dos mecanismos:

1. Expectativas de mock: respuestas condicionales basadas en reglas.
2. Scripts de mock: lógica JavaScript para casos que las reglas no pueden expresar.

En este tutorial configurarás ambos enfoques, verás su orden de prioridad y aprenderás cuándo usar cada uno. Si necesitas contexto previo, consulta la descripción general de mocking de API. Apidog será la herramienta utilizada durante el proceso. La OpenAPI Initiative documenta el enfoque contract-first que hace posible este flujo de trabajo.

Qué significa el mocking condicional

Un mock condicional aplica una regla:

Cuando la solicitud entrante coincide con estas condiciones, devuelve esta respuesta.

En Apidog puedes construir mocks en dos capas.

1. Personalización de campos del esquema

Puedes fijar valores estáticos o usar una expresión dinámica de Faker.js para generar datos en cada llamada.

Esto controla el contenido de un campo, pero sigue devolviendo una única forma de respuesta por endpoint.

2. Expectativas de mock

Una expectativa es una regla nombrada que puede incluir:

• Condiciones sobre la solicitud.
• Código de estado HTTP.
• Encabezados de respuesta.
• Cuerpo de respuesta.
• Retraso artificial.

Una expectativa sin condiciones funciona como comodín. Una expectativa con condiciones solo responde cuando la solicitud coincide.

Puedes combinar varias expectativas para implementar ramificaciones reales:

• Respuesta 200 si un cuerpo contiene un usuario conocido.
• Respuesta 401 si no coincide.
• Cuerpo distinto según un parámetro de ruta.
• Error 500 si el cliente envía un encabezado específico.

Valores dinámicos a nivel de campo

Antes de crear ramificaciones, configura valores dinámicos en tu esquema. Cualquier campo de tipo cadena puede usar expresiones de Faker.js con esta sintaxis:

{{$category.method}}

Por ejemplo:

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

Los métodos pueden recibir parámetros:

• {{$number.int(min=1000,max=9999)}} limita el rango de números.
• {{$date.between(...)}} controla fechas y formato.
• Puedes concatenar texto estático y varias expresiones en un mismo campo.

Apidog también admite localizaciones de mock personalizables para adaptar nombres, direcciones y teléfonos a un idioma o país. Consulta la referencia de Faker.js en Apidog para ver los métodos disponibles.

Esto sigue siendo territorio de Smart mock: los datos cambian, pero la respuesta no depende de la solicitud. Para eso necesitas expectativas.

Tutorial: POST /login con respuesta 200 o 401

El objetivo es implementar este comportamiento:

• POST /login recibe username y password.
• Si username es [e-mail], devuelve 200 y un token.
• Para cualquier otro usuario, devuelve 401.

1. Abre la pestaña de mock

La ubicación depende del modo de trabajo:

• En modo DEBUG (Request-first), abre el endpoint y selecciona la pestaña Mock.

• En modo DESIGN (Design-first), abre el endpoint y selecciona Advanced mock.

Ambas opciones llevan a la lista de expectativas. Si todavía no tienes el endpoint, descarga Apidog y crea o importa primero POST /login.

2. Crea la expectativa de éxito

Haz clic en Nueva expectativa y configura lo siguiente:

Campo	Valor
Nombre de expectativa	login-success
Ubicación de la condición	Parámetro de cuerpo
Nombre o ruta JSON	username
Operador	Igual a
Valor	[e-mail]

Como username está dentro de un cuerpo JSON, debes usar una condición de parámetro de cuerpo. Para propiedades anidadas utiliza rutas con punto, por ejemplo user.email.

En Datos de respuesta, añade el cuerpo de éxito:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

Guarda la expectativa. El código de estado predeterminado es 200, así que no necesitas modificarlo.

3. Crea la expectativa de fallo

Haz clic de nuevo en Nueva expectativa.

Campo	Valor
Nombre de expectativa	login-failure
Condiciones	Déjalas vacías
Código de estado HTTP	401

Dejar las condiciones vacías convierte esta expectativa en una regla comodín.

Usa este cuerpo de respuesta:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Después, abre la pestaña Más y establece el Código de estado HTTP en 401.

Desde la misma pestaña puedes configurar:

• Retraso de respuesta en milisegundos.
• Encabezados de respuesta personalizados.
• Códigos de estado HTTP distintos.

Por ejemplo, un retraso de 400 ms ayuda a comprobar que el estado de carga de tu interfaz se renderiza correctamente.

4. Ordena las expectativas

Las expectativas se evalúan de arriba hacia abajo. La primera coincidencia gana.

El orden correcto es:

1. login-success
2. login-failure

Así:

• [e-mail] coincide con login-success y recibe 200.
• Cualquier otro valor cae en login-failure y recibe 401.

Si colocas primero la regla sin condiciones, coincidirá con todas las solicitudes y la expectativa de éxito nunca se ejecutará.

Prueba ambas rutas usando la URL de mock de tu endpoint:

# Usuario conocido -> 200 con token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# Cualquier otro usuario -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

Tutorial: respuestas diferentes para /orders/{id}

Ahora crea un endpoint que devuelva un pedido enviado o cancelado según el parámetro de ruta id.

Crea una expectativa por estado.

Pedido enviado

Configura una expectativa llamada order-shipped:

Campo	Valor
Tipo de condición	Parámetro de ruta
Nombre	id
Operador	Igual a
Valor	5001

Usa este cuerpo:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.9,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Pedido cancelado

Configura una expectativa llamada order-cancelled:

Campo	Valor
Tipo de condición	Parámetro de ruta
Nombre	id
Operador	Igual a
Valor	5002

Usa este cuerpo:

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Añade un fallback

Crea una tercera expectativa sin condiciones para devolver un pedido pendiente genérico. Esto evita que IDs no contemplados fallen sin respuesta.

Orden recomendado:

1. order-shipped
2. order-cancelled
3. Expectativa comodín de pedido pendiente

Puedes combinar condiciones. Por ejemplo, una regla puede requerir:

• id = 5001
• Encabezado X-Client-Type = mobile

En ese caso, ambas condiciones deben cumplirse. Apidog las combina con lógica AND.

Además del cuerpo y la ruta, las condiciones pueden evaluar:

• Parámetros de consulta.
• Encabezados.
• Cookies.
• Direcciones IP.

Fuerza errores bajo demanda

No necesitas romper un backend para probar la interfaz frente a respuestas de error.

Por ejemplo, fuerza un 500 usando un encabezado que controles desde el cliente:

Campo	Valor
Tipo de condición	Encabezado
Nombre	X-Mock-Scenario
Valor	server-error
Código de estado HTTP	500

Usa este cuerpo:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Con esta regla:

• La respuesta normal del endpoint sigue devolviendo 200.
• El endpoint devuelve 500 cuando envías X-Mock-Scenario: server-error.

Puedes aplicar el mismo patrón para probar:

• 404 cuando un recurso no existe.
• 429 junto con un encabezado Retry-After.
• 503 para simular mantenimiento o indisponibilidad.
• Retrasos para validar timeouts, spinners y reintentos.

Si quieres validar estas respuestas con pruebas automatizadas, consulta la guía de aserciones de API.

En proyectos compartidos, cada expectativa puede activarse o desactivarse de forma independiente para mock local y mock en la nube. Por ejemplo, puedes mantener activa una regla de 500 en local y desactivarla en el entorno cloud que utiliza el resto del equipo.

Cuando las reglas no bastan: scripts de mock

Las expectativas son declarativas: comprueban condiciones y devuelven una respuesta. No pueden calcular valores complejos.

Usa un script de mock cuando necesites:

• Sumar importes de elementos enviados por el cliente.
• Derivar campos a partir del cuerpo de la solicitud.
• Aplicar lógica basada en varias entradas.
• Construir una respuesta cuya estructura dependa de cálculos.

El script de mock es JavaScript y se configura en la sección Mock Script, situada al final de la pestaña Mock.

Dispone de dos variables globales:

• $$.mockRequest: permite leer la solicitud entrante mediante getParam(key), headers, cookies, body, formdata y urlencoded.
• $$.mockResponse: permite modificar la respuesta mediante setBody(), setCode(), setDelay(), json(), headers y code.

Este ejemplo calcula el total de un pedido enviado en el cuerpo y respeta la moneda indicada por el cliente:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

El flujo de ejecución es:

1. Smart mock genera una respuesta inicial.
2. El script lee $$.mockRequest y la respuesta actual.
3. El script aplica su lógica.
4. El script usa setBody(), setCode(), setDelay() o encabezados.
5. Apidog devuelve la respuesta final.

La referencia de JavaScript de MDN es útil si necesitas ampliar esta lógica con métodos de arrays o cálculos de fechas.

Regla importante: scripts y expectativas no se combinan

Los scripts de mock solo funcionan con Smart mock.

No se aplican a:

• Expectativas de mock.
• Ejemplos de respuesta.

Si una expectativa coincide, el script no se ejecuta.

Elige un enfoque por endpoint:

Necesidad	Enfoque recomendado
Respuestas fijas según condiciones	Expectativas de mock
Cálculos a partir de la solicitud	Script de mock con Smart mock
Datos aleatorios basados en el esquema	Smart mock
Errores activados por un encabezado o parámetro	Expectativas de mock

Orden de prioridad de las respuestas

Apidog resuelve una solicitud de mock en este orden:

1. Evalúa las expectativas de arriba hacia abajo. La primera cuyas condiciones coincidan por completo gana.
2. Si ninguna expectativa coincide, utiliza la Prioridad del método de mock configurada en: Configuración del proyecto → Configuración de características → Configuración de mock.
3. En ese nivel, Smart mock genera la respuesta. Los scripts de mock solo se ejecutan en esta ruta.

El modelo mental es simple:

Primero reglas específicas; después datos generados.

Ordena tus expectativas de la más específica a la más general y deja la regla comodín al final cuando quieras garantizar una respuesta.

Para profundizar en qué mecanismo conviene usar en cada caso, consulta los casos de uso de mocking de API.

Errores comunes antes de implementar

Ten en cuenta estas limitaciones para evitar sesiones de depuración innecesarias:

• Las condiciones de parámetros no admiten {{variables}}. Las variables de proyecto y entorno de Apidog no están disponibles dentro de las expectativas de mock.
• Las condiciones de parámetros de cuerpo solo admiten JSON, no XML.
• Para cuerpos JSON, usa la ruta JSON en el campo de nombre, por ejemplo user.email.
• El formato de la condición debe coincidir con la especificación de la API. Si el endpoint usa form-data, configura la condición como form-data, no como JSON.
• Los scripts de mock no disponen de función de registro.
• El objeto pm no está disponible en scripts de mock, ya que no se ejecutan en el mismo entorno que los scripts de prueba.
• Los scripts de mock no pueden usar variables de Apidog; mantén su lógica autocontenida.

La documentación no indica restricciones de plan para estas características. La diferencia entre local y nube es funcional: puedes activar o desactivar expectativas por entorno.

Automatiza el flujo con la CLI de Apidog

El mock de Apidog se configura desde la interfaz y se sirve desde URLs de mock locales o en la nube. No existe un comando CLI para levantar un servidor de mock en ejecución.

La CLI de Apidog sí permite controlar los recursos sobre los que se construyen los mocks.

Las respuestas se generan a partir del esquema del endpoint. Por eso, la precisión del mock depende de la precisión de tu especificación.

Puedes usar la CLI y agentes de codificación de IA compatibles, como Cursor, Claude Code, Trae o Codex, para crear y actualizar endpoints y esquemas en tu proyecto. Actualiza el contrato, sincronízalo y el mock seguirá reflejando el cambio sin tener que reconfigurarlo manualmente.

Cuando el mock haya desbloqueado el trabajo de frontend, ejecuta escenarios de prueba en CI para validar el backend real contra el mismo contrato:

apidog run -t <scenario_id> -e <env_id> -r cli

Este comando ejecuta los escenarios e informa los resultados. Así, mock y validación comparten una única fuente de verdad.

Consulta la guía de instalación de la CLI de Apidog y el tutorial de la CLI de Apidog en GitHub Actions para integrarlo en tu pipeline.

Preguntas frecuentes

¿Por qué mi expectativa se ignora si la condición parece correcta?

Normalmente es un problema de orden o de formato.

Las expectativas se evalúan de arriba hacia abajo. Una regla general sin condiciones situada antes que una regla específica capturará todas las solicitudes.

Comprueba también que el formato coincida con la especificación:

• Ruta JSON para cuerpos JSON.
• Ubicación form-data para endpoints de formulario.

Consulta la descripción general de mocking de API si necesitas revisar la configuración básica.

¿Puedo usar un script de mock y una expectativa en la misma respuesta?

No. Los scripts de mock solo funcionan con Smart mock. Las expectativas y los ejemplos de respuesta los ignoran.

Si una expectativa coincide, el script no se ejecuta.

¿Cómo devuelvo un 401 o 500 sin romper el 200 por defecto?

Crea una expectativa específica con una condición controlable desde el cliente, como un encabezado. Después, abre la pestaña Más y establece el código de estado HTTP.

La respuesta predeterminada seguirá devolviendo 200; el error solo se activará cuando se cumpla la condición.

¿Las condiciones pueden usar variables de entorno?

No. Los valores {{variable}} de Apidog no están disponibles dentro de las expectativas de mock.

Usa valores literales para las condiciones.

¿Qué ocurre si ninguna expectativa coincide?

Apidog utiliza la Prioridad del método de mock configurada en:

Configuración del proyecto
→ Configuración de características
→ Configuración de mock

En esa ruta, Smart mock genera una respuesta a partir de tu esquema.

Si quieres garantizar una alternativa específica, añade una expectativa final sin condiciones.

Conclusión

Smart mock cubre el caso común: generar datos realistas a partir de tu esquema. Las expectativas de mock cubren los casos que incluyen un “si”:

• 200 para un usuario conocido y 401 para el resto.
• Pedidos distintos según su ID.
• Un 500 activado bajo demanda.
• Respuestas diferentes según encabezados, cookies o parámetros.

Usa scripts de mock solo cuando necesites una salida calculada que las reglas no puedan expresar. Recuerda que los scripts se ejecutan únicamente con Smart mock.

Ordena las expectativas desde la más específica hasta la más general, deja los comodines al final y tus mocks se comportarán como una API real. Descarga Apidog para crear tu primer mock condicional.