Format of specmatic.json

Format of specmatic.json

Sample specmatic.json

{
  "sources": [
    {
      "provider": "git",
      "repository": "https://azure.com/XNSio/XNSIO/_git/petstore-contracts2",
      "test": [
        "com/petstore/2.spec"
      ],
      "stub": [
        "com/petstore/payment.spec"
      ]
    }
  ],

  "auth": {
    "bearer-file": "bearer.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"
  }
}

Declare contracts

Contains a list of git repositories containing contract files.

  "sources": [
    {
      "provider": "git",
      
      // repository containing the contracts
      "repository": "https://azure.com/XNSio/XNSIO/_git/petstore-contracts2",
      
      // relative paths of all contracts in this repository
      // to be run as test
      "test": [
        "com/petstore/2.spec"
      ],

      // relative paths of all contracts in this repository
      // to be stubbed out
      "stub": [
          "com/petstore/payment.spec"
      ]
    }
  ],

Declare pipeline details

Contains details of the project pipeline.

  // Needed for Azure CI. See notes below this snippet.
  "auth": {
    "bearer-file": "./bearer.txt"
  },

  // pipeline details of this project
  //
  // This is used by specmatic install, to register
  //    a project's build pipeline to run when a contract changes
  // The details below must be replaced with the details relevant
  //   to your project
  "pipeline": {
    "provider": "azure", // pipeline type, leave as is
    
    // Azure organization name
    "organization": "XNSio",
    
    // Azure project name
    "project": "XNSIO",
    
    // Azure build pipeline definition id
    "definitionId": 4
  }
}

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. bearer.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 > bearer.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"
      }
    }
  }

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 authentication
variables - 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"
  }

In the above snippet, stub_load_contract is the hook name. “python load.py” runs and is passed the contract file name just before a contract is loaded. The hook can modify the contract and post it to standard output.