Link Search Menu Expand Document


Most APIs will not run unless provided a valid authentication token. When running contract tests, Specmatic needs to obtain a valid auth token to call authenticated APIs.

You can see how this in action in the sample petstore project.

Here’s a quick walk through of how it works.

1. Write the auth contract

First off, write the contract of the auth API, and in it, declare tokens such as cookies, json value in the response, etc as exports.

In step 3, Specmatic will run this as as a test against the auth service to get the auth tokens. So we must provide the base url of the actual auth service in environment configuration.

Here’s a the petstore’s auth contract.

Setup the auth credentials

Look at the Examples table, in which we use the variables $username and $password. We do not hardcode them, because each environment (local, staging, etc) will need different auth credentials. These values come from environment configuration, where we can specify the auth credentials needed by each environment. See how this is done in specmatic.json in the sample petstore application.

Note how we have declared two variables, username and password, in the staging environment:

  "environments": {
    "staging": {
      "baseurls": {
        "auth.spec": "http://localhost:8080"
      "variables": {
        "username": "jackie",
        "password": "PaSsWoRd"

Setup base urls

In step 3, Specmatic runs this auth.spec as a test against the auth service in the environment, and stores the exports declared by auth.spec for later.

To run as test, Specmatic needs the base url of the auth service. We put this in the same environment config in specmatic.json.

In the snippet above, baseurls contains configuration for auth.spec, the name of the auth contract file.

Exporting auth tokens in the contract

In the auth.spec file, we have exported the entire response body.

And export token = response-body

This exports a variable named token, the contents of which are the entire reponse body.

If the reponse is JSON, such as {"token": "abc123"}, you can export a specific value:

And export token = response-body.token

If you wish to export a header, such as the Cookie header:

And export cookie = response-header.Cookie

2. Wire up auth in the application contract

Next we must connect auth contract with the actual contract that needs it.

Have a look at the sample petstore contract api_petstore_v1.spec.

You’ll see in the background:

And value auth from auth.spec

We declare that the value named auth comes from auth.spec. auth.spec in this line is the relative path to the auth spec file. In this example, auth.spec is in the same directory as api_1.spec.

Using the auth variables

In the petstore contract, look at the Examples table for any of the POST APIs, to see how we are using the auth token.

Take for example:

 Scenario Outline: Update pet details
    When POST /pets
    And request-header Authenticate (string)
    And request-body (Pet)
    Then status 200

      | name   | type | status    | id | Authenticate  |
      | Archie | dog  | available | 10 | ($auth.token) |

In ($auth.token), auth is the value that we declared above, and token is what was exported from auth.spec.

3. Run the contract tests

Declare the application contract in specmatic.json

Make sure to declare the contract you’re running as a test in specmatic.json. Take a look at specmatic.json in the petstore sample project for an example of this. You can read more about running contract tests using Specmatic here.

Execute the tests

Finally, run the tests. You must specify the environment while doing so, for Specmatic to pick up the variables and baseurls relevant to that environment.

If you’re running the tests from a terminal, the command is specmatic test --environment=staging specfile.spec

If you’re running the tests from code, set a property named environments. Take a look at the petstore sample to see an example of this.

How Specmatic runs the tests

The tests are run in 2 stages.

  • Stage 1: The application contract depends on the auth contract. So Specmatic first runs the auth contract as test, and stores all the exported values for the application contract to use.
  • Stage 2: Specmatic then plugs the exported values into the application contract where required, and goes on to run the application contract in test mode.