A Cypress plugin for validating the response body against JSON Schema, Swagger, and OpenAPI documents using Ajv.
Ajv JSON Schema Validator was chosen as the core engine because of its versatility, powerful validation capabilities, and excellent documentation. For more information on Ajv, visit Ajv official website.
npm install 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.
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.
describe('API Schema Validation with Plain JSON', () => {
it('should validate the user data using plain JSON schema', () => {
const schema = {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name", "age"]
};
cy.request('GET', 'https://awesome.api.com/users/1')
.validateSchema(schema)
.then(response => {
// Further assertions
});
});
});describe('API Schema Validation with OpenAPI 3.0.1', () => {
it('should validate the user data using OpenAPI 3.0.1 schema', () => {
const schema = {
"openapi": "3.0.1",
"paths": {
"/users/{id}": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/User" }
}
}
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name", "age"]
}
}
}
};
const path = { endpoint: '/users/{id}', method: 'GET', status: 200 };
cy.request('GET', 'https://awesome.api.com/users/1')
.validateSchema(schema, path)
.then(response => {
// Further assertions
});
});
});describe('API Schema Validation with Swagger 2.0', () => {
it('should validate the user data using Swagger 2.0 schema', () => {
const schema = {
"swagger": "2.0",
"paths": {
"/users/{id}": {
"get": {
"responses": {
"200": {
"schema": { "$ref": "#/definitions/User" }
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name", "age"]
}
}
};
const path = { endpoint: '/users/{id}', method: 'GET', status: 200 };
cy.request('GET', 'https://awesome.api.com/users/1')
.validateSchema(schema, path)
.then(response => {
// Further assertions
});
});
});import validateSchema from 'cypress-ajv-schema-validator';
describe('API Schema Validation Function', () => {
it('should validate the user data using validateSchema function', () => {
const schema = {
"openapi": "3.0.1",
"paths": {
"/users/{id}": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/User" }
}
}
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name", "age"]
}
}
}
};
const path = { endpoint: '/users/{id}', method: 'GET', status: 200 };
cy.request('GET', 'https://awesome.api.com/users/1').then(response => {
const errors = validateSchema(response.body, schema, path);
expect(errors).to.have.length(0); // Assertion to ensure no validation errors
});
});
});Here are some screenshots of schema validation tests run in Cypress.
In the Cypress log, the number of errors is summarized, and the schema validation errors are listed in AJV format. Missing fields in the validated data are shown with the symbol 🗑️, and the rest of the errors with the symbol 👉.
When clicking on the summary line, the number of errors, the full list of errors in AJV format, and a view of the validated data indicating the errors in a user-friendly format are shown.
At the end of the list of individual errors, a line "...and N more errors." is shown.
When clicking the summary line in the Cypress log, the error details are shown in the console.
When clicking on the "...and N more errors." line in the Cypress log, additional error details are shown in the console.
This project is licensed under the MIT License. See the LICENSE file for more details.
- Initial release.