jest-runner-oas-linter
v0.0.4
Published
A Jest runner for oas-linter
Downloads
14
Readme
jest-runner-oas-linter
A Jest runner for oas-linter.
It's easy enough to run something like speccy, but for integration with CI having something that provides more structured output (e.g. by using jest-unit and Jest) a more machine friendly output can be produced and you can take advantage of other useful features like file watching.
Additionally Speccy doesn't support JS modules,
which is a pain if you like writing your API documents like that - the underlying oas-linter
has no problem though.
Note that this module does not directly support YAML, but can by adding a wrapper
file that parses your YAML and linting that instead, e.g. install yaml
and then create an api.js
to lint, e.g.
const fs = require('fs')
const YAML = require('yaml')
const file = fs.readFileSync('./file.yml', 'utf8')
module.exports = YAML.parse(file)
Warning
This is very alpha; no tests have been written, no promises made, YMMV.
Usage
Install
Install jest
(it needs Jest 21+) and jest-runner-oas-linter
npm install --save-dev jest jest-runner-oas-linter
# or with Yarn
yarn add --dev jest jest-runner-oas-linter
Add your runner to Jest config
Once you have your Jest runner you can add it to your Jest config. You will almost certainly want to configure separate Jest projects and only use this runner on modules that export an OpenAPI document.
Recommended Steps
Create separate configuration files for each "project" (e.g. tests, eslint, and
api document linting) and then reference them in your package.json
.
In your package.json
{
"jest": {
"projects": [
"<rootDir>/jest-test.config.js",
"<rootDir>/jest-eslint.config.js",
"<rootDir>/jest-oas-linter.config.js"
]
}
}
In your jest-oas-linter.config.js
module.exports = {
runner: 'oas-linter',
displayName: 'oas-linter',
testMatch: [
'<rootDir>/path/to/your/api/doc.js',
'<rootDir>/path/to/another/api/doc.js',
'<rootDir>/path/to/another/api/doc/**/*.js',
],
}
Minimal Steps
These are the more standard steps to set up a test runner
In your package.json
{
"jest": {
"runner": "oas-linter",
"testMatch": ["<rootDir>/path/to/your/api/doc.js"]
}
}
Or in jest.config.js
module.exports = {
runner: 'oas-linter',
testMatch: ['<rootDir>/path/to/your/api/doc.js'],
};
Configure OAS Linter
Configuration can be specified in your project root in .oaslintrc.json
, or in an oaslintConfig
in the package.json
file.
Currently the only two options are to specify whether the default rules should be loaded with loadDefaultRules
and to specify additional rules to be applied.
loadDefaultRules
is boolean and defaults to true, oas-linter default rules can be seen over thererules
is an array of objects, as per oas-linter's applyRules. More details about the format of rules supported can be found over atoas-kit
's linter rules documentation and the default rules (link above) have many examples.
In your package.json
{
"oaslintConfig": {
"loadDefaultRules": true,
"rules": [
{
"name": "schema-property-require-description",
"object": "schema",
"description": "schema properties must have a description",
"truthy": "description"
}
]
}
}
Or in .oaslintrc.json
{
"loadDefaultRules": true,
"rules": [
{
"name": "schema-property-require-description",
"object": "schema",
"description": "schema properties must have a description",
"truthy": "description"
}
]
}
Run Jest
npx jest
# or with Yarn
yarn jest