Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
chaiPlugin
✓ import { chaiPlugin } from 'api-contract-validator';
✗ const matchApiSchema = require('api-contract-validator').chaiPlugin;
While CommonJS `require` is shown in the README, modern Node.js and bundlers encourage ESM `import`. The package primarily exposes named exports for its plugins.
shouldPlugin
✓ import { shouldPlugin } from 'api-contract-validator';
✗ const matchApiSchema = require('api-contract-validator').shouldPlugin;
For Should.js integration, the `shouldPlugin` is exported as a named export. Ensure you import it correctly for ESM or destructure it from `require` for CJS.
jestPlugin
✓ import { jestPlugin } from 'api-contract-validator';
✗ const matchApiSchema = require('api-contract-validator').jestPlugin;
The `jestPlugin` registers custom matchers like `toMatchApiSchema` and `toHaveStatus`. It's crucial to call this imported function with your API definition path.
ApiContractValidator
✓ import { ApiContractValidator } from 'api-contract-validator';
While less common for direct use, the underlying `ApiContractValidator` class can be imported if you need to instantiate the validator directly without framework-specific plugins.
This quickstart demonstrates how to integrate `api-contract-validator` with Chai and Supertest to validate an Express.js API's responses against an OpenAPI specification. It sets up a basic server, defines an OpenAPI schema (conceptually, for a `/pet/{id}` endpoint), and then uses the `matchApiSchema` assertion to verify that a successful API response conforms to the defined contract. It illustrates both the setup and a basic test case for a GET request.
import { chaiPlugin } from 'api-contract-validator';
import path from 'path';
import { expect, use } from 'chai';
import supertest from 'supertest';
// Assuming a simple Express app for demonstration
const express = require('express');
const app = express();
app.get('/pet/:id', (req, res) => {
const id = parseInt(req.params.id, 10);
if (id === 123) {
res.status(200).json({ id: 123, name: 'Fido', species: 'Dog' });
} else {
res.status(404).json({ message: 'Pet not found' });
}
});
// API definitions path (assuming myApp.yaml exists relative to this file)
const apiDefinitionsPath = path.join(__dirname, 'myApp.yaml');
// add as chai plugin
use(chaiPlugin({ apiDefinitionsPath }));
const request = supertest(app);
describe('Pet API Contract', () => {
it('GET /pet/123 should match API schema', async () => {
// A dummy myApp.yaml for the quickstart
// paths:
// /pet/{id}:
// get:
// parameters:
// - in: path
// name: id
// schema:
// type: integer
// required: true
// responses:
// '200':
// description: Successful response
// content:
// application/json:
// schema:
// type: object
// properties:
// id:
// type: integer
// name:
// type: string
// species:
// type: string
// required:
// - id
// - name
// - species
const response = await request.get('/pet/123');
expect(response).to.have.status(200).and.to.matchApiSchema();
});
it('GET /pet/456 should not match API schema (e.g., 404 response)', async () => {
const response = await request.get('/pet/456');
expect(response).to.have.status(404);
// The validator would still check if the 404 response schema exists
// but in this quickstart, we're just checking the status.
// expect(response).to.matchApiSchema();
});
});
Errors
Common errors & fixes
Error: definition not found for path: /api/v1/resource, method: get, status: 200
The API definition file provided to the validator does not contain an entry for the specified path, method, and status code combination.
fixVerify that your `apiDefinitionsPath` correctly points to your OpenAPI/Swagger file and that the file includes the definition for `GET /api/v1/resource` with a `200` response schema. Check for typos in path or method.
AssertionError: expected { Object (status, body, ...) } to match API schema
The actual API response body or headers do not conform to the JSON schema generated from your OpenAPI definition for the given endpoint and status code.
fixExamine the detailed assertion failure message (usually provided by Chai/Jest). Compare the actual response structure and data types against your OpenAPI definition's `schema` for the relevant response. This often indicates a mismatch between API implementation and its documentation.
YAMLException: YAMLException: bad indentation of a mapping entry at line X, column Y
The OpenAPI definition file (if YAML) has a syntax error, specifically incorrect indentation or formatting, preventing `api-schema-builder` from parsing it.
fixReview the specified line and column in your YAML definition file. Use a YAML linter or editor with YAML validation to correct indentation and syntax errors.
Audit
Dependencies
api-schema-builderrequiredCore dependency for transforming API definitions into JSON schemas for validation. This package is frequently updated as seen in recent release notes.
chaioptionalPeer dependency when using the `chaiPlugin` for assertion chaining. Not directly required for the package's core logic but essential for its primary use case.
shouldoptionalPeer dependency when using the `shouldPlugin` for assertion chaining. Similar to Chai, it's optional but critical for its intended integration.
jestoptionalPeer dependency when using the `jestPlugin` for custom matchers. Optional but necessary for Jest test environments.