Cypress API Testing Plugin

2.11.2 · active · verified Tue Apr 21

Cypress Plugin API is a tool for enhancing API testing within the Cypress test runner by providing a user interface similar to Postman. It extends the standard `cy.request()` command with `cy.api()`, which visually logs details about API calls, including URLs, headers, request/response bodies, and cookies, directly into the Cypress App UI. These details are viewable through time-travel snapshots. Key features include JSON data object/array folding, HTTP method color coding, response size calculation, and options for sensitive data masking (like credentials) and integrating API calls seamlessly into UI test flows using `snapshotOnly` mode. The plugin currently maintains version `2.11.2`, released on July 14, 2024, with a consistent cadence of bug fixes and minor feature additions. It ships with TypeScript types to provide a better development experience.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates setting up `cypress-plugin-api` in `cypress.config.ts`, importing it, and using `cy.api()` for GET and POST requests. It also showcases `hideCredentials` and `snapshotOnly` environmental options.

import { defineConfig } from 'cypress'

// cypress.config.ts
export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // Optional: Add an event listener to log something during setup
      on('task', {
        log(message) {
          console.log(message)
          return null
        },
      })
      return config
    },
    baseUrl: 'http://localhost:3000', // Ensure your API is running here
    env: {
      snapshotOnly: false, // Default: shows full UI for API calls
      hideCredentials: true,
      myAuthToken: 'secret-token-123',
      apiUser: 'testuser',
      apiPass: 'testpassword',
    }
  },
})

// cypress/support/e2e.ts
import 'cypress-plugin-api'
// You can also add other Cypress commands or configurations here

// cypress/e2e/api.cy.ts
describe('Cypress Plugin API features', () => {
  beforeEach(() => {
    // Assuming your app serves simple endpoints for demonstration
    // For a real app, ensure your dev server is running before tests
  })

  it('should make a GET API call and display full UI details', () => {
    cy.api('/data').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.have.property('message', 'Hello from API')
    })
  })

  it('should make a POST API call with hidden credentials and custom options', {
    env: {
      hideCredentials: true,
      hideCredentialsOptions: {
        headers: ['authorization'],
        body: ['password'],
        query: ['apiKey']
      }
    }
  }, () => {
    cy.api({
      method: 'POST',
      url: '/login',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${Cypress.env('myAuthToken')}` // This header will be hidden
      },
      body: {
        username: Cypress.env('apiUser'),
        password: Cypress.env('apiPass') // This body field will be hidden
      },
      qs: {
        apiKey: 'super-secret-key' // This query param will be hidden
      }
    }).then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.have.property('success', true)
    })
  })

  it('should combine UI and API testing with snapshotOnly mode', { env: { snapshotOnly: true } }, () => {
    cy.visit('/') // Navigate to your web application
    cy.get('h1').should('contain', 'Welcome') // Interact with UI

    cy.api('/users').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.be.an('array')
    })

    cy.get('#user-list').should('exist') // More UI interaction after API call
  })
})

view raw JSON →