A Playwright plugin for API schema validation against plain JSON schemas, Swagger schema documents. Built on the robust core-ajv-schema-validator plugin and powered by the Ajv JSON Schema Validator, it delivers results in a clear, user-friendly format, si
A Playwright plugin for API schema validation against plain JSON schemas, Swagger schema documents. Built on the robust core-ajv-schema-validator plugin and powered by the Ajv JSON Schema Validator, it delivers results in a clear, user-friendly format, simplifying the process of identifying and addressing schema issues.
- Function validateSchema() to report JSON Schema errors in the response obtained from network requests.
- Uses the core-ajv-schema-validator plugin, which leverages the Ajv JSON Schema Validator as its engine .
- Supports schemas provided as plain JSON schema, OpenAPI 3 schema document and Swagger 2 schema document.
- Provides a user-friendly view of schema errors and mismatches between the validated data and the JSON schema, clearly highlighting where each validation error occurred and the exact reason for the mismatch:
- 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.
- Environment variables:
- DISABLE_SCHEMA_VALIDATION to disable schema validation in your tests even when function validateSchema() is present.
- LOG_API_UI to enable the display of API call details in Playwright UI and Trace Viewer .
- LOG_API_REPORT to enable the display of API call details in HTML Report .
- ⭐⭐⭐⭐⭐ Integrates seamlessly with the pw-api-plugin but also functions independently with standard Playwright API requests.
JSON Schema is a hierarchical, declarative language that describes and validates JSON data.
$3
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.
$3
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 playwright-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 specification, and Swagger 2 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 playwright-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 (playwright-ajv-schema-validator) is configured with the options { allErrors: true, strict: false } to display all validation errors and disable strict mode.
- Ajv 8.16.0 or higher
- ajv-formats 3.0.1 or higher
CONFIGURATION
- Add the following lineto your test file:
`js
import { validateSchema } from 'playwright-ajv-schema-validator';
`
API Reference
$3
Validates the response body against a given schema. Note that the function already asserts the validity of the schema, so there is no need to add additional assertions on the results.
#### Parameters
- fixtures (required)
- Type: object - Description: An object containing test fixtures, such as the page object: { page }.
- data (required)
- Type: object - Description: The JSON data to validate against the schema.
- schema (required)
- Type: any - Description: The schema to validate against. Supported formats include:
- JSON Schema
- OpenAPI 3 specification document
- Swagger 2 specification 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 the schema is a plain JSON schema.
- path.endpoint (required if path is provided)
- Type: string - Description: The endpoint path in the Swagger or OpenAPI document.
- path.method (optional)
- Type: string - Default: "GET" - Description: The HTTP method (e.g., GET, POST) of the API request.
- path.status (optional)
- Type: number - Default: 200 - Description: The expected status code of the API response.
- issuesStyles (optional)
- Type: object - Description: An optional object to override the default icons and HEX colors used to flag schema issues.
- issuesStyles.iconPropertyError (optional)
- Type: string - Description: Custom icon to flag property errors.
- issuesStyles.colorPropertyError (optional)
- Type: string - Description: Custom HEX color to flag property errors.
- issuesStyles.iconPropertyMissing (optional)
- Type: string - Description: Custom icon to indicate missing properties.
- issuesStyles.colorPropertyMissing (optional)
- Type: string - Description: Custom HEX color to indicate missing properties.