DEV Community

JhonyVargas
JhonyVargas

Posted on

Pruebas de API con Cypress: de cy.request() a producción con GitHub Actions y Render

Cuando escuchamos "Cypress" casi siempre pensamos en pruebas de interfaz: clics, formularios, navegación. Pero Cypress también es una herramienta muy cómoda para probar APIs REST, y lo mejor es que podemos tener pruebas de API y de interfaz en el mismo proyecto, con la misma sintaxis.

En este artículo construyo TaskLab, una API de tareas con Node.js y Express, la pruebo con Cypress, automatizo las pruebas con GitHub Actions y la despliego en Render, de forma que solo llega a producción el código que pasa todas las pruebas.


1. La aplicación

TaskLab expone un CRUD de tareas:

Método Ruta Respuestas
GET /api/health 200
GET /api/tareas?estado=&prioridad=&q= 200, 400
GET /api/tareas/:id 200, 404
POST /api/tareas 201, 400
PUT /api/tareas/:id 200, 400, 404
DELETE /api/tareas/:id 204, 404

Cada tarea tiene titulo (3-100 caracteres), descripcion, prioridad (baja | media | alta) y completada. La API valida los datos y responde siempre en JSON, incluso en los errores:

app.post('/api/tareas', (req, res) => {
  const errores = store.validate(req.body, { parcial: false });
  if (errores.length) return error(res, 400, 'Datos inválidos', errores);
  const tarea = store.create(req.body);
  res.status(201).location(`/api/tareas/${tarea.id}`).json(tarea);
});
Enter fullscreen mode Exit fullscreen mode

Además tiene un frontend con una consola de API que muestra cada petición HTTP que hace la interfaz (método, ruta, código de estado, tiempo y body), así se ve en todo momento qué pasa "por debajo".

2. Instalando Cypress

npm install -D cypress start-server-and-test
Enter fullscreen mode Exit fullscreen mode

cypress.config.js:

const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    baseUrl: process.env.BASE_URL || 'http://localhost:3000',
    video: false,
    retries: { runMode: 1, openMode: 0 },
  },
});
Enter fullscreen mode Exit fullscreen mode

Leer baseUrl desde una variable de entorno permite ejecutar las mismas pruebas en local y contra producción.

3. Primera prueba: cy.request()

cy.request() hace una petición HTTP real y nos da el status, los headers, el body y la duration:

it('GET /api/health responde 200 y status ok', () => {
  cy.request('/api/health').then((res) => {
    expect(res.status).to.eq(200);
    expect(res.headers['content-type']).to.include('application/json');
    expect(res.body).to.have.property('status', 'ok');
    expect(res.duration).to.be.lessThan(2000);
  });
});
Enter fullscreen mode Exit fullscreen mode

4. Probando el CRUD

Crear (201 + header Location):

it('crea una tarea válida y responde 201', () => {
  const nueva = { titulo: 'Aprender cy.request()', prioridad: 'alta' };

  cy.request('POST', '/api/tareas', nueva).then((res) => {
    expect(res.status).to.eq(201);
    expect(res.headers).to.have.property('location', `/api/tareas/${res.body.id}`);
    expect(res.body).to.include(nueva);
    expect(res.body.completada).to.eq(false);
  });
});
Enter fullscreen mode Exit fullscreen mode

Eliminar y verificar que ya no existe:

it('elimina una tarea y responde 204', () => {
  cy.crearTarea({ titulo: 'Tarea a eliminar' }).then((tarea) => {
    cy.request('DELETE', `/api/tareas/${tarea.id}`).its('status').should('eq', 204);
    cy.request({ url: `/api/tareas/${tarea.id}`, failOnStatusCode: false })
      .its('status').should('eq', 404);
  });
});
Enter fullscreen mode Exit fullscreen mode

💡 Por defecto cy.request() falla si el código no es 2xx/3xx. Para probar errores usamos failOnStatusCode: false.

5. Casos negativos guiados por datos

Probar solo el "camino feliz" no basta. Con un arreglo de casos generamos varias pruebas de validación:

