{"_id":"cypress-schema-validator","_rev":"4-9c40890655dc82bc8948e38691f4d26d","name":"cypress-schema-validator","dist-tags":{"latest":"2.0.0"},"versions":{"0.0.1":{"name":"cypress-schema-validator","version":"0.0.1","keywords":["plugin","cypress","ajv","zod","schema","validator","json"],"author":{"name":"Sebastian Clavijo Suero"},"license":"MIT","_id":"cypress-schema-validator@0.0.1","maintainers":[{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"}],"homepage":"https://github.com/sclavijosuero/cypress-schema-validator#readme","bugs":{"url":"https://github.com/sclavijosuero/cypress-schema-validator/issues"},"dist":{"shasum":"8936be62a1dcefbe58b5f473471ea562051de4ae","tarball":"https://registry.npmjs.org/cypress-schema-validator/-/cypress-schema-validator-0.0.1.tgz","fileCount":3,"integrity":"sha512-eLceMsDpWaGLBoU3v2iLzjqkMOoWBcLXezXMdXQM0awH6+fFQJtxRFAvNLlGDqIjfdjVFs2gtp4yeCEGD2kBug==","signatures":[{"sig":"MEQCICggwGakLAOInmzOZdyuCnJADUj8p3e4pTWTsX0Z/6YjAiB3/fxN07i3bfqm73betoEpkmU5zLELlHyzofkOORk8pQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2715},"main":"src/index.js","types":"src/index.d.ts","gitHead":"7773c09f1caf4aea615e74a57effbb74505a4c00","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"},"repository":{"url":"git+https://github.com/sclavijosuero/cypress-schema-validator.git","type":"git"},"_npmVersion":"10.9.2","description":"Lightweight Cypress plugin for API schema validation. It leverages both the AJV validator (for plain JSON schemas, Swagger documents, and OpenAPI schemas) and the Zod validator (for Zod schemas).","directories":{},"_nodeVersion":"22.13.1","dependencies":{"highlight.js":"^11.10.0","cypress-plugin-api":"^2.11.2","core-ajv-schema-validator":"^1.0.0","core-zod-schema-validator":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"cypress":"^13.17.0","@bahmutov/cy-api":"^2.2.6"},"_npmOperationalInternal":{"tmp":"tmp/cypress-schema-validator_0.0.1_1747630066798_0.9218393450335192","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"cypress-schema-validator","version":"1.0.0","keywords":["plugin","cypress","ajv","zod","schema","validator","json"],"author":{"name":"Sebastian Clavijo Suero"},"license":"MIT","_id":"cypress-schema-validator@1.0.0","maintainers":[{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"}],"homepage":"https://github.com/sclavijosuero/cypress-schema-validator#readme","bugs":{"url":"https://github.com/sclavijosuero/cypress-schema-validator/issues"},"dist":{"shasum":"897d9a86bfb13f594198ec200e7f806c6efc55a7","tarball":"https://registry.npmjs.org/cypress-schema-validator/-/cypress-schema-validator-1.0.0.tgz","fileCount":70,"integrity":"sha512-hwxscpmbvVAmeU2ZseCW1gMQJpeR1sw1wmF5h8ozHzgZeeY1bXWE+4Qk9HYUk9fR7SdN8t0lHPre0Ir+f6hg+g==","signatures":[{"sig":"MEYCIQCuEPsgydkoqy1fnGXtP2Sb0+lcOemO1WSEpv027KgS4wIhAO1AonVOW7fu3nINtTSxEyM1gk1QgFjs8QSd0cL4bIS1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18385217},"main":"src/index.js","types":"src/index.d.ts","gitHead":"172caa4e7faa895423c5c430dcb0c43f3e4da4c6","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"},"repository":{"url":"git+https://github.com/sclavijosuero/cypress-schema-validator.git","type":"git"},"_npmVersion":"10.9.2","description":"Lightweight Cypress plugin for API schema validation. It leverages both the AJV validator (for plain JSON schemas, Swagger documents, and OpenAPI schemas) and the Zod validator (for Zod schemas).","directories":{},"_nodeVersion":"22.13.1","dependencies":{"highlight.js":"^11.10.0","cypress-plugin-api":"^2.11.2","core-ajv-schema-validator":"^1.0.0","core-zod-schema-validator":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.25.46","cypress":"^13.17.0","@bahmutov/cy-api":"^2.2.6"},"_npmOperationalInternal":{"tmp":"tmp/cypress-schema-validator_1.0.0_1749440436644_0.1599264165611256","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"cypress-schema-validator","version":"1.0.1","keywords":["plugin","cypress","ajv","zod","schema","validator","json"],"author":{"name":"Sebastian Clavijo Suero"},"license":"MIT","_id":"cypress-schema-validator@1.0.1","maintainers":[{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"}],"homepage":"https://github.com/sclavijosuero/cypress-schema-validator#readme","bugs":{"url":"https://github.com/sclavijosuero/cypress-schema-validator/issues"},"dist":{"shasum":"5cedcc8c7624d66a7b4ef7561455da45fcc6e79c","tarball":"https://registry.npmjs.org/cypress-schema-validator/-/cypress-schema-validator-1.0.1.tgz","fileCount":70,"integrity":"sha512-BmAARC19Zt8m0235eNPihzMgFrFP1itY3/Dy+3yOhrAAoP1Fvqu37/IvzavTxXyRz6mViCjaTgqG4qceVqjyUw==","signatures":[{"sig":"MEQCIDF3RbItjoEmeXaautZW6sRnmJwbuJ08WoLr07Virv1yAiA79d0DFcwk7EZFTHSbWO8vVRNyCbmvWhPgxAilnHrUyA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18385348},"main":"src/index.js","types":"src/index.d.ts","gitHead":"d5a1cdd56b89e79099d390297af3a7a953c6d9e3","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"},"repository":{"url":"git+https://github.com/sclavijosuero/cypress-schema-validator.git","type":"git"},"_npmVersion":"10.9.2","description":"Lightweight Cypress plugin for API schema validation. It leverages both the AJV validator (for plain JSON schemas, Swagger documents, and OpenAPI schemas) and the Zod validator (for Zod schemas).","directories":{},"_nodeVersion":"22.13.1","dependencies":{"highlight.js":"^11.10.0","cypress-plugin-api":"^2.11.2","core-ajv-schema-validator":"^1.0.0","core-zod-schema-validator":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.25.46","cypress":"^13.17.0","@bahmutov/cy-api":"^2.2.6"},"_npmOperationalInternal":{"tmp":"tmp/cypress-schema-validator_1.0.1_1754171342362_0.4889350667346817","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"cypress-schema-validator","version":"2.0.0","description":"Lightweight Cypress plugin for API schema validation. It leverages both the AJV validator (for plain JSON schemas, Swagger documents, and OpenAPI schemas) and the Zod validator (for Zod schemas).","main":"src/index.js","types":"src/index.d.ts","scripts":{"cy:open":"cypress open --e2e --browser chrome","cy:run":"cypress run --e2e --browser chrome","cy:open:electron":"cypress open --e2e","cy:run:electron":"cypress run --e2e"},"repository":{"type":"git","url":"git+https://github.com/sclavijosuero/cypress-schema-validator.git"},"keywords":["plugin","cypress","ajv","zod","schema","validator","json"],"author":{"name":"Sebastian Clavijo Suero"},"license":"MIT","bugs":{"url":"https://github.com/sclavijosuero/cypress-schema-validator/issues"},"homepage":"https://github.com/sclavijosuero/cypress-schema-validator#readme","devDependencies":{"@bahmutov/cy-api":"^2.3.0","cypress":"^15.16.0","zod":"^3.25.46"},"dependencies":{"core-ajv-schema-validator":"^1.0.0","core-zod-schema-validator":"^1.0.0","highlight.js":"^11.11.1"},"_id":"cypress-schema-validator@2.0.0","gitHead":"f41519b1b0df1feb80c3f3771d01a63aa6d223ab","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-n38icgholuDGLq/YSB1m4VeZkp740NhgkPuB7HaaaUFWqyr62+GUpiYOYvxvmVNsIWYLPmweX+jtgreTas7xDg==","shasum":"f36142b7b25e9b6d2e10147582533449bfd7d95b","tarball":"https://registry.npmjs.org/cypress-schema-validator/-/cypress-schema-validator-2.0.0.tgz","fileCount":70,"unpackedSize":18392600,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCeiAs0Zz/w+vGgC+H0NvwOnkrdKFLZkDqZMTwBjLCzGwIhALE/bKexH4nyy9/bcV6S3Nyd+REhmOC5UPO3G3hCYqUP"}]},"_npmUser":{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"},"directories":{},"maintainers":[{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cypress-schema-validator_2.0.0_1780795974106_0.5663797709180238"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-19T04:47:46.797Z","modified":"2026-06-07T01:32:54.555Z","0.0.1":"2025-05-19T04:47:46.989Z","1.0.0":"2025-06-09T03:40:37.052Z","1.0.1":"2025-08-02T21:49:02.772Z","2.0.0":"2026-06-07T01:32:54.460Z"},"bugs":{"url":"https://github.com/sclavijosuero/cypress-schema-validator/issues"},"author":{"name":"Sebastian Clavijo Suero"},"license":"MIT","homepage":"https://github.com/sclavijosuero/cypress-schema-validator#readme","keywords":["plugin","cypress","ajv","zod","schema","validator","json"],"repository":{"type":"git","url":"git+https://github.com/sclavijosuero/cypress-schema-validator.git"},"description":"Lightweight Cypress plugin for API schema validation. It leverages both the AJV validator (for plain JSON schemas, Swagger documents, and OpenAPI schemas) and the Zod validator (for Zod schemas).","maintainers":[{"name":"sclavijosuero","email":"sclavijosuero@gmail.com"}],"readme":"# cypress-schema-validator\r\n\r\nA Cypress plugin for API schema validation. It leverages the core-ajv-schema-validator powered by the AJV package (for plain JSON schemas, Swagger documents, and OpenAPI schemas) as well as the core-zod-schema-validator powered by the ZOD package (for Zod schemas).\r\n\r\n\r\n![Overview](videos/overview.gif) \r\n\r\n&nbsp; \r\n\r\n## MAIN FEATURES\r\n\r\n✔️ Cypress command **`cy.validateSchema()`** (and alias **`cy.validateSchemaAjv()`**) performs a JSON Schema Validation and reports errors in the responses of network requests made with `cy.request()`.\r\n   - Schemas are provided as JSON objects, which can come from a Cypress fixture.\r\n   - Supports **Plain JSON schemas**, **OpenAPI 3.x schema documents** and **Swagger 2.0 schema documents**.\r\n   - Utilizes the **core-ajv-schema-validator**, leveraging the **Ajv JSON Schema Validator** .\r\n\r\n✔️ Cypress command **`cy.validateSchemaZod()`** identifies and reports Zod schema validation errors in the responses of network requests made with `cy.request()`.\r\n   - Schemas are provided as **Zod objects**, which can come from a Cypress fixture.\r\n   - Uses the **core-zod-schema-validator** , leveraging the **Zod Schema Validator**.\r\n  \r\n✔️ The commands are chainable with `cy.request()` and yield the original API response.\r\n\r\n✔️ Provides a summary of schema errors as well as a list of individual validation errors directly in the Cypress log.\r\n  \r\n✔️ By clicking on the schema errors summary in the Cypress log, the DevTools console outputs:\r\n   -  Total number of schema errors.\r\n   -  Full list of schema errors as provided by **Ajv** or **Zod** depending on the selected command.\r\n   -  A nested tree view of the validated data, clearly indicating the errors and where they occurred in an easy-to-understand format.\r\n\r\n✔️ Presents results to the user in a consistent format, regardless of whether the AJV Schema Validator or ZOD Validator is used.\r\n\r\n✔️ Output the schema errors in the terminal when executing in `run` mode.\r\n\r\n✔️ Allow custom styles (icons and text colors) to match the user's preferences for distinguishing schema errors.\r\n\r\n✔️ Environment variable **`disableSchemaValidation`** to disable schema validation in your tests.\r\n\r\n✔️ Environment variable **`generateReport`** to generate a report of the schema validation (JSON). - **_New in v2.0.0_**\r\n\r\n✔️ Fully integrates with **Gleb Bahmutov**'s [@bahmutov/cy-api](https://github.com/bahmutov/cy-api) plugin, allowing JSON schema validations to be performed immediately after the `cy.api()` command.\r\n   - With the environment variable **`enableMismatchesOnUI`** enabled, schema errors are displayed directly in the user interface of these plugins for enhanced visibility.\r\n\r\n&nbsp; \r\n\r\n> ⭐⭐⭐ Example usage with **@bahmutov/cy-api** plugin\r\n> \r\n> `cy.api('/users/1').validateSchema(schema);`\r\n>\r\n> For detailed examples of `cypress-schema-validator` used with the `@bahmutov/cy-api` plugin in the Swagger Petstore API, refer to the sample test files: [test-multiple-api-with-cy-api-override-style.js](cypress/e2etest-multiple-api-with-cy-api-override-style.js) and [test-multiple-api-with-cy-api.js](cypress/e2e/test-multiple-api-with-cy-api.js).\r\n\r\n&nbsp; \r\n\r\n> ⚠️⚠️⚠️ Deprecation Notice: **cypress-plugin-api**\r\n>   Removed in `cypress-schema-validator` v2.0.0 due to Cypress v16 compatibility issues (`cy.env()` and `Cypress.exposed()`). Support is limited to `cypress-schema-validator` v1.0.1 and below.\r\n\r\n&nbsp;\r\n\r\n> ✔️✔️✔️ **IMPORTANT NOTE:** The `cypress-schema-validator` plugin replaces the legacy `cypress-ajv-schema-validator`. It maintains full backward compatibility while extending the API to support **Zod Schema Validation** in addition to **AJV Schema Validation**. \r\n\r\n&nbsp; \r\n\r\n## TABLE OF CONTENTS\r\n\r\n- [cypress-schema-validator](#cypress-schema-validator)\r\n  - [MAIN FEATURES](#main-features)\r\n  - [COMPATIBILITY](#compatibility)\r\n  - [INSTALLATION](#installation)\r\n  - [CONFIGURATION](#configuration)\r\n  - [ABOUT JSON SCHEMAS AND SCHEMA VALIDATORS](#about-json-schemas-and-schema-validators)\r\n    - [JSON Schema](#json-schema)\r\n    - [OpenAPI 3.x and Swagger 2.0 Schema Documents](#openapi-3x-and-swagger-20-schema-documents)\r\n    - [Ajv JSON Schema Validator](#ajv-json-schema-validator)\r\n    - [Zod Schema Validator](#zod-schema-validator)\r\n  - [API REFERENCE](#api-reference)\r\n    - [`cy.validateSchema(schema[, path[, issuesStyles]])` (and alias `cy.validateSchemaAjv(schema[, path[, issuesStyles]])`)](#cyvalidateschemaschema-path-issuesstyles-and-alias-cyvalidateschemaajvschema-path-issuesstyles)\r\n      - [Parameters](#parameters)\r\n      - [Returns](#returns)\r\n      - [Throws](#throws)\r\n      - [Path Parameter](#path-parameter)\r\n    - [`cy.validateSchemaZod(schema[, issuesStyles])`](#cyvalidateschemazodschema-issuesstyles)\r\n      - [Parameters](#parameters-1)\r\n      - [Returns](#returns-1)\r\n      - [Throws](#throws-1)\r\n  - [USAGE EXAMPLES](#usage-examples)\r\n    - [Examples For AJV Schema Validation USAGE-EXAMPLES-AJV.md.](#examples-for-ajv-schema-validation-usage-examples-ajvmd)\r\n    - [Examples For ZOD Schema Validation USAGE-EXAMPLES-ZOD.md.](#examples-for-zod-schema-validation-usage-examples-zodmd)\r\n  - [SCHEMA VALIDATION RESULTS](#schema-validation-results)\r\n    - [Results Outcome (Passed/Failed)](#results-outcome-passedfailed)\r\n      - [Test Passed ✔️](#test-passed-️)\r\n      - [Test Failed ❌](#test-failed-)\r\n        - [Detailed Error View in the Console](#detailed-error-view-in-the-console)\r\n        - [Test Failed with More than 10 Errors ➕](#test-failed-with-more-than-10-errors-)\r\n        - [Schema errors in the Terminal when executing in `run` mode](#schema-errors-in-the-terminal-when-executing-in-run-mode)\r\n    - [Integration with other Cypress API Plugins](#integration-with-other-cypress-api-plugins)\r\n      - [Integration with Gleb Bahmutov's `@bahmutov/cy-api` Plugin](#integration-with-gleb-bahmutovs-bahmutovcy-api-plugin)\r\n      - [Integration with Filip Hric's `cypress-plugin-api`](#integration-with-filip-hrics-cypress-plugin-api)\r\n    - [Custom Styles for Validation Errors](#custom-styles-for-validation-errors)\r\n    - [Results for AJV Schema Validation vs ZOD Schema Validation](#results-for-ajv-schema-validation-vs-zod-schema-validation)\r\n  - [DISABLE JSON SCHEMA VALIDATION IN YOUR TESTS](#disable-json-schema-validation-in-your-tests)\r\n  - [LICENSE](#license)\r\n  - [CONTRIBUTING](#contributing)\r\n  - [CHANGELOG](#changelog)\r\n    - [\\[1.0.0\\]](#100)\r\n    - [\\[cypress-ajv-schema-validator 2.0.1\\]](#cypress-ajv-schema-validator-201)\r\n  - [EXTERNAL REFERENCES](#external-references)\r\n    - [For cypress-ajv-schema-validator (predecessor plugin)](#for-cypress-ajv-schema-validator-predecessor-plugin)\r\n\r\n&nbsp; \r\n\r\n## COMPATIBILITY\r\n\r\n### Cypress v15.10+\r\n- Use **cypress-schema-validator** *v*2.0.0 or greater\r\n- Use of `cy.env` and `Cypress.expose` (https://docs.cypress.io/app/references/migration-guide#Migrating-away-from-Cypressenv)\r\n- Support integration with the latest version of `@bahmutov/cy-api`\r\n- Decommissioned integration with `cypress-plugin-api`, which has not been updated to support Cypress v16.\r\n\r\n### Cypress v12.0.0 - v15.9.0\r\n- Ajv 8.16.0 or higher\r\n- ajv-formats 3.0.1 or higher\r\n- Support integration with `@bahmutov/cy-api` and `cypress-plugin-api` plugins\r\n  \r\nFor Typescript projects also:\r\n- TypeScript 4.5+\r\n- You must enable strict mode in your `tsconfig.json`. This is a best practice for all TypeScript projects.\r\n\r\n\r\n##  INSTALLATION \r\n\r\n```sh\r\nnpm install -D cypress-schema-validator\r\n```\r\n\r\n## CONFIGURATION\r\n\r\n- Configure the report directory using the `reportsFolder` parameter in `cypress.config.js`. Defaults to `cypress/reports`.\r\n\r\n  ```js\r\n  module.exports = defineConfig({\r\n     // New config option for cypress-schema-validator v2.0.0\r\n    reportsFolder: 'cypress/reports',\r\n    \r\n    // Rest of your configuration\r\n    // [...]\r\n  })\r\n  ```\r\n\r\n- Add the following lines either to your `cypress/support/commands.js` to include the custom command and function globally, or directly in the test file that will host the schema validation tests:\r\n\r\n  ```js\r\n  import 'cypress-schema-validator';\r\n  ```\r\n\r\n- To **disable schema validation** even when the `cy.validateSchema()` command is present in the test, set the Cypress environment variable or exposed variable **`disableSchemaValidation`** to **`true`**. By default, schema validation is enabled.\r\n\r\n- To **enable the display of schema errors** directly in the user interfaces of the `@bahmutov/cy-api` and `cypress-plugin-api` plugins, set the Cypress environment variable or exposed variable **`enableMismatchesOnUI`** to **`true`**. By default, this feature is disabled.\r\n\r\n- To **enable the generation of JSON schema validation reports**, set the generateReport environment or exposed variable to json (disabled by default). Only json is supported at this time.\r\n\r\n   > ✳️Starting in Cypress v15.10.0, you can configure **cypress-schema-validator** using the two environment variables `disableSchemaValidation` and `enableMismatchesOnUI`. These can be defined either as **regular (non-exposed)** or **exposed** Cypress environment variables.\r\n   > This ensures **full backward compatibility** with previous versions and existing projects, configurations, and tests created using versions of cypress-schema-validator prior to Cypress v15.10.0.**.\r\n   >\r\n   > **NOTE: If an environment variable is defined both as exposed and non-exposed, the non-exposed value takes priority.**\r\n\r\n&nbsp; \r\n\r\n## ABOUT JSON SCHEMAS AND SCHEMA VALIDATORS\r\n\r\n### JSON Schema\r\n\r\nJSON Schema is a hierarchical, declarative language that describes and validates JSON data.\r\n\r\n### OpenAPI 3.x and Swagger 2.0 Schema Documents\r\n\r\nThe OpenAPI Specification (formerly Swagger Specification) are schema documents to describe your entire API (in JSON format or XML format). So a schema document will contain multiple schemas, one for each supported combination of **_Endpoint - Method - Expected Response Status_** (also called _path_) by that API.\r\n\r\n### Ajv JSON Schema Validator\r\n\r\nAJV, or Another JSON Schema Validator, is a JavaScript library that validates data objects against a JSON Schema structure.\r\n\r\nIt was chosen as the core engine of the `core-ajv-schema-validator` plugin because of its versatility, speed, capabilities, continuous maintenance, and excellent documentation. For more information on Ajv, visit the [Ajv official website](https://ajv.js.org/).\r\n\r\nAjv supports validation of the following schema formats: **JSON Schema**, **OpenAPI 3.x** specification, and **Swagger 2.0** specification. However, Ajv needs to be provided with the specific schema to be validated for an endpoint, method, and expected response; it cannot process a full OpenAPI 3.x or Swagger 2.0 schema document by itself.\r\n\r\nThe `cypress-schema-validator` plugin simplifies this by obtaining the correct schema definition for the endpoint you want to test. You just need to provide the full schema document (OpenAPI or Swagger) and the path to the schema definition of the service you want to validate for your API (_Endpoint - Method - Expected Response Status_).\r\n\r\n> **Note:** The Ajv instance used in this plugin (`cypress-schema-validator`) is configured with the options `{ allErrors: true, strict: false }` to display all validation errors and disable strict mode.\r\n\r\n### Zod Schema Validator\r\n\r\nZod is a TypeScript-first schema declaration and validation library that allows defining schemas directly in TypeScript while providing robust type detection within your code.\r\n\r\nIt was chosen as the core engine of the `core-zod-schema-validator` plugin due to its developer-friendly nature, versatility, and seamless integration into modern TypeScript workflows. Its intuitive API, extensive validation capabilities, and active maintenance make it a powerful tool for schema validation. For more information on Zod, visit the [Zod official website](https://zod.dev/).\r\n\r\nThe `cypress-schema-validator` plugin integrates Zod by enabling developers to supply Zod schemas directly for validation. You define the schema for the service and endpoint you want to validate, and the plugin ensures that the API responses adhere to the specified structure.\r\n\r\n&nbsp; \r\n\r\n## API REFERENCE\r\n\r\n&nbsp; \r\n\r\n### `cy.validateSchema(schema[, path[, issuesStyles]])` (and alias `cy.validateSchemaAjv(schema[, path[, issuesStyles]])`)\r\n\r\nIt validates the JSON data in the response body against the provided **Plain JSON schema**, **OpenAPI** and **Swagger** document format using the **AJV Schema Validator**.\r\nIt is expected to be chained to an API response (from a `cy.request()` or `cy.api()`).\r\n\r\n#### Parameters\r\n\r\n- **`schema`** (object)\r\n  The schema to validate against. Supported formats are plain JSON schema, Swagger, and OpenAPI documents.\r\n- **`path`** (object, optional)\r\n  This second parameter represents the path to the schema definition in a Swagger or OpenAPI document and is determined by three properties:\r\n  - **`endpoint`** (string, optional): The endpoint path.\r\n  - **`method`** (string, optional): The HTTP method. Defaults to 'GET'.\r\n  - **`status`** (integer, optional): The response status code. If not provided, defaults to 200.\r\n- **`issuesStyles`** (object, optional)\r\n   An object with the icons and HEX colors used to flag the issues. If not provided, it will use the default icons defined in the plugin.\r\n   Includes the following properties:\r\n  - **`iconPropertyError`** (string, optional): The icon used to flag type errors in the data. Support emojis.\r\n  - **`iconPropertyMissing`** (string, optional): The icon used to flag type errors in the data. Support emojis.\r\n  - **`colorPropertyError`** (string, optional): The HEX color used to flag the property error.\r\n  - **`colorPropertyMissing`** (string, optional): The HEX color used to flag the missing property.\r\n \r\n#### Returns\r\n\r\n- `Cypress.Chainable`: The response object wrapped in a `Cypress.Chainable`.\r\n\r\n#### Throws\r\n\r\n- `Error`: If any of the required parameters are missing or if the schema or schema definition is not found.\r\n\r\n&nbsp; \r\n\r\nExample providing a **_Plain JSON schema_**:\r\n\r\n```js\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchema(schema);\r\n```\r\nor\r\n```js\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchemaAjv(schema);\r\n```\r\n\r\nExample providing a **_Plain JSON schema and custom `issuesStyles`_**:\r\n\r\n```js\r\nconst issuesStylesOverride = {\r\n  iconPropertyError: '🟦', colorPropertyError: '#5178eb',\r\n  iconPropertyMissing: '🟪', colorPropertyMissing: '#800080'\r\n}\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchema(schema, undefined, issuesStylesOverride);\r\n```\r\nor\r\n```js\r\nconst issuesStylesOverride = {\r\n  iconPropertyError: '🟦', colorPropertyError: '#5178eb',\r\n  iconPropertyMissing: '🟪', colorPropertyMissing: '#800080'\r\n}\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchemaAjv(schema, undefined, issuesStylesOverride);\r\n```\r\n\r\nExample providing an **_OpenAPI 3.0.1 or Swagger 2.0 schema documents and path to the schema definition_**:\r\n\r\n```js\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchema(schema, { endpoint: '/users/{id}', method: 'GET', status: 200 });\r\n```\r\nor\r\n```js\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchemaAjv(schema, { endpoint: '/users/{id}', method: 'GET', status: 200 });\r\n```\r\n\r\nExample providing an **_OpenAPI 3.0.1 or Swagger 2.0 schema documents, path to the schema definition and custom `issuesStyles`_**:\r\n\r\n```js\r\nconst issuesStylesOverride = {\r\n  iconPropertyError: '🟦', colorPropertyError: '#5178eb',\r\n  iconPropertyMissing: '🟪', colorPropertyMissing: '#800080'\r\n}\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchema(schema, { endpoint: '/users/{id}', method: 'GET', status: 200 }, issuesStylesOverride);\r\n```\r\nor\r\n```js\r\nconst issuesStylesOverride = {\r\n  iconPropertyError: '🟦', colorPropertyError: '#5178eb',\r\n  iconPropertyMissing: '🟪', colorPropertyMissing: '#800080'\r\n}\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchemaAjv(schema, { endpoint: '/users/{id}', method: 'GET', status: 200 }, issuesStylesOverride);\r\n```\r\n\r\n#### Path Parameter\r\n\r\nUsing the path defined by `{ endpoint, method, status }`, the plugin will automatically take the schema `$ref` for that definition, find it in the `components` section, and use it in the schema validation.\r\n\r\n![Path to the schema definition](images/path_a.png) \r\n\r\n&nbsp; \r\n\r\n### `cy.validateSchemaZod(schema[, issuesStyles])`\r\n\r\nIt validates the JSON data in the response body against the provided **Zod schema** using the **ZOD Schema Validator**.\r\nIt is expected to be chained to an API response (from a `cy.request()` or `cy.api()`).\r\n\r\n#### Parameters\r\n\r\n- **`schema`** (object)\r\n   The schema to validate against. Supported format is Zod Schema.\r\n- **`issuesStyles`** (object, optional)\r\n   An object with the icons used to flag the schema issues. If not provided, it will use the default icons defined in the plugin `core-zod-schema-validator`.\r\n   Includes the following properties:\r\n  - **`iconPropertyError`** (string, optional): The icon used to flag type errors in the data. Support emojis.\r\n  - **`iconPropertyMissing`** (string, optional): The icon used to flag type errors in the data. Support emojis.\r\n  - **`colorPropertyError`** (string, optional): The HEX color used to flag the property error.\r\n  - **`colorPropertyMissing`** (string, optional): The HEX color used to flag the missing property.\r\n\r\n#### Returns\r\n\r\n- `Cypress.Chainable`: The response object wrapped in a `Cypress.Chainable`.\r\n\r\n#### Throws\r\n\r\n- `Error`: If any of the required parameters are missing or if the schema or schema definition is not found.\r\n\r\n&nbsp; \r\n\r\nExample providing a **_Zod schema_**:\r\n\r\n```js\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchemaZod(schema);\r\n```\r\n\r\nExample providing a **_Zod schema nd custom `issuesStyles`_**:\r\n\r\n```js\r\nconst issuesStylesOverride = {\r\n  iconPropertyError: '🟦', colorPropertyError: '#5178eb',\r\n  iconPropertyMissing: '🟪', colorPropertyMissing: '#800080'\r\n}\r\ncy.request('GET', 'https://awesome.api.com/users/1')\r\n  .validateSchemaZod(schema, issuesStylesOverride);\r\n```\r\n\r\n&nbsp; \r\n\r\n## USAGE EXAMPLES\r\n\r\n### Examples For AJV Schema Validation [USAGE-EXAMPLES-AJV.md](USAGE-EXAMPLES-AJV.md).\r\n\r\nIncludes detailed examples for the use cases:\r\n\r\n  - `.validateSchema()` command with a **Plain JSON schema**.\r\n\r\n  - `.validateSchema()` command with a **Plain JSON schema** and overriding `issuesStyles`\r\n  \r\n  - `.validateSchema()` command with an **OpenAPI 3.0.1 schema** document.\r\n  \r\n  - `.validateSchemaAjv()` command with a **Swagger 2.0 schema** document.\r\n\r\n  - `.validateSchema()` command with a **Swagger 2.0 schema** document and overriding `issuesStyles`.\r\n  \r\n  - `.validateSchemaAjv()` command in conjunction with **`cy.api()` from the `@bahmutov/cy-api` or `cypress-plugin-api` plugins**.\r\n\r\n### Examples For ZOD Schema Validation [USAGE-EXAMPLES-ZOD.md](USAGE-EXAMPLES-ZOD.md).\r\n\r\nIncludes detailed examples for the use cases:\r\n\r\n  - `.validateSchemaZod()` command with a **Zod Schema**.\r\n\r\n  - `.validateSchemaZod()` command with a **Zod Schema** and overriding `issuesStyles`.\r\n  \r\n  - `.validateSchemaAZod()` command with **`cy.api()` from Plugin `@bahmutov/cy-api` or `cypress-plugin-api` plugins**.\r\n\r\n\r\n## SCHEMA VALIDATION RESULTS\r\n\r\n### Results Outcome (Passed/Failed)\r\n\r\nHere are some screenshots of schema validation tests run in Cypress for the different test results.\r\n\r\n#### Test Passed ✔️\r\n\r\nWhen a test passes, the Cypress log will show the message: \"✔️ **PASSED - THE RESPONSE BODY IS VALID AGAINST THE SCHEMA.**\".\r\n\r\n![Test Passed](images/pass1_a.png) \r\n\r\n#### Test Failed ❌\r\n\r\nWhen a test fails, the Cypress log will show the message: \"❌ **FAILED - THE RESPONSE BODY IS NOT VALID AGAINST THE SCHEMA**\"; indicating the total number of errors: _(Number of schema errors: N_).\r\n\r\nAlso, the Cypress log will show an entry for each of the individual schema validation errors as provided by AJV or ZOD. The errors that correspond to missing fields in the data validated are marked with the symbol ❌, and the rest of the errors like with the symbol ⚠️.\r\n\r\n![Test Failed Overview](images/error11_a.png) \r\n\r\n##### Detailed Error View in the Console\r\n\r\nIf you open the Console in the browser DevTools, and click on the summary line for the schema validation error in the Cypress log, the console will display detailed information about all the errors. This includes:\r\n\r\n- Message containing the schema analysis results.\r\n- The total number of errors.\r\n- Complete list of errors provided by the core Schema Validator (AJV or ZOD).\r\n- A user-friendly view of the mismatches between the validated data and the JSON schema, highlighting where each validation error occurred and the exact reason for the mismatch.\r\n\r\n![Test Failed Details](images/error12_a.png) \r\n\r\n##### Test Failed with More than 10 Errors ➕\r\n\r\nWhen there are more than 10 schema validation errors, the Cypress log will show only the first 10 and, at the end of the list, an additional line indicating \"**...and _N_ more errors.**\".\r\n\r\nIf you click on the \"**...and N more errors.**\" line in the Cypress log, the browser console will show additional details for the errors grouped under that entry as provided by the core Schema Validator (AJV or ZOD).\r\n\r\n![Test Failed Many Errors](images/error21_a.png) \r\n\r\n\r\n##### Schema errors in the Terminal when executing in `run` mode\r\n\r\nIn case the tests are executed in run mode and there are schema errors, these will be displayed in the Terminal as provided by the AJV or ZOD validators.\r\n\r\n![Terminal Schema Errors](images/terminal_errors.png) \r\n\r\n\r\n### Integration with other Cypress API Plugins\r\n\r\n#### Integration with Gleb Bahmutov's `@bahmutov/cy-api` Plugin\r\n\r\nWhen the Cypress environment variable **`enableMismatchesOnUI`** is set to **`true`**, and you have imported the `@bahmutov/cy-api` plugin into your `cypress/support/commands.js` or test file, schema validation mismatches will be displayed directly in the plugin's UI in a user-friendly format.\r\n\r\n![Plugin @bahmutov/cy-api](images/cy_api_1_a.png) \r\n\r\n![Plugin @bahmutov/cy-api](images/cy_api_1_details_a.png) \r\n\r\n\r\n### Custom Styles for Validation Errors\r\n\r\nThe **Custom Styles for Validation Errors** feature allows users to personalize the display of schema validation issues for enhanced clarity. By specifying custom styles through the issuesStyles object, users can customize icons and HEX color codes to flag specific validation errors visually.\r\n\r\nThese customizable styles ensure flexibility and improved error identification suited to individual preferences.\r\n\r\n![Custom Styles Validation Errors](images/custom-errors.png)\r\n\r\n\r\n### Results for AJV Schema Validation vs ZOD Schema Validation\r\n\r\nOne of the significant advantages of using this plugin is that it presents results to the user in a consistent format, regardless of whether the AJV Schema Validator or ZOD Validator is used. This ensures that if the plugin's user decides to switch between validators, the results remain uniform and consistent.\r\n\r\nThis provides a layer of abstraction that manages how the results are presented, allowing the user to focus solely on the results themselves.\r\n\r\nIf we compare the results presented by the cypress-schema-plugin for AJV validation and ZOD validation side by side, we can observe that the data mismatch results displayed in the Cypress UI, as well as the nested tree view of the validated data, remain consistent. This ensures an identical user experience when identifying schema issues.\r\n\r\nThe only slight differences are the schema error properties presented in the Cypress Log and the console, as these are provided by the specific validator. This allows users to inspect the results in the original validator format, if they are more familiar with it.\r\n\r\n![Results AJV vs ZOD](images/results-ajv-vs-zod.png) \r\n\r\n&nbsp; \r\n\r\n## ENABLE CREATION OF JSON REPORTS FOR SCHEMA VALIDATIONS\r\n\r\nYou can enable the generation of JSON reports for your schema validations by setting the Cypress environment (or exposed) variable **`generateReport`** to **`json`**.\r\n\r\n**Note:** This feature is disabled by default, and json is currently the only supported format.\r\n\r\nWhen enabled, each validation command `cy.validateSchema()`, `cy.validateSchemaAjv()`, or `cy.validateSchemaZod()` generates a report file in the directory configured by reportsFolder in cypress.config.js.\r\n\r\n### File Name Format\r\n\r\n`schema-validation-report-{uniqueId}_{timestamp}.json`\r\n\r\nWhere:\r\n- `uniqueId` is generated with Cypress utility `Cypress._.uniqueId('id')` (for example: `id1`, `id2`, `id36`).\r\n- `timestamp` is generated from ISO date-time and normalized for file systems by replacing `:` and `.` with `-`.\r\n\r\nExample:\r\n- `schema-validation-report-id36_2026-06-06T23-58-42-001Z.json`\r\n\r\n\r\n### JSON Report File Content\r\n\r\nEach generated report is a JSON object with the following structure:\r\n\r\nExample:\r\n```json\r\n{\r\n  \"timestamp\": \"2026-06-07T00-45-49-966Z\",\r\n  \"test\": \"ALL TESTS SHOULD FAIL > Schema Validation for Swagger 2.0 > POST /service1 (401 Response)\",\r\n  \"validationResults\": {\r\n    \"errors\": [\r\n      {\r\n        \"instancePath\": \"/code\",\r\n        \"schemaPath\": \"#/definitions/ErrorResponse/properties/code/type\",\r\n        \"keyword\": \"type\",\r\n        \"params\": {\r\n          \"type\": \"integer\"\r\n        },\r\n        \"message\": \"must be integer\"\r\n      },\r\n      {\r\n        \"instancePath\": \"/message\",\r\n        \"schemaPath\": \"#/definitions/ErrorResponse/properties/message/type\",\r\n        \"keyword\": \"type\",\r\n        \"params\": {\r\n          \"type\": \"string\"\r\n        },\r\n        \"message\": \"must be string\"\r\n      }\r\n    ],\r\n    \"dataMismatches\": {\r\n      \"code\": \"⚠️ null must be integer\",\r\n      \"message\": \"⚠️ 123456 must be string\"\r\n    }\r\n  },\r\n  \"data\": {\r\n    \"code\": null,\r\n    \"message\": 123456\r\n  }\r\n}\r\n```\r\n\r\n#### Top-level properties\r\n\r\n- `timestamp` (`string`): Report creation date-time in ISO-like format used in the file name (for example: `2026-06-06T23-58-42-001Z`).\r\n- `test` (`string`): Full Cypress test path/title where the validation was executed.\r\n- `validationResults` (`object`): Validation output (errors and highlighted mismatches).\r\n- `data` (`array | object`): Original response payload that was validated.\r\n\r\n##### `validationResults` properties\r\n\r\n- `errors` (`array`): List of validation errors returned by the active validator (Ajv or Zod).\r\n- `dataMismatches` (`array | object`): Copy of validated `data` response with mismatch markers added by the plugin.\r\n  - `dataMismatches` mirrors the `data` structure and adds marker strings (icon + message) at failing paths.\r\n  - Examples of a field mismatches:\r\n    - `\"code\": \"⚠️ null must be integer\"`\r\n    - `\"createdDate\": \"❌ Missing property 'createdDate'`\r\n  - Note: Top-level property `data` always stores the original validated payload unchanged (same shape as the API response).\r\n\r\n\r\n## DISABLE JSON SCHEMA VALIDATION IN YOUR TESTS\r\n\r\nYou can disable schema validation in your tests by setting the Cypress environment (or exposed) variable **`disableSchemaValidation`** to **`true`**.\r\n\r\nWhen schema validation is disabled for a test, the Cypress log and the browser console will display the following message:\r\n\r\n![JSON Schema Validation Disabled](images/disabled_a.png) \r\n\r\n&nbsp; \r\n\r\n## LICENSE\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\r\n\r\n\r\n## CONTRIBUTING\r\n\r\nFirst off, thanks for taking the time to contribute!\r\n\r\nTo contribute, please follow the best practices promoted by GitHub on the [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project \"Contributing to a project\") page.\r\n\r\nAnd if you like the project but just don't have the time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:\r\n- Star the project\r\n- Promote it on social media\r\n- Refer this project in your project's readme\r\n- Mention the project at local meetups and tell your friends/colleagues\r\n- Buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.\r\n\r\n<a href=\"https://www.buymeacoffee.com/sclavijosuero\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 40px !important;width: 150px !important;\" ></a>\r\n\r\nThank you for your support!\r\n\r\n\r\n## CHANGELOG\r\n\r\n### [2.0.0]\r\n- Added support to generate a schema validation report (JSON).\r\n- Added support for the new environment variable handling in v15.10+ (`cy.env` and `Cypress.expose`).\r\n- Migrated package to Cypress v15.16.0.\r\n- Major release due a breaking change that will be introduced in the Cypress v16 release.\r\n- Cypress.env deprecated in Cypress v15.10.0 and no loger supported in Cypress v16.0.0.\r\n- **cypress-ajv-schema-validator** v2.0.0 is not supported on versions earlier than v15.10.0.\r\n- Decommissioned support for **`cypress-plugin-api`**, as it has not been updated to work with `cy.env()` and `Cypress.exposed()`.\r\n\r\n\r\n### [1.0.1]\r\n- Update documentation regarding the legacy plugin `cypress-ajv-schema-validator`.\r\n\r\n\r\n### [1.0.0]\r\n- Initial release of `cypress-schema-validator`, supporting both AJV and ZOD schema validations.\r\n\r\n\r\n### [cypress-ajv-schema-validator 2.0.1]\r\n- Predecessor to the `cypress-schema-validator`.\r\n- The legacy plugin `cypress-ajv-schema-validator` has been decommissioned and is no longer officially supported.\r\n\r\n\r\n## EXTERNAL REFERENCES\r\n\r\n### For cypress-ajv-schema-validator (predecessor plugin)\r\n\r\n- [json-schema.org](https://json-schema.org/ \"https://json-schema.org/\") - Website [JSON Schema Tooling](https://json-schema.org/tools?query=&sortBy=name&sortOrder=ascending&groupBy=toolingTypes&licenses=&languages=&drafts=&toolingTypes=#json-schema-tooling \"JSON Schema Tooling\")\r\n\r\n- [cypress.io](https://www.cypress.io/ \"https://www.cypress.io/\") - Blog [Elevate Your Cypress Testing: Top 10 Essential Plugins](https://www.cypress.io/blog/elevate-your-cypress-testing-top-10-essential-plugins \"Elevate Your Cypress Testing: Top 10 Essential Plugins\")\r\n\r\n- [Murat Ozcan](https://www.linkedin.com/in/murat-ozcan-3489898/ \"Murat Ozcan\")\r\n    - Video [Schema validation using cypress-ajv-schema-validator vs Optic](https://www.youtube.com/watch?v=ysCADOh9aJU \"Schema validation using cypress-ajv-schema-validator vs Optic\")\r\n    - Video [Demo comparing API e2e vs Schema testing](https://www.youtube.com/watch?v=ePjcKMq4c2o \"Demo comparing API e2e vs Schema testing\")\r\n    - Course [Epic Test Arch. - test everything, everywhere all at once](https://www.udemy.com/course/epic-test-arch-test-everything-everywhere-all-at-once/?referralCode=97449422709A69966E4B \"Epic Test Arch. - test everything, everywhere all at once\")\r\n\r\n- [Joan Esquivel Montero](https://www.linkedin.com/in/joanesquivel/ \" Joan Esquivel Montero\") - Video [Cypress API Testing: AJV SCHEMA VALIDATOR](https://www.youtube.com/watch?v=SPmJvH5mYaU \"Cypress API Testing: AJV SCHEMA VALIDATOR\")\r\n","readmeFilename":"README.md"}