Ya ejecutas Cypress para pruebas de extremo a extremo. Ahora quieres acceder a una API directamente, verificar el código de estado y hacer aserciones sobre el cuerpo JSON sin navegar por la interfaz de usuario. Cypress puede hacer eso. El comando cy.request() envía solicitudes HTTP reales desde Node, fuera del navegador, para que puedas probar un endpoint por sí solo o configurar el estado antes de ejecutar una prueba de interfaz de usuario.
Esta guía te muestra cómo probar APIs con Cypress: los conceptos básicos de cy.request(), hacer aserciones sobre las respuestas, encadenar solicitudes para reutilizar un token de autenticación y simular el tráfico del navegador con cy.intercept(). También verás dónde Cypress para API encaja bien y dónde una herramienta nativa de API encaja mejor.
¿Por qué probar APIs con Cypress?
La mayoría de las suites de Cypress controlan un navegador. Pero mucho de lo que verificas en la interfaz de usuario es la API subyacente: ¿/login devuelve un token, ¿/users devuelve la forma correcta, ¿un POST crea el registro que esperas?
Probar esos endpoints directamente tiene dos beneficios. Primero, las verificaciones de API se ejecutan más rápido que los flujos de interfaz de usuario porque no hay renderizado, ni espera de elementos. Segundo, puedes usar cy.request() para configurar datos de prueba. En lugar de hacer clic en un formulario de registro para crear un usuario, envías un POST y pasas a la aserción que realmente te importa.
Si Cypress ya está en tu pila, añadir pruebas de API significa que no hay una nueva herramienta que instalar. Las escribes en los mismos archivos de especificación, con las mismas aserciones expect, en la misma ejecución de CI.
Conceptos básicos de cy.request()
cy.request() realiza una solicitud HTTP y devuelve la respuesta. Se ejecuta desde el proceso de Node de Cypress, no desde el navegador, por lo que no está sujeto a las reglas de CORS o de mismo origen.
El comando acepta varias formas:
cy.request(url)
cy.request(url, body)
cy.request(method, url)
cy.request(method, url, body)
cy.request(options)
La llamada más sencilla pasa una URL. Sin método, Cypress usa GET por defecto:
cy.request('https://jsonplaceholder.typicode.com/users')
Para cualquier cosa más allá de un GET básico, pasa un objeto de opciones. Esto te da control total sobre el método, el cuerpo y los encabezados:
cy.request({
method: 'POST',
url: 'https://jsonplaceholder.typicode.com/posts',
headers: {
'Content-Type': 'application/json'
},
body: {
title: 'API test',
body: 'created from Cypress',
userId: 1
}
})
Opciones útiles en ese objeto:
method: el verbo HTTP (GET,POST,PUT,PATCH,DELETE, y otros). Por defecto esGET.url: el endpoint. Obligatorio.body: el cuerpo de la solicitud. Cypress serializa los objetos a JSON.headers: un objeto de encabezados de solicitud.auth: credenciales para Autenticación Básica HTTP.qs: parámetros de cadena de consulta como un objeto.failOnStatusCode: se establece enfalsecuando quieres hacer aserciones sobre una respuesta 4xx o 5xx en lugar de fallar la prueba.
Esa última opción es importante para las pruebas negativas. Por defecto, cy.request() falla la prueba con cualquier estado que no sea 2xx o 3xx. Si estás comprobando que una solicitud errónea devuelve 400, tienes que desactivar esta opción:
cy.request({
method: 'GET',
url: 'https://jsonplaceholder.typicode.com/users/99999',
failOnStatusCode: false
}).then((response) => {
expect(response.status).to.eq(404)
})
Aserciones sobre el estado y el cuerpo
cy.request() devuelve un objeto de respuesta. Encadena .then() para leerlo. La respuesta tiene cuatro propiedades que usarás con mayor frecuencia:
status: el código de estado HTTP.body: el cuerpo de la respuesta. Cypress lo analiza a un objeto JavaScript cuando elContent-Typetermina enjson.headers: los encabezados de la respuesta.duration: el tiempo que tardó la solicitud, en milisegundos.
Aquí tienes una prueba completa que verifica el estado, la forma del cuerpo y un campo específico:
describe('Users API', () => {
it('returns a list of users', () => {
cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
expect(response.status).to.eq(200)
expect(response.body).to.be.an('array')
expect(response.body).to.have.length(10)
expect(response.body[0]).to.have.property('email')
})
})
})
Debido a que response.body ya es un objeto analizado, puedes hacer aserciones sobre él con Chai estándar. Puedes verificar el tipo, la longitud, las propiedades anidadas o los valores exactos. Esta es la misma sintaxis de aserción que usas para las pruebas de interfaz de usuario, por lo que no hay nada nuevo que aprender.
También puedes hacer aserciones sobre los encabezados de respuesta, lo cual es útil para verificar el tipo de contenido o el almacenamiento en caché:
cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
expect(response.headers['content-type']).to.include('application/json')
})
Para una mirada más profunda a la estructuración de estas verificaciones, consulta nuestra guía sobre aserción de API y las mejores prácticas de pruebas de API en general.
Encadenar solicitudes y reutilizar un token de autenticación
Las APIs reales necesitan autenticación. El patrón común es iniciar sesión una vez, obtener el token y luego enviarlo en cada solicitud posterior. cy.request() se encadena limpiamente para esto.
Envía la solicitud de inicio de sesión, lee el token del cuerpo de la respuesta y luego úsalo en la siguiente llamada:
describe('Authenticated API flow', () => {
it('logs in and fetches a protected resource', () => {
cy.request({
method: 'POST',
url: 'https://api.example.com/login',
body: {
email: 'user@example.com',
password: 'secret'
}
}).then((loginResponse) => {
expect(loginResponse.status).to.eq(200)
const token = loginResponse.body.token
cy.request({
method: 'GET',
url: 'https://api.example.com/profile',
headers: {
Authorization: `Bearer ${token}`
}
}).then((profileResponse) => {
expect(profileResponse.status).to.eq(200)
expect(profileResponse.body).to.have.property('email', 'user@example.com')
})
})
})
})
Si varias pruebas necesitan el mismo token, mueve el inicio de sesión a un beforeEach y almacena el token con Cypress.env() o un alias envuelto para que cada prueba lo recoja. Eso mantiene la configuración de autenticación en un solo lugar en lugar de repetirla en cada especificación.
Este patrón de inicio de sesión y uso es la misma forma que escribirías en cualquier flujo de prueba de integración de API, donde una llamada alimenta datos a la siguiente.
cy.intercept() para simulación (stubbing)
cy.request() accede a la API real. A veces quieres lo contrario: interceptar las solicitudes que hace tu aplicación front-end y devolver una respuesta falsa. Eso es cy.intercept().
Aquí hay una distinción importante. cy.intercept() solo intercepta las solicitudes realizadas por tu aplicación front-end en el navegador. No intercepta cy.request(), porque cy.request() omite completamente el navegador. Usa cy.intercept() cuando estés probando cómo reacciona tu interfaz de usuario a una respuesta de API determinada, no cuando estés probando la API en sí.
Puedes espiar una solicitud, simularla con una respuesta estática o esperarla. Para simular, pasa un objeto de respuesta:
cy.intercept('GET', '/api/users', {
statusCode: 200,
body: [{ id: 1, name: 'Ada' }]
})
Ahora, cualquier solicitud de navegador a /api/users devuelve esa carga útil fija. Esto te permite probar casos límite difíciles de activar contra un backend en vivo, como una lista vacía, un error 500 o una respuesta lenta.
Para afirmar que la solicitud ocurrió, dale un alias con .as() y espérala:
it('shows an error banner when the API fails', () => {
cy.intercept('GET', '/api/users', {
statusCode: 500,
body: { message: 'Server error' }
}).as('getUsers')
cy.visit('/dashboard')
cy.wait('@getUsers').its('response.statusCode').should('eq', 500)
cy.contains('Something went wrong').should('be.visible')
})
La línea cy.wait('@getUsers') pausa la prueba hasta que la solicitud interceptada se resuelva, luego te entrega la solicitud y la respuesta para hacer aserciones. Configura la intercepción antes de la acción que dispara la solicitud, o no capturará nada. Si estás sopesando cuándo simular una respuesta versus simular un servicio completo, nuestras publicaciones sobre simulación de API y stubbing de API vs. mocking de API desglosan las ventajas y desventajas.
Cuándo Cypress para API tiene sentido y cuándo no
Cypress es una excelente opción para las verificaciones de API que viven dentro de una suite de pruebas de interfaz de usuario. Si ya estás escribiendo pruebas e2e y necesitas sembrar datos, verificar un endpoint del que depende tu interfaz de usuario o simular una respuesta para probar el manejo de errores, cy.request() y cy.intercept() mantienen todo en un solo lugar. Sin cambio de contexto, sin segunda herramienta.
También está bien para un puñado de pruebas de humo de API independientes cuando Cypress es tu único ejecutor de pruebas y no quieres añadir otra dependencia.
Donde se vuelve incómodo es con una suite de pruebas de API grande e independiente. Cypress fue construido para el navegador, por lo que las pruebas de API son una capacidad añadida, no el diseño central. Algunas brechas aparecen a medida que la suite crece:
- No hay un constructor visual de solicitudes. Cada solicitud es código. Componer encabezados, cuerpos y parámetros de consulta a mano se vuelve lento cuando tienes cientos de endpoints.
- Más débil para una pipeline de API solo de CI. Cypress inicia un contexto de navegador incluso para ejecuciones de API puras, lo cual es una sobrecarga que no necesitas.
- No hay una definición de API compartida. Las formas de las solicitudes viven en tus archivos de prueba, no en una especificación que tu equipo pueda reutilizar en diseño, documentación y pruebas.
Aquí es donde una herramienta nativa de API encaja mejor. Apidog está construido alrededor de la propia API: diseñas un endpoint una vez, luego construyes escenarios de prueba contra él con un constructor visual de solicitudes y aserciones visuales, sin necesidad de código para los casos comunes. Las solicitudes, entornos y autenticación viven en un espacio de trabajo compartido, por lo que tu equipo no tiene que derivarlos de nuevo a partir de archivos de prueba.
Para CI, la CLI de Apidog ejecuta tus escenarios de prueba guardados sin interfaz gráfica en cualquier paso que pueda ejecutar Node:
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
El flag -t apunta a un escenario o suite guardado, -e selecciona un entorno y -r elige los formatos de informe (cli, html, json, junit). La salida JUnit se integra directamente en la mayoría de los paneles de CI. Añade -d o --iteration-data para ejecutar una prueba desde un archivo de datos, y --upload-report para enviar los resultados de vuelta a tu espacio de trabajo. La CLI ejecuta escenarios guardados; no es un enviador de solicitudes interactivo.
Una forma útil de pensarlo: usa cy.request() para verificaciones de API que apoyan tus pruebas de navegador, y opta por una herramienta nativa de API cuando las pruebas de API son la tarea principal. Si estás comparando opciones, nuestros resúmenes de herramientas de automatización de pruebas de API que se ejecutan en CI/CD y las 30 mejores herramientas de prueba de API cubren el campo.
Preguntas Frecuentes
¿Se ejecuta cy.request() en el navegador?
No. cy.request() se ejecuta desde el proceso de Node de Cypress, fuera del navegador. Por eso no es bloqueado por CORS ni por la política de mismo origen, y por qué cy.intercept() no puede interceptarlo. Si necesitas una solicitud que el navegador realiza, dispárala a través de tu aplicación y captúrala con cy.intercept().
¿Cómo pruebo una respuesta 400 o 404 sin que la prueba falle?
Por defecto, cy.request() falla con cualquier estado que no sea 2xx o 3xx. Establece failOnStatusCode: false en el objeto de opciones, luego haz la aserción sobre el estado tú mismo con expect(response.status).to.eq(404).
¿Puedo usar cy.request() para iniciar sesión antes de una prueba de interfaz de usuario?
Sí, y es un patrón común. Envía un POST a tu endpoint de inicio de sesión con cy.request(), lee el token de response.body y almacénalo (en Cypress.env(), localStorage o una cookie) para que tu prueba de interfaz de usuario comience ya autenticada. Esto omite el formulario de inicio de sesión y acelera la suite.
¿Cuál es la diferencia entre cy.request() y cy.intercept()?
cy.request() envía una solicitud HTTP real y devuelve la respuesta real, por lo que lo usas para probar una API. cy.intercept() observa o simula las solicitudes que tu front-end realiza en el navegador, por lo que lo usas para controlar lo que tu interfaz de usuario recibe. Uno golpea la red; el otro la moldea.
¿Debo usar Cypress o una herramienta dedicada para pruebas de API?
Usa Cypress cuando las verificaciones de API apoyen una suite de pruebas de navegador que ya ejecutas. Para una suite de API independiente grande, pipelines de API solo de CI o una definición de API compartida de la que trabaja todo tu equipo, una herramienta nativa de API como Apidog encaja mejor. Consulta nuestras mejores prácticas de pruebas de API para saber cómo decidir.