const invalidos = [
  { caso: 'sin título',         body: { prioridad: 'alta' },                 mensaje: '"titulo" es obligatorio' },
  { caso: 'título muy corto',   body: { titulo: 'ab' },                      mensaje: 'al menos 3 caracteres' },
  { caso: 'prioridad inválida', body: { titulo: 'Tarea', prioridad: 'urgente' }, mensaje: '"prioridad" debe ser' },
];

invalidos.forEach(({ caso, body, mensaje }) => {
  it(`responde 400 cuando el body tiene ${caso}`, () => {
    cy.request({ method: 'POST', url: '/api/tareas', body, failOnStatusCode: false })
      .then((res) => {
        expect(res.status).to.eq(400);
        expect(res.body.detalles.join(' ')).to.include(mensaje);
      });
  });
});
Enter fullscreen mode Exit fullscreen mode

6. Comandos personalizados

Para no repetir código, creé comandos en cypress/support/commands.js:

Cypress.Commands.add('crearTarea', (tarea = {}) =>
  cy.request('POST', '/api/tareas', { titulo: `Tarea ${Date.now()}`, ...tarea }).its('body')
);
Enter fullscreen mode Exit fullscreen mode

7. Bonus: probar que el frontend usa bien la API

Con cy.intercept() espiamos las peticiones que hace la página y validamos request y response:

cy.intercept('POST', '/api/tareas').as('crear');
cy.get('[data-cy=input-titulo]').type('Tarea UI');
cy.get('[data-cy=btn-agregar]').click();

cy.wait('@crear').then(({ request, response }) => {
  expect(request.body.titulo).to.eq('Tarea UI');
  expect(response.statusCode).to.eq(201);
});
Enter fullscreen mode Exit fullscreen mode

Resultado local: 33 pruebas en verde ✅

  ✔  api/stats.cy.js       2 passing
  ✔  api/tareas.cy.js     26 passing
  ✔  ui/frontend.cy.js     5 passing
Enter fullscreen mode Exit fullscreen mode

8. Automatización con GitHub Actions

Cada push o pull request a main levanta la API y ejecuta Cypress:

name: CI - Pruebas de API con Cypress
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test:ci
Enter fullscreen mode Exit fullscreen mode

test:ci usa start-server-and-test: levanta la API, espera a que /api/health responda y luego ejecuta Cypress. Así el CI hace exactamente lo mismo que en local.

⚠️ Cypress 16 requiere Node 22 o superior; con Node 20 el pipeline falla.

9. Despliegue en Render (solo si las pruebas pasan)

El archivo render.yaml define el servicio como código:

services:
  - type: web
    name: tasklab-api-testing
    runtime: node
    plan: free
    buildCommand: npm ci --omit=dev
    startCommand: npm start
    healthCheckPath: /api/health
    autoDeployTrigger: checksPass
Enter fullscreen mode Exit fullscreen mode

La clave es autoDeployTrigger: checksPass: Render espera a que GitHub Actions termine en verde antes de desplegar. Si una prueba falla, el código roto nunca llega a producción.

Para crearlo: en Render, New → Blueprint y seleccionar el repositorio.

10. Probar producción

Como baseUrl sale de una variable de entorno, un segundo workflow ejecuta las pruebas de API contra la URL pública todos los días:

BASE_URL=https://tasklab-api-testing.onrender.com npx cypress run --spec "cypress/e2e/api/**"
Enter fullscreen mode Exit fullscreen mode

Conclusiones

  • cy.request() hace que probar APIs con Cypress sea simple y legible.
  • Probar los casos negativos (400, 404, JSON mal formado) es tan importante como el camino feliz.
  • Con GitHub Actions + autoDeployTrigger: checksPass en Render tenemos un pipeline donde las pruebas son la puerta de entrada a producción.
  • La misma suite sirve para local, CI y producción.

¿Usas Cypress para probar APIs o prefieres Postman/Newman o k6? ¡Te leo en los comentarios! 👇

Top comments (0)