Pruebas de Regresión API: Cómo Detectar Cambios Disruptivos a Tiempo

Envías un cambio pequeño a un endpoint. El código compila, la nueva función funciona y lo despliegas. Dos días después, un cliente móvil empieza a fallar porque un campo que renombraste antes era una cadena y ahora es un objeto. Nadie quiso romper nada. El cambio parecía local. No lo era.

Prueba Apidog hoy

Las pruebas de regresión de API existen para detectar ese tipo de fallos antes de que lleguen a producción. Guardas un conjunto de pruebas que describe cómo se comporta tu API hoy y lo vuelves a ejecutar en cada cambio. Si cambia la forma de una respuesta, el código de estado o el valor de una clave contractual, el conjunto falla y te muestra dónde ocurrió la regresión.

En esta guía vas a ver qué establecer como línea base, cómo construir un conjunto reutilizable y cómo ejecutarlo automáticamente en CI para que un cambio de nombre no se convierta en un incidente.

¿Qué son las pruebas de regresión de API?

Las pruebas de regresión consisten en volver a ejecutar pruebas que ya pasaron para confirmar que el comportamiento existente sigue intacto después de un cambio.

En APIs, ese “comportamiento existente” es el contrato del que dependen tus consumidores:

• Rutas.
• Métodos HTTP.
• Códigos de estado.
• Esquemas de respuesta.
• Tipos de datos.
• Campos obligatorios.
• Valores con significado contractual.

Las APIs regresan por cambios comunes:

• Alguien renombra un campo JSON.
• Una refactorización cambia un 200 por un 204.
• Una nueva validación rechaza una entrada que antes era válida.
• Una actualización del ORM cambia el formato de fecha.
• Una dependencia cambia el mensaje de error que un cliente parsea.

Nada de eso aparece como error de compilación. Aparece como integración rota.

La diferencia clave frente a las pruebas de regresión generales es el alcance. Aquí no intentas volver a probar toda la aplicación. Compruebas que la superficie HTTP, la parte a la que se acoplan otros sistemas, no cambió accidentalmente. Ese enfoque permite ejecutar el conjunto en cada commit.

Qué establecer como línea base

Un conjunto de regresión es tan útil como sus afirmaciones.

Si afirmas muy poco, se cuelan fallos reales. Si afirmas demasiado, cualquier cambio intencional rompe el pipeline. La regla práctica es:

Afirma sobre lo que rompería a un consumidor, no sobre todo lo que aparece hoy en el payload.

Establece una línea base en estas cuatro capas.

1. Códigos de estado

Cada endpoint debe devolver un estado conocido para entradas conocidas.

Ejemplos de regresión:

• 200 pasa a 500.
• 201 pasa a 200.
• 404 pasa a 204.
• 422 pasa a 400.

Aunque el cuerpo parezca correcto, el código de estado forma parte del contrato.

2. Esquema de respuesta

Valida estructura y tipos:

• Nombres de campos.
• Campos requeridos.
• Anidamiento.
• Tipos: string, number, boolean, array, object.
• Formatos esperados: email, date-time, UUID, etc.

Los cambios de esquema son una de las rupturas silenciosas más comunes.

3. Valores de campos clave

No necesitas fijar todos los valores. Fija los que tengan significado contractual:

• id debe existir.
• status debe pertenecer a un conjunto conocido.
• total debe ser numérico.
• email debe tener formato válido.
• roles debe ser un array.

Para valores volátiles como createdAt, no afirmes el valor exacto. Afirma tipo y formato.

4. Contrato OpenAPI

Valida que la respuesta real coincida con tu especificación.

Si OpenAPI dice que email es requerido y la API deja de devolverlo, eso es una violación de contrato. Puedes profundizar en este enfoque en pruebas de contrato de API.

Un ejemplo mínimo para un endpoint:

GET /v1/users/42  ->  200
  body.id            is present, type number
  body.email         is present, type string, matches email format
  body.status        is one of ["active", "pending", "suspended"]
  body.roles         type array
  response time      < 800 ms

Esas cinco comprobaciones describen un contrato operativo. Si una falla después de un cambio, tienes una regresión.

Para más detalle sobre cómo escribir validaciones sobre cuerpos de respuesta, consulta afirmaciones de API.

Pruebas de regresión manuales vs. automatizadas

Puedes hacer regresión manualmente: abres tu cliente API, ejecutas solicitudes guardadas y revisas respuestas.

Funciona para uno o dos endpoints. Se rompe cuando tienes diez, veinte o cien.

Los humanos omiten casos repetitivos. Y muchas regresiones viven justo en esos casos repetitivos.

Criterio	Manual	Automatizado
Se ejecuta en cada cambio	No, depende de la disciplina	Sí, por defecto
Cobertura	Pocos endpoints	Todo el conjunto
Costo por ejecución	Minutos de tiempo humano	Segundos de cómputo
Detecta fallos fuera de horario	No	Sí
Esfuerzo inicial	Bajo	Moderado

Para cualquier API mantenida por más de una persona o consumida por más de un cliente, automatiza.

Cómo construir un conjunto de regresión reutilizable

