Skip to main content

​
Overview

The API configuration file (cypress.config.api.ts) defines settings specifically for API testing using Cypress. Location: cypress.config.api.ts

​
Complete Configuration

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: 'https://restful-booker.herokuapp.com',
    specPattern: 'cypress/e2e/api/**/*.cy.ts',
    supportFile: 'cypress/support/e2e.ts',
    watchForFileChanges: false,
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

​
Configuration Options

​
e2e

The main configuration object for end-to-end testing.
​
baseUrl
string
default:"https://restful-booker.herokuapp.com"
Base URL for the API under test. All cy.request() commands will use this as the base URL.
​
specPattern
string
default:"cypress/e2e/api/**/*.cy.ts"
Glob pattern that specifies which API test files to run. This pattern matches all TypeScript Cypress spec files in the cypress/e2e/api/ directory and subdirectories.
​
supportFile
string
default:"cypress/support/e2e.ts"
Path to the support file that runs before all spec files. Use this for global configuration, custom commands, and imports.
​
watchForFileChanges
boolean
default:false
When set to false, Cypress will NOT automatically re-run tests when spec or source files change. Set to true for development mode with auto-reload.
​
setupNodeEvents
function
Function to register Node.js event listeners. Use this to implement plugins and custom behavior for API testing.

​
Usage

​
Running API Tests

Specify this configuration file when running Cypress: 
# Open Cypress Test Runner
cypress open --config-file cypress.config.api.ts

# Run tests in headless mode
cypress run --config-file cypress.config.api.ts

​
Running Specific API Specs

# Run all API specs
cypress run --config-file cypress.config.api.ts

# Run specific API spec file
cypress run --config-file cypress.config.api.ts --spec "cypress/e2e/api/GETSpec.cy.ts"

# Run multiple spec files
cypress run --config-file cypress.config.api.ts --spec "cypress/e2e/api/GETSpec.cy.ts,cypress/e2e/api/POSTSpec.cy.ts"

​
Test File Structure

Based on the specPattern, API tests should be organized as follows: 
cypress/
└── e2e/
    └── api/
        ├── GETSpec.cy.ts
        ├── POSTSpec.cy.ts
        ├── PUTSpec.cy.ts
        ├── DELETESpec.cy.ts
        └── ... (other API test files)

​
baseUrl for API Testing

​
How It Works

With baseUrl set to https://restful-booker.herokuapp.com: 
// This:
cy.request('/booking')

// Becomes:
cy.request('https://restful-booker.herokuapp.com/booking')

// And this:
cy.request({
  method: 'GET',
  url: '/booking/1'
})

// Becomes:
cy.request({
  method: 'GET',
  url: 'https://restful-booker.herokuapp.com/booking/1'
})

​
Benefits for API Testing

  • Environment Switching: Easily switch between dev, staging, and production APIs
  • Cleaner Code: Shorter request URLs in test files
  • Consistency: All API requests use the same base URL

​
Overriding baseUrl

# Test against different environment
cypress run --config-file cypress.config.api.ts --config baseUrl=https://api-staging.example.com

# Use environment variable
export CYPRESS_BASE_URL=https://api-staging.example.com
cypress run --config-file cypress.config.api.ts

​
API Testing Example

// cypress/e2e/api/GETSpec.cy.ts
describe('GET API Tests', () => {
  it('Should get all bookings', () => {
    cy.request({
      method: 'GET',
      url: '/booking' // Uses baseUrl
    }).then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.be.an('array')
    })
  })

  it('Should get booking by ID', () => {
    cy.request({
      method: 'GET',
      url: '/booking/1'
    }).then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.have.property('firstname')
      expect(response.body).to.have.property('lastname')
    })
  })
})

​
Advanced API Testing Patterns

​
Using setupNodeEvents for API Tests

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: 'https://restful-booker.herokuapp.com',
    specPattern: 'cypress/e2e/api/**/*.cy.ts',
    supportFile: 'cypress/support/e2e.ts',
    watchForFileChanges: false,
    setupNodeEvents(on, config) {
      // Log API test execution
      on('task', {
        logApiRequest(data) {
          console.log('API Request:', data)
          return null
        },
        logApiResponse(data) {
          console.log('API Response:', data)
          return null
        }
      })

      // Set environment-specific variables
      config.env.apiKey = process.env.API_KEY
      config.env.apiSecret = process.env.API_SECRET
      
      return config
    },
  },
});

