🥑 Continuous contract testing tool for HTTP APIs
Avocat is a continuous contract testing tool for HTTP APIs. It allows running integration tests between different modules. Make sure you have your APIs contracts written in (YAML, RAML, JSON or XML), then you're ready to get started!
Avocat installation is a simple process. It won't take too much of your time 😉
- npm version >=6.12.1
- node version >=10.15.3
-
Clone this git repository into a local directory
$ git clone [email protected]:salesforce/Avocat.git
-
Open it
$ cd avocat
-
Install npm dependencies
$ npm install
-
Install Avocat globally
$ npm r -g avocat && npm i -g
-
That's it! You can start Avocat
$ avocat
Trust is our number one value. We have strict quality checks and metrics to ensure it is always respected.
- We use Jest to write tests, you can run them easily with
$ npm test
- We use Jest to generate snapshots of avocat expected UX, in case of modifications update them with
$ npm run test:updateSnapshot
- We use Jest to measure code coverage as well, you can run it easily with
$ npm run coverage
- We use ESlint to validate code style conformance, and it applies StandardJS set of rules. Validate your code with
$ npm run validate
Before you start using avocat, make sure you've installed it globally, otherwise refer to Installation section.
-
status
This command allows you check if there is pending changes in your local repositories. It takes no parameters or options.
e.g.$ avocat status
See more detailed examples here. -
import
This command allows you to import new contract version into the local store. It takes one parameter which is your contract file.
e.g.$ avocat import '/path/to/contract'
See more detailed examples here.Note that the import command uses the directory ~/.avocat as the default local store. In case you need to override it, please set the AVOCAT_STORE_DIR environment variable with the desired directory value.
e.g.$ export AVOCAT_STORE_DIR='/path/to/store'
-
test
This command allows you to validate contracts in your local repository. You need to add some options to specify contracts on which you're running validations.Available options:
- url (required): Server url in which the APIs are hosted e.g. https://www.example.com/
- name (optional): Specify a contract name to run tests on e.g. "Search Mru"
- version (optional): Specify a contract version to run tests on e.g. 49
Behaviour:
- When only a contract name option is provided, tests will be run on all the contract versions
- When only a contract version option is provided, tests will be run on all the contracts having the provided version
- When both name and version options are provided, tests will be run on contract’s specified version only
- When neither name nor version are provided, an error message will be displayed "Insufficient criteria"
e.g.
$ avocat test --url http://www.example.com/services --name 'My Contract' --version 2.1
See more detailed examples here.Note that the test command uses the SID environment variable to get the Bearer authorization token. Please update it with a valid token before you start testing. However, more authentication types will be implemented in the future.
e.g.$ export SID='This is a valid token'
-
env
This command allows you to manage the configuration of the environments you're running tests on. Instead of looking for the right URL each time you want to switch the testing environment, you can add them using the adding command.An environment configuration contains a unique name, an url and an authentication token (which could be updated regularly).
e.g.$ avocat env:add --name MyEnv --url http://www.example.com/services --token MyAuthToken
To view the available environments, you can run the list command.
e.g.$ avocat env:list
Then, you can use one of your added environments with the test command.
e.g.$ avocat test --env MyEnv --name 'My Contract' --version 2.1
See more detailed examples here.
-
help
Show available commands/options -
loglevel
Show verbose output depending on the specified log level. This option takes one parameter which is the level.
Allowed values: TRACE|DEBUG|INFO|WARN|ERROR|SILENT (case-insensitive)
Default value: SILENT
e.g.$ avocat status --loglevel DEBUG
Despite the capabilities of OpenAPI Specification, we still can't define different responses based on a parameter existence or value
(check the docs here).
However, we introduce a way here to override a default scenario using an OpenAPI custom extension (x-scenario-override).
Define this extension under a response object, then set its value with an API path that contains custom parameters values.
Check out this example below, an invalid value for a param is set to receive 400 response:
responses:
400:
description: "Invalid input"
x-scenario-override: "/path/to/API?param=INVALID_VALUE"
This section describes our code files structure.
Could be found in avocat/src directory.
|_ main # source code and unit tests
|_ app # commands UX management
|_ core # avocat business logic
|_ infrastructure # repositories and 3rd party calls
|_ index.ts # loads CliApp and runs avocat
|_ test # integration tests and test utils
All config files could be found under the root directory.
- package.json: Avocat manifest, scripts and dependencies.
- tsconfig.json: contains ts-node config.
- jest.config.js: contains Jest config.
- .eslintrc.js: contains eslint config.
We've added some custom scripts that might be useful when coding in Avocat.
-
ts-node: this command is an alternative way to run avocat when you don't want to install it globally every time. You can run it with
$ ts-node src/main/index.ts
-
Build: this command transpiles typescript code into javascript. Transpiled files could be found in avocat/dist folder. You can run it with
$ npm run build
-
Refresh: this command removes node_modules directory and package-lock.json file, then re-installs new versions of dependencies. You can run it with
$ npm run refresh
Format | Status |
---|---|
OpenAPI | In progress |
RAML | Not supported |
JSON | Not supported |
XML | Not supported |
The BSD 3-Clause license governs your use of Avocat.