A Cypress plugin for API testing to validate the API response against Plain JSON schemas, Swagger documents, or OpenAPI documents using Ajv JSON Schema validator.
For a detailed guide on how to use this plugin, check out my blog post, "CYPRESS-AJV-SCHEMA-VALIDATOR Plugin: The Brave Vigilante for Your API Contracts," on my Cypress blog. There you'll find comprehensive information about setting up and getting the most out of this plugin.
-
Cypress command
cy.validateSchema()and utility functionvalidateSchema()to report JSON Schema validation errors in the response obtained from any network request withcy.request(). -
The command
cy.validateSchema()is chainable and returns the original API response yielded. -
Schema is provided as a JSON object, that could come from a Cypress fixture.
-
It uses the Ajv JSON Schema Validator as its core engine.
-
Support schemas provided as plain JSON schema, OpenAPI 3.0.1 schema document and Swagger 2.0 schema document.
-
Provides in the Cypress log a summary of the schema errors as well as a list of the individual errors in the schema validation.
-
By clicking on the summary of schema errors in the Cypress log, the console will output:
- Number of schema errors.
- Full list of schema errors as provided by Ajv.
- A nested tree view of the validated data, clearly indicating the errors and where they occurred in an easy-to-understand format.
⭐⭐⭐⭐⭐ Note: This plugin complements Filip Hric cypress-plugin-api and Gleb Bahmutov @bahmutov/cy-api plugins to perform JSON schema validations.
Example usage with these two API plugins:
cy.api('/users/1').validateSchema(schema);To see an example of
cypress-ajv-schema-validatorworking with thecypress-plugin-apiplugin for the Swagger PetStore API, check the sample test test-petstore-with-cypress-plugin-api.js.
JSON Schema is a hierarchical, declarative language that describes and validates JSON data.
The 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.
AJV, or Another JSON Schema Validator, is a JavaScript library that validates data objects against a JSON Schema structure.
It was chosen as the core engine of the cypress-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.
Ajv supports validation of the following schema formats: JSON Schema, OpenAPI 3.0.1 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.0.1 or Swagger 2.0 schema document by itself.
The cypress-ajv-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).
Note: The Ajv instance used in this plugin (
cypress-ajv-schema-validator) is configured with the options{ allErrors: true, strict: false }to display all validation errors and disable strict mode.
npm install cypress-ajv-schema-validator
// or
yarn add cypress-ajv-schema-validator- Cypress 12.0.0 or higher
- Ajv 8.16.0 or higher
- ajv-formats 3.0.1 or higher
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:
import 'cypress-ajv-schema-validator';import validateSchema from 'cypress-ajv-schema-validator';Validates the response body against the provided schema.
schema(object): The schema to validate against. Supported formats are plain JSON schema, Swagger, and OpenAPI documents.path(object, optional): The path object to the schema definition in a Swagger or OpenAPI document.endpoint(string, optional): The endpoint path.method(string, optional): The HTTP method. Defaults to 'GET'.status(integer, optional): The response status code. Defaults to 200.
Cypress.Chainable: The response object wrapped in a Cypress.Chainable.
Error: If any of the required parameters are missing or if the schema or schema definition is not found.
Example providing a Plain JSON schema:
cy.request('GET', 'https://awesome.api.com/users/1')
.validateSchema(schema);Example providing an OpenAPI 3.0.1 or Swagger 2.0 schema documents:
cy.request('GET', 'https://awesome.api.com/users/1')
.validateSchema(schema, { endpoint: '/users/{id}', method: 'GET', status: 200 });Validates the given data against the provided schema.
data(any): The data to be validated.schema(object): The schema to validate against.path(object, optional): The path object to the schema definition in a Swagger or OpenAPI document.endpoint(string, optional): The endpoint path.method(string, optional): The HTTP method. Defaults to 'GET'.status(integer, optional): The response status code. Defaults to 200.
Array: An array of validation errors, or null if the data is valid against the schema.
Error: If any of the required parameters are missing or if the schema or schema definition is not found.
Example providing a Plain JSON schema:
cy.request('GET', 'https://awesome.api.com/users/1').then(response => {
const data = response.body
const errors = validateSchema(data, schema);
expect(errors).to.have.length(0); // Assertion to ensure no validation errors
});Example providing an OpenAPI 3.0.1 or Swagger 2.0 schema documents:
cy.request('GET', 'https://awesome.api.com/users/1').then(response => {
const data = response.body
const errors = validateSchema(data, schema, { endpoint: '/users/{id}', method: 'GET', status: 200 });
expect(errors).to.have.length(0); // Assertion to ensure no validation errors
});For detailed usage examples, check the document USAGE-EXAMPLES.md.
The examples included are for using:
-
cy.validateSchema()command with a Plain JSON schema. -
cy.validateSchema()command with an OpenAPI 3.0.1 schema document. -
cy.validateSchema()command with a Swagger 2.0 schema document. -
validateSchema()function with an OpenAPI 3.0.1 schema document. -
cy.validateSchema()command in conjunction withcy.api()from thecypress-plugin-apior@bahmutov/cy-apiplugins.
Here are some screenshots of schema validation tests run in Cypress.
When a test passes, the Cypress log will show the message: "✔️ PASSED - THE RESPONSE BODY IS VALID AGAINST THE SCHEMA.".
When 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).
Also, the Cypress log will show an entry for each of the individual schema validation errors as provided by Ajv. The errors that correspond to missing fields in the data validated are marked with the symbol 🗑️, and the rest of the errors with the symbol 👉.
If 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:
- The total number of errors
- The full list of errors as provided by the Ajv.
- A user-friendly view of the validated data, highlighting where each validation error occurred and the exact reason for the mismatch.
When 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.".
In this case, clicking on the summary line for the schema validation error in the Cypress log will also display: the total number of errors, the full list of errors as provided by Ajv, and the user-friendly view of the schema mismatches, making it easy to understand where the errors occurred.
When clicking 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 Ajv.
This project is licensed under the MIT License. See the LICENSE file for more details.
- Added GitHub CI/CD workflow.
- Initial release.