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, un nombre que no es xJ8kQ. Para la mayoría de los trabajos de frontend, eso es suficiente para desbloquearte.

Luego te encuentras con un caso que Smart mock no puede resolver. Quieres que /login devuelva 200 para un usuario conocido y 401 en caso contrario. Quieres que /orders/{id} devuelva un pedido enviado para un ID y uno cancelado para otro. Quieres forzar un 500 bajo demanda para que tu manejo de errores se ejercite antes de que llegue a producción. Smart mock devuelve una única forma por endpoint, por lo que no puede ramificarse según la solicitud. Esa es la brecha que cierra esta guía.

Apidog lo cubre con dos características: expectativas de mock para respuestas condicionales basadas en reglas, y scripts de mock para lógica que las reglas no pueden expresar. Este tutorial muestra ambos con ejemplos concretos y explica el orden de prioridad para que tus reglas personalizadas superen a Smart mock en todo momento. Si eres nuevo en los conceptos básicos, la descripción general de mocking de API es un buen calentamiento, y Apidog es la herramienta que usaremos a lo largo. La OpenAPI Initiative documenta el flujo de trabajo "contract-first" que hace todo esto posible.

botón

Qué significa realmente el mocking condicional

Un mock condicional es una regla: cuando la solicitud entrante se parece a esto, devuelve aquello. Apidog construye estas reglas a partir de dos capas.

La primera capa es la personalización a nivel de campo dentro del esquema del endpoint. Fijar un campo a un valor fijo, o adjuntar una expresión dinámica de Faker.js para que varíe en cada llamada. Esto controla qué contiene un campo, pero aún devuelve una única forma de respuesta para el endpoint.

La segunda capa es la expectativa de mock de respuesta completa. Una expectativa es una regla nombrada con condiciones opcionales y su propio cuerpo de respuesta, código de estado y encabezados. Una expectativa sin condiciones devuelve datos fijos incondicionalmente. Una expectativa con condiciones devuelve sus datos solo cuando la solicitud coincide. Apila algunas de estas y obtendrás ramificaciones reales: respuesta B cuando la solicitud coincide con la condición A, un cuerpo de error cuando falta un encabezado, una carga útil diferente por parámetro de ruta.

Esa segunda capa hace posibles los estados de error bajo demanda y los cuerpos por solicitud. El resto de esta guía se centra ahí.

Valores dinámicos a nivel de campo primero

Antes de la ramificación, ayuda ver cómo un solo campo obtiene su valor, porque tus respuestas condicionales reutilizarán la misma sintaxis.

Dentro del esquema de un endpoint, cualquier campo de cadena puede contener una expresión de Faker.js escrita como {{$category.method}}. Apidog la resuelve de nuevo en cada llamada de mock, utilizando los tipos de campo que tu definición de JSON Schema ya declara.

