Lightweight package for API testing to validate API responses against plain JSON schemas, Swagger documents, or OpenAPI documents using the Ajv JSON Schema validator. It can be used directly in any project, but also serves as the core engine for schema va
npm install core-ajv-schema-validatorvalidateSchema() to report JSON Schema validation errors in the response obtained from any network request.
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.
core-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_).
core-ajv-schema-validator) is configured with the options { allErrors: true, strict: false } to display all validation errors and disable strict mode.
sh
npm install -D core-ajv-schema-validator
`
Compatibility
- Ajv 8.17.1 or higher
- ajv-formats 3.0.1 or higher
API Reference
$3
Function that validates the given data against the provided schema.
#### Parameters
- data (required)
- Type: any
- Description: The data to be validated.
- schema (required)
- Type: object
- Description: The schema to validate against. Supported formats are:
- Plain JSON schema
- Swagger document
- OpenAPI document
See the Ajv JSON Schema documentation for more information.
- path (optional)
- Type: object
- Description: The path object to the schema definition in a Swagger or OpenAPI document. Not required if using a plain JSON schema.
- path.endpoint (required for Swagger/OpenAPI documents)
- Type: string
- Description: The endpoint path.
- path.method (optional)
- Type: string
- Description: The HTTP method. Defaults to 'GET' if not provided.
- path.status (optional)
- Type: integer
- Description: The response status code. Defaults to 200 if not provided.
- issuesStyles (optional)
- Type: object
- Description: An object with the icons used to flag the schema issues. If not provided, it will use the default icons defined in the plugin. Includes the following properties:
- iconPropertyError: The icon used to flag type errors in the data.
- iconPropertyMissing: The icon used to flag missing properties in the data.
#### Returns
An object containing the following properties:
- errors
- Type: array
- Description: An array of validation errors as provided by Ajv, or null if the data is valid against the schema.
- dataMismatches
- Type: object
- Description: The original response data with all schema mismatches directly flagged.
#### Throws
- Error: If any of the required parameters are missing or if the schema or schema definition cannot be found.
Example providing a Plain JSON schema:
`js
//...
const data = response.body
const { errors, dataMismatches } = validateSchema(data, schema);
expect(errors).to.have.length(0); // Assertion to ensure no validation errors
console.log(dataMismatches)
//...
`
Example providing an OpenAPI 3.0.1 or Swagger 2.0 schema documents, a path to the schema definition, and issuesStyles:
`js
const issuesStyles = {
iconPropertyError: '🔸',
iconPropertyMissing: '🔴'
}
const data = response.body
const { errors, dataMismatches } = validateSchema(data, schema, { endpoint: '/users/{id}', method: 'GET', status: 200 }, issuesStyles);
expect(errors).to.have.length(0); // Assertion to ensure no validation errors
console.log(dataMismatches)
`
Usage Examples
$3
#### OpenAPI 3.0.1
`js
import validateSchema from 'core-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, dataMismatches } = validateSchema(response.body, schema, path);
expect(errors).to.have.length(0); // Assertion to ensure no validation errors
console.log(dataMismatches)
});
});
});
`
License
This project is licensed under the MIT License. See the LICENSE file for more details.
Changelog
$3
- Initial release: It is the core for cypress-ajv-schema-validator@2.0.0`.