Configuration
Getting started
We often have to pass more than one API Specification file to Specmatic to stub or test. While it is possible to send all the files as command line options, there is a better way.
Also if your contracts are stored in a source control system like Git, we need to provide details about the repository so that Specmatic can pull your specifications directly from your version control.
Here is a sample configuration to get you started.
-
{ "sources": [ { "provider": "git", "repository": "https://github.com/znsio/specmatic-order-contracts.git", "provides": [ "io/specmatic/examples/store/openapi/api_order_v3.yaml" ] } ] }
-
sources: - provider: git repository: https://github.com/znsio/specmatic-order-contracts.git provides: - io/specmatic/examples/store/openapi/api_order_v3.yaml
Place this file in the root folder of your project (Here is an example). Let us now go through each of the lines in this file.
- provider - At the moment we support all git based source control systems. Example: GitHub, Gitlab, Azure, etc.
- repository - The git repository URL
- provides - This is the list of API Specifications that need to be run as a test. Note that the path is relative to the source control repository root.
You can also specify the branch.
-
{ "sources": [ { "provider": "git", "repository": "https://github.com/znsio/specmatic-order-contracts.git", "branch": "feature-1", "provides": [ "io/specmatic/examples/store/openapi/api_order_v3.yaml" ] } ] }
-
sources: - provider: git repository: https://github.com/znsio/specmatic-order-contracts.git branch: feature-1 provides: - io/specmatic/examples/store/openapi/api_order_v3.yaml
When branch is not specified, default branch will be picked up.
Now if you run the specmatic test
command line executable from the directory that contains the specmatic.json
file Specmatic will pull the API Specifications listed under provides and run them as tests.
% java -jar /path/to/specmatic.jar test
Loading config file ./specmatic.json
Couldn't find local contracts, cloning https://github.com/znsio/specmatic-order-contracts.git into .specmatic/repos
Resetting /<path where you are running the specmatic command>/.specmatic/repos/specmatic-order-contracts
The logs show that Specmatic resets your local copy and clones the latest API Specification from the Git repository into a folder called .specmatic
. Please add this folder to .gitignore
.
Contract Test Timeout
The HTTP timeout duration for requests made during contract testing can be configured using timeoutInMilliseconds
parameter. This parameter sets the maximum time Specmatic will wait for a response to each HTTP request before marking it as a failure. The default timeout is 6000 milliseconds
.
-
{ "sources": [ { "provider": "git", "repository": "https://github.com/znsio/specmatic-order-contracts.git", "consumes": [ "io/specmatic/examples/store/openapi/api_order_v3.yaml" ] } ], "test": { "timeoutInMilliseconds": 3000 } }
-
sources: - provider: git repository: https://github.com/znsio/specmatic-order-contracts.git consumes: - io/specmatic/examples/store/openapi/api_order_v3.yaml test: timeoutInMilliseconds: 3000
Configuring Stubs
The same configuration file can be leveraged to define stubs also.
-
{ "sources": [ { "provider": "git", "repository": "https://github.com/znsio/specmatic-order-contracts.git", "consumes": [ "io/specmatic/examples/store/openapi/api_order_v3.yaml" ] } ] }
-
sources: - provider: git repository: https://github.com/znsio/specmatic-order-contracts.git consumes: - io/specmatic/examples/store/openapi/api_order_v3.yaml
Please note that now we are now listing the api_order_v3.yaml
is listed as a stub dependency. You can run the specmatic stub
command and the Specmatic will clone the API specifications and run it as a stub. Here is an example.
A single application may need to list the API Specifications it is implementing under the provides attribute and the API Specifications of its dependencies under the consumes attribute.
-
{ "sources": [ { "provider": "git", "repository": "<Git URL>", "consumes": [ "com/example/api_order_v1.yaml", "com/example/api_user_v1.yaml" ], "provides": [ "com/example/api_auth_v1.yaml", ] } ] }
-
sources: - provider: git repository: <Git URL> consumes: - com/example/api_order_v1.yaml - com/example/api_user_v1.yaml provides: - com/example/api_auth_v1.yaml
Service Virtualization Delay
A delay can be applied to all requests handled by service virtualization. By configuring the delayInMilliseconds
parameter, you can simulate response times with the specified delay in milliseconds, as mentioned in Delay Simulation
Use specifications on local file system
If you just need to use specifications from your local file system, specify provider
as filesystem
, as shown below.
-
{ "sources": [ { "provider": "filesystem", "consumes": [ "api_order_v1.yaml", "api_user_v1.yaml" ], "provides": [ "api_auth_v1.yaml", ] } ] }
-
sources: - provider: filesystem consumes: - api_order_v1.yaml - api_user_v1.yaml provides: - api_auth_v1.yaml
Note that the consumes
and provides
specifications are relative paths. This means that they must be in the same directory as the current directory.
You can also provide absolute paths in case they are somewhere else on the filesystem.
Use specifications from the web
-
{ "sources": [ { "provider": "web", "consumes": [ "http://third.party.com/products.yaml" ], "provides": [ "http://third.party.com/api_auth_v1.yaml", ] } ] }
-
sources: - provider: web consumes: - http://third.party.com/products.yaml provides: - http://third.party.com/api_auth_v1.yaml
Note that the consumes
and provides
can both contain URLs. http
and https
are both supported.
Source control authentication
Usually source control requires authentication. Below are the ways in which you can set it up.
- Recommended approach - Provide a Git SSH URL and make sure your environment already has necessary keys loaded. If the git clone command works on your regular command line, it will work within Specmatic too. This is most suitable in CI, because your CI server may already be setup to clone the application code (for which the CI server should already have the necessary keys). So it should already be able to clone your API Specifications also. The same also should be applicable for local development and testing environments.
- Alternatives - With https URLs you can provide the bearer token or other means. Please reach us (raise a github issue) if you need help with this.
Report Configuration
Specmatic can generate reports based on the below configuration:
-
"report": { "formatters": [ { "type": "text", "layout": "table" } ], "types": { "APICoverage": { "OpenAPI": { "successCriteria": { "minThresholdPercentage": 100, "maxMissedEndpointsInSpec": 0, "enforce": true }, "excludedEndpoints": [ "/health" ] } } } }
-
report: formatters: - type: text layout: table types: APICoverage: OpenAPI: successCriteria: minThresholdPercentage: 100 maxMissedEndpointsInSpec: 0 enforce: true excludedEndpoints: - /health
Formatters
Defaults to ‘Text’ if none specified.
The Text formatter will print the report on to the console/terminal.
Report Types
API Coverage report
This gives you a comprehensive analysis of any mismatch between your api specification and implementation. Here is an article with a detailed write-up about this feature.
Complete sample specmatic.json with all attributes
-
{ "sources": [ { "provider": "git", "repository": "https://azure.com/XNSio/XNSIO/_git/petstore-contracts", "branch": "main", "provides": [ "com/petstore/store.yaml" ], "consumes": [ "com/petstore/payment.yaml" ] } ], "auth": { "bearer-file": "central_repo_auth_token.txt" }, "pipeline": { "provider": "azure", "organization": "XNSio", "project": "XNSIO", "definitionId": 4 }, "environments": { "staging": { "baseurls": { "auth.spec": "http://localhost:8080" }, "variables": { "username": "jackie", "password": "PaSsWoRd" } } }, "hooks": { "hook_name": "command" }, "report": { "formatters": [ { "type": "text", "layout": "table" } ], "types": { "APICoverage": { "OpenAPI": { "successCriteria": { "minThresholdPercentage": 100, "maxMissedEndpointsInSpec": 0, "enforce": true }, "excludedEndpoints": [ "/health" ] } } } } }
-
sources: - provider: git repository: https://azure.com/XNSio/XNSIO/_git/petstore-contracts branch: main provides: - com/petstore/store.yaml consumes: - com/petstore/payment.yaml auth: bearer-file: central_repo_auth_token.txt pipeline: provider: azure organization: XNSio project: XNSIO definitionId: 4 environments: staging: baseurls: auth.spec: http://localhost:8080 variables: username: jackie password: PaSsWoRd hooks: hook_name: command report: formatters: - type: text layout: table types: APICoverage: OpenAPI: successCriteria: minThresholdPercentage: 100 maxMissedEndpointsInSpec: 0 enforce: true excludedEndpoints: - /health
Declare pipeline details
Contains details of the project pipeline.
-
{ "auth": { "bearer-file": "./central_repo_auth_token.txt" }, "pipeline": { "provider": "azure", "organization": "XNSio", "project": "XNSIO", "definitionId": 4 } }
-
auth: bearer-file: ./central_repo_auth_token.txt pipeline: provider: azure organization: XNSio project: XNSIO definitionId: 4
auth
section is needed for Azure pipelinespipeline
section is used by Specmatic install, to register a project’s build pipeline to run when a contract changes.provider
should remainazure
, no need to change this- Details such as
organization
,project
anddefinitionId
must be set up as per your project.
Specmatic fetches contracts from git repositories in Azure using the value of the pipeline variable System.AccessToken
for authentication. This is a predefined variable in Azure build pipelines.
It looks for this value in the file specified by bearer-file
. central_repo_auth_token.txt
is our recommended name for the file. This file should be in your project root.
You can set it up by placing this snippet in the steps
section of your Azure pipeline:
steps:
- script: echo $SYSTEM_ACCESSTOKEN > central_repo_auth_token.txt
env:
SYSTEM_ACCESSTOKEN: $(System.AccessToken)
You can read more about System.AccessToken
here.
Declare environment configuration
-
"environments": { "staging": { "baseurls": { "auth.spec": "http://localhost:8080" }, "variables": { "username": "jackie", "password": "PaSsWoRd" } } }
-
environments: staging: baseurls: auth.spec: http://localhost:8080 variables: username: jackie password: PaSsWoRd
The environments key in this example contains configuration for the staging
environment. It can contain configuration for any number of environments.
Each environment configuration can contain
baseurls
- needed when running contracts as test as part of authenticationvariables
- these values are plugged into the Examples rows of an auth contract for authentication, or even when running regular contract tests
Hooks
A hook is simply a command that can run on the Terminal or Command Prompt.
-
{ "hooks": { "stub_load_contract": "python load.py" } }
-
hooks: stub_load_contract: python load.py
In the above snippet, stub_load_contract
is the hook name. python load.py
is executed, while the path of the original contract file is present in CONTRACT_FILE
environment variable.
The command can parse the contract file and write it to standard out. Specmatic will read it as the new contract. stub_load_contract
and test_load_contract
are the supported hook names.