![](\"https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86\")
\n![](\"https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/count/v2x96h/main&style=flat&logo=cypress\"){kind=icon}
\n\n
\nCypress plugin for effective API testing. Imagine Postman, but in Cypress. Prints out information about the API call in the Cypress App UI.\n
\n\n\n\n### Features\n- cy.api() command that shows information about the API call (URL, headers, response, and more) in the UI\n- all of the info can be viewed in a time-travel snapshots\n- simple table for viewing cookies\n- JSON data object and array folding\n- color coding of methods in UI view and in timeline\n- calculating size of the response\n- [combine API calls with UI](#snapshot-only-mode)\n- [hide sensitive headers and auth information](#hiding-credentials)\n- [`requestMode` to add cy.api() features to cy.request() command](#requestmode---enable-ui-for-cyrequest-command)\n- [TypeScript support](#typescript-support)\n\n### Installation\n\nInstall this package:\n```bash\nnpm i cypress-plugin-api\n# or\nyarn add cypress-plugin-api\n```\n\nImport the plugin into your `cypress/support/e2e.js` file:\n```js\nimport 'cypress-plugin-api'\n// or\nrequire('cypress-plugin-api')\n```\n\n> [!IMPORTANT]\n> **Cypress 16 support is currently limited.** Core `cy.api()` functionality works, but this README and the project's test configuration are not yet fully migrated to Cypress 16. In Cypress 16, configure plugin options with `Cypress.expose()` or `setPluginConfig()`; do not use `Cypress.env()` or per-test/per-suite `env` options for plugin configuration.\n\n### Usage\nYou can now use `cy.api()` command. This command works exactly like `cy.request()` but in addition to calling your API, it will print our information about the API call in your Cypress runner.\n\n#### Snapshot only mode\nIf you want to combine your API calls with your UI test, you can now use `snapshotOnly` mode, that will hide the plugin UI view after command ends. You can access it within the timeline.\n\n`snapshotOnly` mode is set to `false` by default. To set up `snapshotOnly` mode, set it at runtime or in config (Cypress 15.10+ uses `expose` for plugin config):\n\n```js\nit('my UI & API test', () => {\n Cypress.expose('snapshotOnly', true)\n cy.visit('/') // open app\n cy.api('/item') // call api\n cy.get('#myElement') // still able to access element on page\n\n})\n```\n\nor add to your `cypress.config.{js,ts}` file:\n```js\nimport { defineConfig } from 'cypress'\n\nexport default defineConfig({\n e2e: {\n setupNodeEvents(on, config) {\n },\n expose: {\n snapshotOnly: true\n }\n },\n})\n```\n\n#### Hiding credentials\nBy default, values are **shown** in the UI so you can see them when running locally. When you use **cy.env()** for secrets (or want to hide in CI), turn on **HideCredentials** so those values are masked (e.g. `****`) in request headers, auth, body, query params, and the cURL tab.\n\n- **See values locally:** leave `hideCredentials` unset or `false` (default).\n- **Hide credentials from `cy.env()` (recommended for secrets):**\n - **Globally via config** (applies to all specs):\n\n ```js\n // cypress.config.{js,ts}\n import { defineConfig } from 'cypress'\n\n export default defineConfig({\n e2e: {\n env: {\n // credentials passed from cy.env() will be masked in the plugin UI\n hideCredentials: true,\n },\n },\n })\n ```\n\n - **Per spec / per suite:** use any of these:\n - **Via env** (in a `before()` or at the start of the test):\n ```js\n Cypress.env('hideCredentials', true)\n // optional: Cypress.env('hideCredentialsOptions', { headers: ['authorization'], auth: ['pass'], body: ['username'], qs: ['password'] })\n ```\n - Or **test-level env** (env applies only to that test):\n ```js\n it('my secret test', { env: { hideCredentials: true } }, () => {\n cy.env(['myToken']).then(({ myToken }) => {\n cy.api({ url: '/', headers: { authorization: myToken } })\n })\n })\n ```\n - On Cypress 15.10+: `Cypress.expose('hideCredentials', true)`\n - Or the plugin helper: `setPluginConfig('hideCredentials', true)`\n\nExample: use **cy.env()** for the token and **HideCredentials** so it’s masked in the UI:\n\n```js\nit('my secret test', () => {\n // Option 1 (Cypress 15.10+)\n Cypress.expose('hideCredentials', true)\n\n // Option 2 (helper from this plugin, also works when Cypress.expose is not available)\n // setPluginConfig('hideCredentials', true)\n\n cy.env(['myToken']).then(({ myToken }) => {\n cy.api({\n url: '/',\n headers: {\n authorization: myToken\n }\n })\n })\n})\n```\n\nThe result will look like this:\n\n\n\nUse **hideCredentialsOptions** to choose which keys are masked (when not set, default keys include `authorization`, `password`, `user`, `pass`, `token`, `apiKey`). You can set it via **config env** or per spec:\n\n- **Config env (global):**\n\n ```js\n // cypress.config.{js,ts}\n import { defineConfig } from 'cypress'\n\n export default defineConfig({\n e2e: {\n env: {\n hideCredentials: true,\n hideCredentialsOptions: {\n headers: ['authorization'],\n auth: ['pass'],\n body: ['username'],\n qs: ['password'],\n },\n },\n },\n })\n ```\n\n- **Per spec** (use one of these):\n\n **Via env** (in a `before()` or at the start of the test):\n\n ```js\n Cypress.env('hideCredentials', true)\n Cypress.env('hideCredentialsOptions', {\n headers: ['authorization'],\n auth: ['pass'],\n body: ['username'],\n qs: ['password']\n })\n ```\n\n **Or via expose / helper inside the test:**\n\n ```js\n it('my secret test', () => {\n // Option 1: Cypress 15.10+\n Cypress.expose('hideCredentialsOptions', {\n headers: ['authorization'],\n auth: ['pass'],\n body: ['username'],\n qs: ['password']\n })\n\n // Option 2: helper from this plugin\n // setPluginConfig('hideCredentialsOptions', {\n // headers: ['authorization'],\n // auth: ['pass'],\n // body: ['username'],\n // qs: ['password']\n // })\n\n cy.env(['myToken', 'myPass', 'myUser', 'password']).then(\n ({ myToken, myPass, myUser, password }) => {\n cy.api({\n url: '/',\n headers: { authorization: myToken },\n auth: { pass: myPass },\n body: { username: myUser },\n qs: { password }\n })\n }\n )\n })\n ```\n\n#### `requestMode` - enable UI for `cy.request()` command\nWhen `false` (default), only `cy.api()` shows the plugin UI. When set to `true`, `cy.request()` also displays the same UI for every `cy.request()` call.\n\n#### TypeScript support\nIn most cases, types work just by installing plugin, but you can add the types to your `tsconfig.json`\n```json\n{\n \"types\": [\"cypress-plugin-api\"]\n}\n```\nThis will add types for `cy.api()` command, it’s returned values as well as `env` properties.\n\n### Issues\nAll the issues can be found on [issues page](https://github.com/filiphric/cypress-plugin-api/issues), feel free to open any new ones or contribute with your own code.\n\n\n\n...powered by coffee and love ❤️ Filip Hric\n
\n","readmeFilename":"README.md"}