🥒 cypress-cucumber-api

Test REST APIs using Gherkin language with Cucumber for Cypress. 47 Steps · Autocomplete · Cross-Platform · JSON Schema Validation

⚡ Install & Setup (2 Steps)

npm install cypress-cucumber-api

// cypress/support/e2e.js — add this line:
require('cypress-cucumber-api');

Done. The postinstall script automatically:

• ✅ Configures .cypress-cucumber-preprocessorrc.json (step discovery)
• ✅ Creates .vscode/settings.json (autocomplete)

Start writing .feature files and run npx cypress run.

🎯 Autocomplete

After npm install, autocomplete works automatically in VS Code:

1. Install the Cucumber (Gherkin) Full Support extension
2. Start typing in .feature files — steps are suggested as you type

Example: Type upload → the API request uploads file "{field}" from "{path}"

For IntelliJ/WebStorm: Point Cucumber Glue to node_modules/cypress-cucumber-api/lib/steps/.

� 47 Steps — Quick Reference

Full reference with keywords: STEPS.md

Building Requests (Given)

Given the API request "url" property is set to "https://api.example.com/posts"
Given the API request "method" property is set to "POST"
Given the API request "body.title" property is set to "Hello"
Given the API request "body.active" property is set to true
Given the API request "body.tags" property is set to a list of "a, b, c"
Given the API request "body" property is set to:
  """
  { "title": "My Post", "body": "Content" }
  """
Given the API request uploads file "avatar" from "test-image.png"
Given the API request "body.parentId" property is set to saved "postId"

Sending Requests (When)

When the user sends the API request
When the user sends the following API request:
  """
  { "url": "https://api.example.com/posts/1", "method": "GET" }
  """

Assertions (Then)

# Status
Then the API response status should equal 200

# Equality
Then the API response "body.title" property should be equal to "Hello"
Then the API response "body.id" property should be equal to 1
Then the API response "body.email" property should be equal to regex ".*@.*"

# Existence & Type
Then the API response "body.id" property should exist
Then the API response "body" property should have a type of "Array"
Then the API response "body.active" property should be true

# Contains
Then the API response "body.title" property should contain "Post"

# Length
Then the API response "body" property should have a length of 100

# Numeric Comparisons
Then the API response "body.id" property should be greater than 0
Then the API response "body.count" property should be less than 100
Then the API response "body" property should have a length greater than 5
Then the API response "body" property should have a length less than 200

# Sorting
Then the API response "body" array should be sorted by "id" in "asc" order

# Headers
Then the API response header "Content-Type" should contain "application/json"
Then the API response header "X-Request-Id" should exist

# Performance / SLA
Then the API response time should be less than 2000 ms

# JSON Schema
Then the API response "body" should match the JSON schema:
  """
  {
    "type": "object",
    "required": ["id", "title"],
    "properties": {
      "id": { "type": "number" },
      "title": { "type": "string" }
    }
  }
  """

# Save & Reuse
Then the API response "body.id" property is saved as "postId"

# Debug
Then the API response is logged
Then the API response "body.data" property is logged
Then the API response headers are logged

Authentication (Given)

Given the user is authenticated
Given the user logs in with username "admin" and password "secret123"
Given the auth token is cleared

Negation: All should steps support should not or shouldn't.

@auth tag: Tag scenarios with @auth to auto-inject the saved token.

📁 Package Structure

lib/
├── index.js              # Entry point: require('cypress-cucumber-api')
├── commands.js            # Custom Cypress commands
└── steps/
    ├── parameterTypes.js  # {should}, {status} parameter types
    ├── request.js         # Given: set, upload, configure
    ├── action.js          # When:  send, execute
    ├── assertion.js       # Then:  equal, exist, contain, type, length
    ├── comparison.js      # Then:  greater, less, sorted
    ├── response.js        # Then:  header, time, performance
    ├── schema.js          # Then:  JSON Schema validation
    ├── auth.js            # Given/Then: login, token, save
    └── debug.js           # Then:  log, inspect, debug

🚀 Development (Clone)

git clone https://github.com/your-org/cypress-cucumber-api.git
cd cypress-cucumber-api
npm install
npm test              # Run all tests (Chrome)
npm run test:electron # Without Chrome
npm run open          # Cypress interactive UI

⚙️ Environment Variables

Create cypress.env.json (gitignored):

{
  "API_BASE_URL": "https://your-api.com",
  "AUTH_ENDPOINT": "/auth/login",
  "AUTH_USERNAME": "your-username",
  "AUTH_PASSWORD": "your-password"
}

🔐 Auth Token Flow

sequenceDiagram
    participant Feature as .feature
    participant Auth as auth.js
    participant Fixture as auth-token.json
    participant API as Your API

    Feature->>Auth: Given the user is authenticated
    Auth->>API: POST /auth/login
    API-->>Auth: { token: "abc123" }
    Auth->>Fixture: Save token

    Note over Feature: Next @auth scenario
    Feature->>Auth: Before hook
    Auth->>Fixture: Read token
    Auth->>Feature: Authorization: Bearer abc123

🖥 Cross-Platform

| Platform | Notes | |----------|-------| | Windows | Use npm run test:env for env vars. Reinstall node_modules if esbuild fails. | | macOS/Linux | Works out of the box. | | CI/CD | Use npm run test:electron (no Chrome needed). |

🛠 Tech Stack

• Cypress · Cucumber Preprocessor · esbuild · Ajv · cross-env

📦 How to Publish

1. Login to npm:

   npm login

2. Publish (Public):

   npm publish --access public

3. Install in other projects:

   npm install cypress-cucumber-api

📝 License

MIT