{"id":15996,"library":"cypress-plugin-api","title":"Cypress API Testing Plugin","description":"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.","status":"active","version":"2.11.2","language":"javascript","source_language":"en","source_url":"https://github.com/filiphric/cypress-plugin-api","tags":["javascript","cypress","api","testing","plugin","typescript"],"install":[{"cmd":"npm install cypress-plugin-api","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-plugin-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-plugin-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for the plugin to function within the Cypress test runner.","package":"cypress","optional":false}],"imports":[{"note":"The plugin augments the Cypress `cy` object with `cy.api()`. This import is for its side effects and does not export named symbols directly for `cy.api`.","wrong":"import { api } from 'cypress-plugin-api'","symbol":"*","correct":"import 'cypress-plugin-api'"},{"note":"CommonJS equivalent for importing the plugin. Like ESM, it's primarily for side effects to extend the `cy` object.","wrong":"const api = require('cypress-plugin-api')","symbol":"*","correct":"require('cypress-plugin-api')"},{"note":"While `import 'cypress-plugin-api'` typically handles type augmentation in modern TypeScript setups, explicit reference directives or ensuring `tsconfig.json` includes `cypress-plugin-api` in `types` or `compilerOptions.typeRoots` might be necessary in specific configurations to get IntelliSense for `cy.api()`.","symbol":"Cypress global types","correct":"/// <reference types=\"cypress-plugin-api\" />"}],"quickstart":{"code":"import { defineConfig } from 'cypress'\n\n// cypress.config.ts\nexport default defineConfig({\n  e2e: {\n    setupNodeEvents(on, config) {\n      // Optional: Add an event listener to log something during setup\n      on('task', {\n        log(message) {\n          console.log(message)\n          return null\n        },\n      })\n      return config\n    },\n    baseUrl: 'http://localhost:3000', // Ensure your API is running here\n    env: {\n      snapshotOnly: false, // Default: shows full UI for API calls\n      hideCredentials: true,\n      myAuthToken: 'secret-token-123',\n      apiUser: 'testuser',\n      apiPass: 'testpassword',\n    }\n  },\n})\n\n// cypress/support/e2e.ts\nimport 'cypress-plugin-api'\n// You can also add other Cypress commands or configurations here\n\n// cypress/e2e/api.cy.ts\ndescribe('Cypress Plugin API features', () => {\n  beforeEach(() => {\n    // Assuming your app serves simple endpoints for demonstration\n    // For a real app, ensure your dev server is running before tests\n  })\n\n  it('should make a GET API call and display full UI details', () => {\n    cy.api('/data').then((response) => {\n      expect(response.status).to.eq(200)\n      expect(response.body).to.have.property('message', 'Hello from API')\n    })\n  })\n\n  it('should make a POST API call with hidden credentials and custom options', {\n    env: {\n      hideCredentials: true,\n      hideCredentialsOptions: {\n        headers: ['authorization'],\n        body: ['password'],\n        query: ['apiKey']\n      }\n    }\n  }, () => {\n    cy.api({\n      method: 'POST',\n      url: '/login',\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': `Bearer ${Cypress.env('myAuthToken')}` // This header will be hidden\n      },\n      body: {\n        username: Cypress.env('apiUser'),\n        password: Cypress.env('apiPass') // This body field will be hidden\n      },\n      qs: {\n        apiKey: 'super-secret-key' // This query param will be hidden\n      }\n    }).then((response) => {\n      expect(response.status).to.eq(200)\n      expect(response.body).to.have.property('success', true)\n    })\n  })\n\n  it('should combine UI and API testing with snapshotOnly mode', { env: { snapshotOnly: true } }, () => {\n    cy.visit('/') // Navigate to your web application\n    cy.get('h1').should('contain', 'Welcome') // Interact with UI\n\n    cy.api('/users').then((response) => {\n      expect(response.status).to.eq(200)\n      expect(response.body).to.be.an('array')\n    })\n\n    cy.get('#user-list').should('exist') // More UI interaction after API call\n  })\n})","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Cypress installation to version 10 or higher (e.g., `npm install cypress@latest`).","message":"This plugin requires Cypress version 10 or newer. Installing with older Cypress versions will result in command `cy.api()` not being available or unexpected behavior.","severity":"breaking","affected_versions":"<10.0.0"},{"fix":"Ensure `import 'cypress-plugin-api'` (ESM) or `require('cypress-plugin-api')` (CommonJS) is present in your support file (e.g., `cypress/support/e2e.ts`).","message":"The `cy.api()` command is added globally by importing the plugin in `cypress/support/e2e.{js,ts}`. Failing to import it will result in `cy.api is not a function` errors.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Set `env: { requestMode: true }` in your `cypress.config.{js,ts}` file or per-test configuration.","message":"The `requestMode` option, which applies `cy.api()`'s UI features to `cy.request()`, is `false` by default. If you intend for all `cy.request()` calls to display in the plugin's UI, you must explicitly enable this option in your Cypress configuration.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Carefully define all fields you wish to hide in the `hideCredentialsOptions` array if `hideCredentials: true` is also enabled, as it will take precedence over defaults.","message":"When using both `hideCredentials: true` and `hideCredentialsOptions`, the `hideCredentialsOptions` will override the default sensitive fields hidden by `hideCredentials`. Ensure all desired fields are explicitly listed in `hideCredentialsOptions` if you are using it.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure your `tsconfig.json` properly includes the plugin's types (e.g., in `compilerOptions.types` or by including `cypress-plugin-api` in `typeRoots`). If using explicit reference directives, ensure `/// <reference types=\"cypress-plugin-api\" />` is present.","message":"Incorrect type imports or `tsconfig.json` configuration can lead to TypeScript errors for `cy.api()` or `Cypress.env()` properties, despite the plugin shipping with types. Recent releases have specifically addressed type-related bugs.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Add `import 'cypress-plugin-api'` to your `cypress/support/e2e.ts` (or `.js`) file.","cause":"The `cypress-plugin-api` plugin has not been correctly imported into your Cypress support file.","error":"TypeError: cy.api is not a function"},{"fix":"Ensure the package is installed via `npm install cypress-plugin-api` or `yarn add cypress-plugin-api`. Check your `cypress/support/e2e.{js,ts}` path and `tsconfig.json` if applicable.","cause":"The `cypress-plugin-api` package is either not installed or webpack cannot resolve its path.","error":"Error: Webpack compilation failed: Cannot find module 'cypress-plugin-api'"},{"fix":"Verify that `cypress-plugin-api` is listed in the `types` array of your `tsconfig.json` (e.g., `\"types\": [\"cypress\", \"cypress-plugin-api\"]`) or that `/// <reference types=\"cypress-plugin-api\" />` is in a relevant `.d.ts` file or `cypress/support/e2e.ts`.","cause":"TypeScript is not correctly picking up the type augmentations provided by `cypress-plugin-api` for the `cy` object.","error":"Property 'api' does not exist on type 'Chainable<any>'"}],"ecosystem":"npm"}