Lightweight Playwright 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).
Playwright 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). It delivers results in a clear, user-friendly format, simplifying the process of identifying and addressing schema issues.
> ššš IMPORTANT NOTE: This plugin playright-schema-validator replaces the previously existing playright-ajv-schema-validator, maintaining complete backward compatibility while extending the API to support Zod schema validation capabilities.
MAIN FEATURES
āļø Function validateSchema() (and alias validateSchemaAjv()) performs a JSON Schema Validation and reports errors in the responses of network requests.
- Schemas are provided as JSON objects.
- Supports Plain JSON schemas, OpenAPI 3.x schema documents and Swagger 2.0 schema documents.
- Utilizes the core-ajv-schema-validator, leveraging the Ajv JSON Schema Validator .
āļø Fuction cy.validateSchemaZod() identifies and reports Zod schema validation errors in the responses of network requests.
- Schemas are provided as Zod objectse.
- Uses the core-zod-schema-validator , leveraging the Zod Schema Validator.
āļø The functions process the responses provided by Playwright API requests.
āļø 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:
- Total number of schema errors.
- Full list of schema errors as provided by Ajv or Zod depending on the selected function.
- A nested tree view of the validated data, clearly indicating the errors and where they occurred in an easy-to-understand format.
āļø Allow custom styles (icons and text colors) to match the user's preferences for distinguishing schema errors.
āļø Presents results to the user in a consistent format, regardless of whether the AJV Schema Validator or ZOD Validator is used.
āļø 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 works independently with standard Playwright API requests.
- Ajv 8.16.0 or higher
- ajv-formats 3.0.1 or higher
For Typescript projects also:
- TypeScript 4.5+
- You must enable strict mode in your tsconfig.json. This is a best practice for all TypeScript projects.
INSTALLATION
``sh
npm install -D playwright-schema-validator
`
CONFIGURATION
- Add the following line to your test file for leveraging AJV Schema Validation:
`js
import { validateSchema } from 'playwright-schema-validator';
` or
`js
import { validateSchemaAjv } from 'playwright-schema-validator';
`
- Add the following line to your test file for leveraging ZOD Schema Validation:
`js
import { validateSchemaZod } from 'playwright-schema-validator';
`
- Set environment variable DISABLE_SCHEMA_VALIDATION to true to disable the schema validation even when the validateSchema(), validateSchemaAjv(), and validateSchemaZod() functions are present in the test. By default, schema validation is enabled.
- Set environment variable LOG_API_UI to true to enable the display of schema errors on the Playwright UI and Trace Viewer. By default, these results are displayed.
- Set environment variable LOG_API_REPORT to true to attach the schema errors on the HTML Report. By default, these results are not attached to the report.
> āāāāā If you are using the Playwright pw-api-plugin in your API tests to display API call details, the playwright-schema-validation plugin will automatically detect and display schema errors directly alongside the details.
ABOUT JSON SCHEMAS AND SCHEMA VALIDATORS
$3
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 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.
Ajv 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.
The playwright-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-schema-validator) is configured with the options { allErrors: true, strict: false } to display all validation errors and disable strict mode.
$3
Zod is a TypeScript-first schema declaration and validation library that allows defining schemas directly in TypeScript while providing robust type detection within your code.
It 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.
The playwright-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.
API Reference
$3
It validates the JSON data in the response body against the provided Plain JSON schema, OpenAPI and Swagger document format using the AJV Schema Validator.
Note that the function already asserts the validity of the schema, so there is no need to add additional assertions checking for types 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. Support emojis.
- 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. Support emojis.
- issuesStyles.colorPropertyMissing (optional)
- Type: string - Description: Custom HEX color to indicate missing properties.