{"id":17185,"library":"chai-openapi-response-validator","title":"Chai OpenAPI Response Validator","description":"Chai OpenAPI Response Validator is a testing utility that extends the Chai assertion library, enabling developers to validate HTTP responses and arbitrary JavaScript objects against an OpenAPI (Swagger) specification. The current stable version is 0.14.2, released in January 2022. While it doesn't adhere to a strict release cadence, the project shows active maintenance with several releases in late 2021 and early 2022. Key differentiators include its seamless integration with Chai's assertion syntax (e.g., `expect(response).to.satisfyApiSpec`), support for both OpenAPI 2 and 3 specifications in YAML or JSON formats, and robust handling of `$ref` definitions. It is compatible with various HTTP clients like Axios, `request-promise`, Supertest, Superagent, and `chai-http`, making it versatile for different testing setups, including Mocha. It also provides immediate feedback if the loaded OpenAPI specification itself is invalid.","status":"active","version":"0.14.2","language":"javascript","source_language":"en","source_url":"https://github.com/openapi-library/OpenAPIValidators/tree/master/packages/chai-openapi-response-validator","tags":["javascript","chai","chai-plugin","http","response","openapi","validate","typescript"],"install":[{"cmd":"npm install chai-openapi-response-validator","lang":"bash","label":"npm"},{"cmd":"yarn add chai-openapi-response-validator","lang":"bash","label":"yarn"},{"cmd":"pnpm add chai-openapi-response-validator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core assertion library this plugin extends.","package":"chai","optional":true},{"reason":"Underlying validation logic for OpenAPI specifications.","package":"openapi-response-validator","optional":false},{"reason":"Type declarations for `request` library, moved to dependencies in v0.14.2 for build compatibility.","package":"@types/request","optional":false},{"reason":"Type declarations for `superagent` library, moved to dependencies in v0.14.2 for build compatibility.","package":"@types/superagent","optional":false}],"imports":[{"note":"This is the default export, used to initialize the Chai plugin with your OpenAPI spec.","symbol":"chaiResponseValidator","correct":"import chaiResponseValidator from 'chai-openapi-response-validator';"},{"note":"For CommonJS, the default export must be accessed via the `.default` property.","wrong":"const chaiResponseValidator = require('chai-openapi-response-validator');","symbol":"chaiResponseValidator","correct":"const chaiResponseValidator = require('chai-openapi-response-validator').default;"},{"note":"While not a direct import from this package, 'satisfyApiSpec' is the primary assertion method added to Chai's Assertion prototype by this plugin for response validation.","symbol":"satisfyApiSpec","correct":"expect(response).to.satisfyApiSpec();"}],"quickstart":{"code":"import chai from 'chai';\nimport chaiResponseValidator from 'chai-openapi-response-validator';\nimport axios from 'axios';\n\nconst expect = chai.expect;\n\n// Load your OpenAPI file (YAML or JSON) into the plugin\n// In a real app, use an actual path or load from an environment variable\nchai.use(chaiResponseValidator({\n  openapi: '3.0.0',\n  info: { title: 'Example API', version: '1.0.0' },\n  paths: {\n    '/example': {\n      get: {\n        responses: {\n          200: {\n            description: 'A successful response',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'object',\n                  properties: {\n                    message: { type: 'string' }\n                  },\n                  required: ['message']\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}));\n\ndescribe('GET /example', () => {\n  it('should satisfy OpenAPI spec', async () => {\n    // Simulate an HTTP response (e.g., from an actual API call)\n    const mockResponse = {\n      status: 200,\n      data: { message: 'Hello from API' },\n      headers: { 'content-type': 'application/json' }\n    };\n\n    // Use Chai to assert that the mock response satisfies the OpenAPI spec\n    expect(mockResponse).to.satisfyApiSpec();\n\n    // Example with an actual axios call (if your server is running)\n    // try {\n    //   const res = await axios.get('http://localhost:3000/example');\n    //   expect(res).to.satisfyApiSpec();\n    // } catch (error) {\n    //   console.error('Axios request failed:', error.message);\n    //   throw error;\n    // }\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to set up Chai with `chai-openapi-response-validator`, load a simple OpenAPI specification directly as an object, and then assert that a mock HTTP response (or an actual one from Axios) satisfies the defined API specification."},"warnings":[{"fix":"Review your tests and update any assertions that validate specific error message strings. Focus on the nature of the validation failure rather than verbatim messages.","message":"The underlying `openapi-response-validator` dependency was updated from v3 to v9 in `chai-openapi-response-validator` v0.14.0. This change resulted in altered validation error messages and potentially subtle shifts in validation rules. Test assertions that relied on exact error message strings may break.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Always access the default export using `.default` for CommonJS: `const chaiResponseValidator = require('chai-openapi-response-validator').default;`","message":"When using CommonJS `require()`, directly importing `chai-openapi-response-validator` will result in `chaiResponseValidator` being an object containing the default export, not the function itself. This typically manifests as 'TypeError: chaiResponseValidator is not a function'.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Verify the provided OpenAPI specification is valid using a tool like Swagger Editor. If using a filepath, ensure it's absolute and points to an existing, readable file.","message":"The `filepathOrObject` parameter for `chaiResponseValidator` can be an absolute path to a YAML/JSON file or a JavaScript object representing the OpenAPI spec. Ensure the path is correct and the file is accessible, or the object is a valid OpenAPI definition. An invalid spec will lead to initialization errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `const chaiResponseValidator = require('chai-openapi-response-validator');` to `const chaiResponseValidator = require('chai-openapi-response-validator').default;`","cause":"Attempting to use `chaiResponseValidator` in a CommonJS environment without accessing its `.default` property.","error":"TypeError: chaiResponseValidator is not a function"},{"fix":"Review the detailed error messages provided by the assertion failure to identify the specific validation discrepancy. Either update your API response to match the spec or update the OpenAPI spec to reflect the correct response structure.","cause":"The HTTP response body or status code does not conform to the schema defined in your OpenAPI specification for the given endpoint and response code.","error":"Expected response body to satisfy OpenAPI spec, but it had the following errors: ..."},{"fix":"Ensure the path and HTTP method in your test precisely match a defined path and method in your loaded OpenAPI specification. Verify the OpenAPI spec is correctly structured and accessible.","cause":"The `chaiResponseValidator` was initialized with an OpenAPI specification that does not contain the expected path or operation (`GET`, `POST`, etc.) being tested. This can also happen if the provided path is relative instead of absolute, or if the spec itself is malformed.","error":"Invalid OpenAPI spec: Path '/your/path' not found"}],"ecosystem":"npm","meta_description":null}