Un conjunto de regresión es un grupo de solicitudes guardadas con afirmaciones, organizado para ejecutarse junto.

El objetivo es simple:

1. Construirlo una vez.
2. Ejecutarlo en cada cambio.
3. Extenderlo cuando agregues endpoints o encuentres bugs.

Agrupa por recurso

Agrupa las pruebas por recurso, no por historia de usuario.

Ejemplo:

/users
  GET /users/{id}
  POST /users
  PATCH /users/{id}
  DELETE /users/{id}

/orders
  GET /orders/{id}
  POST /orders
  POST /orders/{id}/cancel

Cuando modifiques el servicio de usuarios, sabrás qué grupo revisar primero.

Usa variables de entorno

No codifiques valores que cambian en cada ambiente.

Usa variables para:

• URL base.
• Tokens.
• IDs de tenant.
• Credenciales de prueba.
• Headers comunes.

Ejemplo conceptual:

{{baseUrl}}/v1/users/{{userId}}
Authorization: Bearer {{accessToken}}
X-Tenant-Id: {{tenantId}}

Así puedes ejecutar el mismo conjunto contra local, staging o producción cambiando solo el entorno.

Encadena solicitudes dependientes

Muchos bugs no aparecen en una solicitud aislada. Aparecen en flujos.

Ejemplo CRUD:

1. POST /users
   extrae body.id -> userId

2. GET /users/{{userId}}
   valida status 200
   valida body.id == userId

3. PATCH /users/{{userId}}
   valida status 200
   valida body.status actualizado

4. DELETE /users/{{userId}}
   valida status 204

Este tipo de flujo se solapa con las pruebas de integración de API, porque valida comportamiento entre varias operaciones.

Usa datos para casos extremos

No crees diez solicitudes casi iguales. Crea una solicitud y aliméntala con una tabla.

Ejemplo en CSV:

email,expectedStatus
[e-mail],201
[e-mail],201
not-an-email,422
,422
a@b,422

Una solicitud, cinco casos, cinco afirmaciones sobre el código de estado.

Cuando descubras un nuevo caso extremo, agregas una fila. No necesitas duplicar pruebas.

Mantén el conjunto rápido

Un conjunto de regresión que tarda veinte minutos será ignorado o movido fuera del flujo principal.

Para mantenerlo útil:

• Ejecuta en paralelo las solicitudes independientes si tu herramienta lo permite.
• Simula dependencias externas lentas.
• Deja los flujos end-to-end largos para ejecuciones nocturnas.
• Mantén en pull requests un conjunto rápido y representativo.

Ejecutar el conjunto en CI

Un conjunto de regresión que vive en tu portátil solo protege tu portátil.

El objetivo es ejecutarlo en CI en los eventos que pueden introducir regresiones:

• Pull requests.
• Merges a la rama principal.
• Despliegues a staging.
• Despliegues a producción, si aplica.

El patrón general es:

1. Instalar un runner sin interfaz gráfica.
2. Ejecutar el conjunto guardado.
3. Pasar el entorno como configuración.
4. Fallar el job si falla alguna afirmación.
5. Publicar reportes legibles por CI.

Apidog incluye un runner de línea de comandos para esto. Instálalo con Node:

npm install -g apidog-cli

Ejecuta un escenario o conjunto guardado por ID:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,html,junit

Qué significa cada opción:

• --access-token: autentica la ejecución. Guárdalo como secreto de CI.
• -t: ID del escenario, carpeta o conjunto que quieres ejecutar.
• -e: ID del entorno.
• -r: formatos de reporte.
  • cli: salida en consola.
  • html: reporte navegable.
  • junit: XML para que el CI muestre resultados por prueba.

Ejemplo en GitHub Actions:

name: API Regression

on: [pull_request]

jobs:
  regression:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: '22'

      - run: npm install -g apidog-cli

      - run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 123456 \
            -e 789012 \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Si una prueba falla, el runner devuelve un código distinto de cero. El job queda en rojo y el pull request queda bloqueado hasta que alguien revise la regresión.

Para una guía más completa de CI/CD, revisa Apidog CLI para CI/CD y cómo automatizar pruebas de API en GitHub Actions.

Si usas un archivo de datos, pásalo con -d:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -d ./test-data/emails.csv \
  -r cli,junit

Si estás probando una rama con su propia versión de API, usa --branch para ejecutar el conjunto guardado en esa rama. Para conservar el historial de ejecuciones en la nube, agrega --upload-report.

Diferencias de esquema y contrato

Las afirmaciones detectan regresiones en runtime. La comparación de esquemas puede detectarlas antes de desplegar.

La idea es versionar tu especificación OpenAPI en el repositorio. Cuando alguien la cambia, comparas la nueva versión con la anterior y clasificas el cambio.

Cambios normalmente seguros:

• Agregar un campo opcional.
• Agregar un nuevo endpoint.
• Agregar un nuevo valor opcional sin romper clientes existentes.

Cambios potencialmente disruptivos:

• Eliminar un campo.
• Renombrar un campo.
• Cambiar string por object.
• Hacer obligatorio un campo antes opcional.
• Eliminar un valor de un enum.
• Cambiar códigos de estado esperados.