{
  "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 parametrizados funcionan, así que {{$number.int(min=1000,max=9999)}} limita el valor y {{$date.between(...)}} fija un rango y formato. Puedes concatenar texto estático y múltiples expresiones en un campo, que es como se construye la dirección anterior. Si necesitas datos específicos de una región, Apidog admite localizaciones de mock personalizables para que tus nombres, direcciones y números de teléfono coincidan con un idioma o país determinado. La referencia de Faker.js en Apidog cubre el catálogo completo de métodos.

Ejemplo de un esquema con valores dinámicos Faker.js en Apidog.

Esto es territorio de Smart mock. Es dinámico, pero no es condicional. Para ramificarse según la solicitud, se pasa a las expectativas.

Tutorial: un endpoint de inicio de sesión que devuelve 200 o 401

El caso canónico: POST /login toma un cuerpo JSON con username y password. Un usuario conocido debería obtener 200 con un token. Todos los demás deberían obtener 401.

Abre la pestaña correcta

Dónde configurar esto depende de tu modo de trabajo:

En el modo DEBUG (Request-first), abre el endpoint y haz clic en la pestaña Mock.

Captura de pantalla de la interfaz de Apidog mostrando la pestaña 'Mock' en modo DEBUG.

En el modo DESIGN (Design-first), abre el endpoint y haz clic en la pestaña Advanced mock.

Captura de pantalla de la interfaz de Apidog mostrando la pestaña 'Advanced mock' en modo DESIGN.

Ambos conducen a la misma lista de expectativas. Si quieres seguir el tutorial y aún no tienes la aplicación, descarga Apidog e importa o crea primero un endpoint /login.

Añade la expectativa de éxito

Haz clic en Nueva expectativa. Dale un nombre de expectativa como login-success. Ahora añade una condición. Debido a que username reside en el cuerpo de la solicitud JSON, lo emparejas como un parámetro de cuerpo: pon la ruta JSON de la propiedad de destino, username, en el campo de nombre, y establece la condición para que sea igual a alice@example.com.

Captura de pantalla de Apidog mostrando la configuración de una nueva expectativa de mock con una condición basada en un parámetro de cuerpo JSON.

Las condiciones de parámetro de cuerpo son solo JSON, y se emparejan a través de la ruta JSON en el campo de nombre, por lo que las propiedades anidadas usan rutas de punto como user.email. Rellena los Datos de respuesta con la carga útil de éxito:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

Guarda. El Código de estado HTTP predeterminado es 200, por lo que no necesitas tocar nada más para el camino feliz.

Añade la expectativa de fallo

Haz clic en Nueva expectativa de nuevo. Nómbrala login-failure y deja sus condiciones en blanco para que actúe como un comodín. Establece sus Datos de respuesta al cuerpo del error:

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

Este necesita un estado no predeterminado. Abre la pestaña Más de la expectativa y establece el Código de estado HTTP en 401. Mientras estás allí, ten en cuenta que la pestaña Más también es donde estableces el Retraso de respuesta en milisegundos (predeterminado 0) y cualquier encabezado de respuesta personalizado. Un retraso de 400ms es una forma económica de asegurarte de que tu spinner de carga realmente se renderice.

El orden importa

Las expectativas se evalúan de arriba a abajo, y la primera coincidencia gana. Así que login-success debe estar encima de login-failure. Una solicitud con username igual a alice@example.com coincide con la primera regla y devuelve el token. Cualquier otra cosa cae en la regla de fallo incondicional y obtiene el 401. Si invirtieras el orden, la regla de condición en blanco coincidiría con todo y tu caso de éxito nunca se dispararía.

Copia la URL de mock del endpoint y prueba ambas rutas:

# usuario conocido -> 200 con un token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# cualquier otro -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

Tutorial: diferentes cuerpos para /orders/{id} por estado

El segundo caso común se ramifica en un parámetro de ruta. Quieres que /orders/{id} devuelva un pedido enviado para un ID y un pedido cancelado para otro, para que tu UI pueda renderizar cada estado sin un backend en vivo.

Crea una expectativa por estado. Para cada una, añade una condición sobre el parámetro de ruta id, luego rellena los Datos de respuesta correspondientes.

Expectativa order-shipped, condición: parámetro de ruta id es igual a 5001.

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

Expectativa order-cancelled, condición: parámetro de ruta id es igual a 5002.

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

Añade una expectativa final sin condiciones que devuelva un pedido pendiente genérico, para que cualquier otro ID siga obteniendo una respuesta válida en lugar de fallar. Ordena las reglas específicas por encima del comodín, guarda, y tendrás un mock que renderiza cada estado de pedido bajo demanda. La mezcla de condiciones también funciona: añade una condición de encabezado junto con la condición de ruta y ambas deben cumplirse, porque Apidog combina múltiples condiciones con lógica AND (una intersección de las condiciones, en los términos de la documentación).

Las condiciones no se limitan al cuerpo y la ruta. Puedes hacer coincidir parámetros de consulta, parámetros de encabezado, parámetros de cookie e incluso direcciones IP, lo que te permite restringir una respuesta a clientes específicos durante una prueba.

Forzando estados de error bajo demanda

No necesitas un backend roto para probar respuestas rotas. Una expectativa más la pestaña Más te da cualquier estado que desees.

Para forzar un 500, añade una expectativa cuya condición sea algo que controles desde el cliente, por ejemplo, un encabezado X-Mock-Scenario igual a server-error. Establece sus Datos de respuesta a un cuerpo de error realista y su Código de estado HTTP a 500 en la pestaña Más.

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

Ahora el mismo endpoint sirve un 200 normal por defecto y un 500 cada vez que envías ese encabezado. Haz lo mismo para 404, 429 (con un encabezado Retry-After configurado en la pestaña Más), o 503. Tu manejo de errores de frontend finalmente tiene algo que capturar. Si afirmas estas respuestas en comprobaciones automatizadas, la guía sobre aserciones de API se combina bien con esta configuración.

Un detalle para proyectos compartidos: cada expectativa se puede activar o desactivar de forma independiente para los entornos de mock local y en la nube desde la lista de expectativas. Así, puedes mantener una regla 500 activa localmente mientras la dejas desactivada en el mock en la nube que usan tus compañeros de equipo.

Cuando las reglas no son suficientes: scripts de mock

Las expectativas son declarativas. Coinciden y devuelven, pero no pueden calcular. Cuando necesitas un campo derivado de la solicitud, un total sumado de los elementos de línea, o un cuerpo que cambia de forma en función de varias entradas a la vez, recurre a un script de mock.

Un script de mock es JavaScript que se ejecuta contra la respuesta del mock. Se encuentra en la sección Mock Script en la parte inferior de la pestaña Mock y se habilita con un interruptor. El script expone dos variables globales:

$$.mockRequest: lee la solicitud entrante a través de getParam(key), además de headers, cookies, body, formdata, y urlencoded.
$$.mockResponse: da forma a la respuesta saliente a través de setBody(), setCode(), setDelay(), json(), y las propiedades headers y code.

Aquí tienes un script que calcula el total de un pedido a partir de los artículos de línea publicados y devuelve el encabezado de moneda del llamador:

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 es: Smart mock genera una respuesta inicial, tu script lee $$.mockRequest y el $$.mockResponse actual, aplica su lógica, llama a $$.mockResponse.setBody() (y setCode, setDelay, o headers según sea necesario), y el motor devuelve el resultado final. La referencia de JavaScript de MDN es un buen compañero si quieres llevar la lógica más allá con métodos de array o matemáticas de fechas.

La única regla que confunde a la gente

Los scripts de mock solo funcionan con Smart mock. No se aplican a las expectativas de mock ni a los ejemplos de respuesta. Esto es lo más importante que hay que interiorizar: no se puede combinar un script de mock con una respuesta basada en expectativas. Si una expectativa coincide con la solicitud, el script nunca se ejecuta. Así que elige un camino por endpoint. Usa expectativas cuando te ramifiques en condiciones fijas y devuelvas cuerpos predefinidos. Usa un script de mock cuando necesites una salida calculada a partir de la base generada por Smart mock.

Cómo se resuelve el orden de prioridad

Juntándolo todo, este es el orden que Apidog sigue para cualquier solicitud de mock:

Comprueba tus expectativas, de arriba a abajo. La primera expectativa cuyas condiciones coincidan todas gana, y su respuesta es devuelta. Por eso las reglas personalizadas vencen a Smart mock: una expectativa coincidente interrumpe todo lo que está debajo.
Si ninguna expectativa coincide, Apidog recurre a la Prioridad del método de mock que configuraste en Configuración del proyecto - Configuración de características - Configuración de mock. Ese es el nivel donde Smart mock (y cualquier script de mock adjunto a él) produce la respuesta.

El modelo mental es simple: primero las reglas específicas, luego los datos generados. Ordena tus expectativas de lo más específico a lo menos, mantén un comodín de condición en blanco al final si quieres una coincidencia garantizada, y deja que Smart mock se encargue de todo lo demás. Para un recorrido más profundo sobre cuándo apoyarse en cada capa, la guía de casos de uso de mocking de API asigna escenarios comunes a características.

Errores comunes que debes conocer antes de implementar

Algunas limitaciones te ahorrarán una confusa sesión de depuración:

Las condiciones de los parámetros no admiten {{variables}}. Las variables de proyecto y entorno de Apidog no están disponibles dentro de las expectativas de mock, así que usa valores literales en tus condiciones.
Las condiciones de los parámetros del cuerpo son solo JSON, no XML, y deben coincidir a través de la ruta JSON en el campo de nombre.
El formato del cuerpo de la solicitud en una condición debe coincidir con la especificación de la API. Un endpoint de tipo form-data debe ser simulado con la ubicación de form-data, no JSON.
Dentro de los scripts de mock no hay función de registro, el objeto pm no está disponible (es un entorno de ejecución diferente al de los scripts de prueba), y no se pueden usar las variables de Apidog. Mantén la lógica del script autocontenida.

Ninguna de estas características tiene restricciones de plan en la documentación. La única distinción entre local y nube es funcional: la opción independiente de activación/desactivación por entorno descrita anteriormente, no un muro de pago.

Automatiza el flujo de trabajo con la CLI de Apidog

El mocking en Apidog es una capacidad de GUI y en la nube. El motor de mock sirve tus endpoints desde URLs de mock locales y en la nube, y no hay ningún comando CLI que levante un servidor de mock en ejecución. Lo que la CLI de Apidog sí añade es control sobre los recursos a partir de los cuales se construyen esos mocks.

Las respuestas de mock se generan a partir del esquema del endpoint, por lo que la precisión de tu mock sigue la precisión de tu especificación. La CLI, y los agentes de codificación de IA que la impulsan (Cursor, Claude Code, Trae, Codex), pueden crear y actualizar los endpoints y esquemas en tu proyecto. Cambia el contrato en el código, sincronízalo, y la salida del mock se mantiene correcta sin que nadie tenga que reabrir la aplicación.

Una vez que el mock ha desbloqueado el trabajo de frontend, los escenarios de prueba del mismo proyecto se ejecutan de forma autónoma en CI para validar el backend real contra el contrato que describió el mock:

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

Ese único comando ejecuta tus escenarios de prueba e informa los resultados, de modo que el mock y la verificación comparten una única fuente de verdad. La guía de instalación de la CLI de Apidog cubre la configuración, y el tutorial de la CLI de Apidog en GitHub Actions lo conecta a un pipeline.

Preguntas frecuentes

¿Por qué mi expectativa es ignorada aunque la condición parece correcta? Casi siempre es por el orden o una falta de coincidencia de formato. Las expectativas se evalúan de arriba a abajo y la primera coincidencia gana, por lo que una regla general con condición en blanco ubicada encima de una específica se tragará la solicitud. Confirma también que el formato del cuerpo coincide con la especificación (ruta JSON para cuerpos JSON, ubicación de form-data para endpoints de formulario). La descripción general de mocking de API cubre los conceptos básicos de configuración si quieres volver a verificar.

¿Puedo usar un script de mock y una expectativa de mock en la misma respuesta? No. Los scripts de mock solo funcionan con Smart mock. Son ignorados por las expectativas de mock y los ejemplos de respuesta. Si una expectativa coincide, el script nunca se ejecuta, así que elige un enfoque por endpoint: expectativas para ramificaciones basadas en reglas, scripts para salida calculada.

¿Cómo devuelvo un 401 o 500 sin romper el 200 por defecto? Añade una expectativa dedicada con una condición que controles desde el cliente (un encabezado funciona bien), luego abre su pestaña Más y establece el Código de estado HTTP. La respuesta predeterminada permanece en 200; el error solo se dispara cuando la condición coincide.

¿Pueden las condiciones usar mis variables de entorno? No. Los valores de {{variable}} de Apidog no están disponibles dentro de las expectativas de mock, y las condiciones de los parámetros no admiten {{variables}}. Usa valores literales en las condiciones.

¿Qué sucede cuando ninguna expectativa coincide en absoluto? Apidog recurre a la Prioridad del método de mock en Configuración del Proyecto - Configuración de Características - Configuración de Mock, donde Smart mock genera una respuesta a partir de tu esquema. Añadir una expectativa comodín con condición en blanco es la forma de garantizar una alternativa específica.

Conclusión

Smart mock maneja el caso común, y las expectativas de mock manejan todo lo que lleva un "si": 200 para un usuario conocido y 401 en caso contrario, un cuerpo de pedido diferente por estado, un 500 bajo demanda. Recurre a un script de mock solo cuando necesites una salida calculada que las reglas no puedan expresar, y recuerda que se ejecuta solo con Smart mock. Ten en cuenta el orden de prioridad (primero las expectativas específicas, luego los datos generados) y tus mocks se ramificarán exactamente como lo hacen las APIs reales. Descarga Apidog para construir tu primer mock condicional, gratis, sin necesidad de tarjeta de crédito.

botón