​
Using Custom Commands for API Testing

// cypress/support/e2e.ts
Cypress.Commands.add('apiLogin', (username: string, password: string) => {
  return cy.request({
    method: 'POST',
    url: '/auth',
    body: {
      username,
      password
    }
  }).then((response) => {
    return response.body.token
  })
})

// Usage in tests
it('Should create booking with auth', () => {
  cy.apiLogin('admin', 'password123').then((token) => {
    cy.request({
      method: 'POST',
      url: '/booking',
      headers: {
        'Cookie': `token=${token}`
      },
      body: {
        firstname: 'John',
        lastname: 'Doe'
      }
    })
  })
})

​
Comparison with UI Config

​
API Config vs UI Config

SettingAPI ConfigUI Config
baseUrlhttps://restful-booker.herokuapp.comhttps://www.saucedemo.com/
specPatterncypress/e2e/api/**/*.cy.tscypress/e2e/ui/**/*.cy.ts
PurposeAPI testingUI/E2E testing
Test TypeHTTP requestsBrowser automation
Common Commandscy.request(), cy.api()cy.visit(), cy.get(), cy.click()
Use CaseBackend endpoints, REST APIsUser interface, user flows
See UI Configuration for details on UI testing setup.

​
Package.json Scripts

Add convenient npm scripts for API testing: 
{
  "scripts": {
    "test:api": "cypress run --config-file cypress.config.api.ts",
    "test:api:open": "cypress open --config-file cypress.config.api.ts",
    "test:api:headed": "cypress run --config-file cypress.config.api.ts --headed",
    "test:all": "npm run test:ui && npm run test:api"
  }
}
Usage: 
npm run test:api         # Run all API tests
npm run test:api:open    # Open Cypress Test Runner for API tests
npm run test:api:headed  # Run API tests with browser visible
npm run test:all         # Run both UI and API tests

​
Environment Variables

Manage API configuration through environment variables: 
// cypress.config.api.ts
import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: process.env.CYPRESS_API_BASE_URL || 'https://restful-booker.herokuapp.com',
    specPattern: 'cypress/e2e/api/**/*.cy.ts',
    supportFile: 'cypress/support/e2e.ts',
    watchForFileChanges: false,
    env: {
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET,
      timeout: 10000
    },
    setupNodeEvents(on, config) {
      return config
    },
  },
});
Usage: 
# Set environment variables
export CYPRESS_API_BASE_URL=https://api-staging.example.com
export API_KEY=your-api-key
export API_SECRET=your-api-secret

# Run tests
npm run test:api

​
Common API Test Patterns

​
CRUD Operations

describe('Booking API - CRUD Operations', () => {
  let bookingId: number

  it('CREATE - Should create a new booking', () => {
    cy.request({
      method: 'POST',
      url: '/booking',
      body: {
        firstname: 'John',
        lastname: 'Doe',
        totalprice: 111,
        depositpaid: true,
        bookingdates: {
          checkin: '2024-01-01',
          checkout: '2024-01-02'
        }
      }
    }).then((response) => {
      expect(response.status).to.eq(200)
      bookingId = response.body.bookingid
    })
  })

  it('READ - Should get the booking', () => {
    cy.request(`/booking/${bookingId}`)
      .its('status')
      .should('eq', 200)
  })

  it('UPDATE - Should update the booking', () => {
    cy.request({
      method: 'PUT',
      url: `/booking/${bookingId}`,
      body: {
        firstname: 'Jane',
        lastname: 'Doe'
      }
    }).its('status').should('eq', 200)
  })

  it('DELETE - Should delete the booking', () => {
    cy.request({
      method: 'DELETE',
      url: `/booking/${bookingId}`
    }).its('status').should('eq', 201)
  })
})

UI Configuration

Configuration for UI testing

Build docs developers (and LLMs) love

Get started for freeTalk to us