Una herramienta de diff puede marcar estos cambios en el pull request para que el revisor vea algo accionable, por ejemplo:

Breaking change:
  Removed response property: user.phone

Combina esto con pruebas de contrato contra la API real:

• La especificación detecta cambios intencionales en el contrato.
• Las pruebas contra la API viva detectan si el código se desvió del contrato.

No todos los cambios disruptivos son errores. A veces necesitas eliminar un campo o cambiar un tipo. El punto es hacer explícita esa decisión y gestionarla con versionado y deprecación, no sorprender a los consumidores.

Para ese proceso, consulta cómo versionar y deprecar APIs a escala.

Cómo Apidog ejecuta conjuntos de regresión

Apidog reúne diseño de API, escenarios de prueba y ejecución automatizada en el mismo flujo.

Puedes construir escenarios visualmente:

• Encadenar solicitudes.
• Extraer valores de una respuesta.
• Pasar variables a la siguiente solicitud.
• Añadir afirmaciones sobre estado, esquema y campos.
• Validar respuestas contra el esquema guardado del endpoint.

Como el diseño de la API y las pruebas viven en el mismo proyecto, no necesitas duplicar el esquema en dos lugares. Cuando cambia el diseño, también cambia la referencia contra la que se validan las pruebas.

Para pruebas basadas en datos, puedes adjuntar datasets CSV o JSON a un escenario. Apidog ejecuta un caso por fila.

Luego puedes guardar escenarios relacionados en un conjunto para ejecutar un recurso o flujo completo.

El runner apidog-cli lleva esos escenarios a CI sin interfaz gráfica. Ejecuta conjuntos guardados y reporta resultados. No es un cliente interactivo ni un generador de carga; su objetivo es reproducir tu conjunto de regresión y fallar cuando algo se rompe.

Para un flujo scriptado, revisa la guía de pipeline de CI/CD de Apidog CLI.

Flujo de trabajo inicial

Puedes adoptar este flujo esta semana sin rehacer toda tu estrategia de pruebas.

1. Elige tus cinco endpoints más usados.
   
   El riesgo se concentra donde hay más tráfico o más consumidores.

2. Guarda una solicitud por endpoint.
   
   Añade afirmaciones de código de estado, esquema y dos o tres campos clave.

3. Crea un flujo encadenado.
   
   Por ejemplo: crear, leer, actualizar y eliminar tu recurso principal.

4. Agrega datos a un endpoint con mucha validación.
   
   Incluye entradas válidas, vacías, límite e inválidas.

5. Ejecútalo en CI para pull requests.
   
   Instala apidog-cli, ejecuta el conjunto con -r junit y bloquea merges si falla.

6. Convierte cada bug escapado en una prueba.
   
   Si una regresión llegó a producción, agrega un caso para que no vuelva a ocurrir.

Los pasos 1 a 4 pueden hacerse en una tarde. El paso 5 suele ser un único archivo de CI. Después, el conjunto se ejecuta solo y crece cuando la realidad revela nuevos modos de fallo.

Ese es el objetivo: que un cambio de nombre que antes habría sido un incidente se convierta en una verificación roja dentro de un pull request.

Preguntas frecuentes

¿En qué se diferencian las pruebas de regresión de API de las pruebas de regresión generales?

Las pruebas de regresión generales verifican comportamiento en toda la aplicación, incluyendo UI y lógica de negocio. Las pruebas de regresión de API se enfocan en la superficie HTTP: rutas, códigos de estado, esquema de respuesta y valores contractuales.

Ese alcance reducido permite ejecutarlas en cada commit.

¿Con qué frecuencia debo ejecutar el conjunto?

En cada cambio que pueda afectar la API.

En la práctica:

• En cada pull request.
• En cada merge a la rama principal.
• Antes o después de desplegar a staging.
• Opcionalmente, antes de promover a producción.

Mantén un conjunto rápido para PRs y deja flujos end-to-end más lentos para ejecuciones nocturnas.

¿Qué debo afirmar para evitar pruebas frágiles?

Afirma lo que rompería a un consumidor:

• Código de estado.
• Campos requeridos.
• Tipos de datos.
• Estructura de respuesta.
• Valores contractuales como enums o IDs.
• Formato de valores dinámicos, no su valor literal.

Evita afirmar datos volátiles como timestamps exactos, IDs generados o mensajes que no formen parte del contrato.

¿Puedo ejecutar pruebas de regresión de API sin escribir código?

Sí. Herramientas como Apidog permiten construir escenarios y afirmaciones visualmente. Luego puedes ejecutarlos en CI con apidog-cli, sin mantener un framework de pruebas propio.

¿Cómo manejo cambios disruptivos intencionales?

No los escondas como simples fallos de prueba.

Hazlos pasar por tu proceso de versionado y deprecación:

1. Marca el cambio en revisión con diff de esquema.
2. Comunica el cambio a consumidores.
3. Versiona el endpoint si hace falta.
4. Mantén compatibilidad temporal si es posible.
5. Actualiza la línea base de regresión de forma deliberada.