Sebastian Clavijo Suero

Posted on Apr 8 • Edited on Apr 14

GET/me/some{API}now(): New PLAYWRIGHT-AJV-SCHEMA-VALIDATOR for API Testing!

#playwright #apitesting #automation #qa

(Cover image from pexels.com by RealToughCandy.com)

Fellow QAs, the moment you’ve been waiting for is finally here!!! I am beyond thrilled to introduce the groundbreaking PLAYWRIGHT-AJV-SCHEMA-VALIDATOR plugin! 🚀 💥

ABOUT JSON SCHEMAS

JSON Schema

JSON Schema is a hierarchical, declarative language that describes and validates JSON data.

OpenAPI 3 and Swagger 2 Schema Documents

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 JSON Schema Validator

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 or Swagger 2 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).

WHAT IS THE PLUGIN FOR?

This brand-new Playwright plugin takes API schema validation to the next level. Whether you're dealing with plain JSON Schema or OpenAPI/Swagger schema documents, this plugin simplifies the process by presenting clear, user-friendly validation results directly within Playwright UI, Trace Viewer, and HTML Reports. Debugging schema issues has never been easier!

Here’s what makes PLAYWRIGHT-AJV-SCHEMA-VALIDATOR truly game-changing:

⚡ By simply providing the endpoint, HTTP method, and expected status, it automatically extracts the correct schema from your entire OpenAPI3 or Swagger2 document—no manual effort needed!

🔗 It integrates seamlessly with PW-API-PLUGIN (pwApi and pwAxios classes) but can also function independently with Playwright’s standard API requests (e.g., request.get()).

With this plugin you get out-of-the-box:

📊 Detailed insights with the number of schema errors.
⚠️ A full list of validation errors (as provided by Ajv).
👁️‍🗨️ A view of the validated data, directly pinpointing where the errors occur in the result data and detailing what those errors are.

All this with just a simple call to the function validateSchema().

You also have full control over your API validation process using the supported 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.

And it is open-source! 🆓

HOW DO YOU USE IT?

1- Install the plugin in your Playwright project:

npm install -D playwright-ajv-schema-validator`

2- Import the validation function in your test suite:

import { validateSchema } from 'playwright-ajv-schema-validator';

3- Validate the response body against the expected schema:

// Get your schema doc from a URL or a file
const schemaDoc = ...
// Make API call and get the 'response'
const data = response.body

const validationResult = await validateSchema(
    { page },
    data,
    schemaDoc,
    { endpoint: '/api/resource', method: 'POST', status: 201}
);

That's it! No kidding!

AND WHAT DOES IT LOOK LIKE?

Schema Validation Pass

Schema Validation Fail Using pw-api-plugin

Schema Validation Fail Using Playwright Standard API request

Schema Validation Fails with Custom Styles Used in your Tests

Disable Schema Validation

Setting environment variable DISABLE_SCHEMA_VALIDATION to "true".

Attach Schema Validation Failure Details in HTML Report

Setting environment variable LOG_API_REPORT to "true".

Schema Validation Test Results in HTML Report

Schema Validation Failure Details in HTML Report

Schema Validation Details in Trace Viewer

Executing command npx playwright test --trace on.

Schema Validation Details in Trace Viewer - Using pw-api-plugin

Schema Validation Details in Trace Viewer - Using Playwright Standard API request

That is AWESOME!!!! ⭐⭐⭐⭐⭐

WHERE TO FIND IT?

Here are the links to the plugin:

GitHub: https://github.com/sclavijosuero/playwright-ajv-schema-validator

npm: https://www.npmjs.com/package/playwright-ajv-schema-validator

AT THE CORE!

The plugin leverages the brand-new CORE-AJV-SCHEMA-VALIDATOR, which I have just released!

This powerful engine drives not only this Playwright plugin but also its counterpart the CYPRESS-AJV-SCHEMA-VALIDATOR plugin. You can use CORE-AJV-SCHEMA-VALIDATOR directly in any project or as the core engine for these advanced plugins.

🙂 Fun fact 🙂: CYPRESS-AJV-SCHEMA-VALIDATOR was featured in the Cypress blog’s Elevate Your Cypress Testing: Top 10 Essential Plugins—and now, Playwright users can enjoy the same cutting-edge capability!

SO... NOW YOU KNOW!

Elevate your Playwright API testing experience with the formula:

🎭 PW-API-PLUGIN ➕ PLAYWRIGHT-AJV-SCHEMA-VALIDATOR 🎭

And liquidate any API bug like the Baba Yaga of the QA underworld! 😎

Cheers to bug-free APIs and effortless schema validation.

I'd love to hear from you! Please don't forget to follow me, leave a comment, or a reaction if you found this article useful or insightful. ❤️ 🦄 🤯 🙌 🔥

If you like this plugin, please don’t forget to:
⭐ Star the project
📣 Promote it on social media
📄 Refer to this project in your project’s README
🗣️ Mention it at local meetups, and tell your friends/colleagues.

☕ Or, if you’re feeling extra generous, you can even buy me a coffee or contribute to a training session so I can keep learning and sharing cool stuff with all of you!

Thank you for your support!