Skip to main content

Complete Configuration Examples

Complete Sample Configuration with All Attributes​

This example shows all available configuration options:

version: 3
systemUnderTest:
  service:
    $ref: "#/components/services/onlineStoreServiceV1"
    runOptions:
      $ref: "#/components/runOptions/onlineStoreServiceV1Test"
dependencies:
  services:
    - service:
        $ref: "#/components/services/orderServiceV1"
        runOptions:
          $ref: "#/components/runOptions/orderServiceV1Mock"
components:
  sources:
    centralContractRepo:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    onlineStoreServiceV1:
      description: Online Store Service (V1)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContractRepo"
            specs:
              - io/specmatic/examples/store/openapi/online_store_v1.yaml
    orderServiceV1:
      description: Payment Service (V1)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContractRepo"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v1.yaml
  runOptions:
    onlineStoreServiceV1Test:
      openapi:
        type: test
        baseUrl: http://localhost:8080
    orderServiceV1Mock:
      openapi:
        type: mock
        baseUrl: http://localhost:8090
  adapters:
    stub-hoks:
      test_load_contract: python test_load_contract.py
      stub_load_contract: python stub_load_contract.py
      post_specmatic_response_processor: python post_specmatic_response_processor.py
      pre_specmatic_request_processor: python pre_specmatic_request_processor.py
      pre_specmatic_response_processor: python pre_specmatic_response_processor.py
specmatic:
  settings:
    backwardCompatibility:
      strictMode: true
      baseBranch: origin/v3
      mock:
        delayInMilliseconds: 1000
        generative: true
      test:
        timeoutInMilliseconds: 1000
  governance:
    report:
      formats:
        - ctrf
        - html
      outputDirectory: reports/specmatic
    successCriteria:
      enforce: true
      maxMissedOperationsInSpec: 10
      minCoveragePercentage: 75
  license:
    path: "{LICENSE_PATH:/path/to/license/file-or-directory}"

Configuration Structure Summary (v3)

The complete configuration file supports the following top-level sections:

  1. version - Configuration version number (latest being 3).
  2. components - Reusable components and definitions. Key sub-sections include:
    • components.sources - Define contract sources (Git repositories or filesystem locations) used to load API specs.
    • components.services - Service definitions referenced by systemUnderTest and dependencies. Each service typically contains definitions which reference a source and one or more specs.
    • components.runOptions - Named run configurations (for example, openapi.type = test or mock, and baseUrl)
    • components.adapters - Adapter definitions for massaging contract specifications, or for mutating request/responses from the proxy and/or stub.
  3. systemUnderTest - Defines the primary system under test. Contains a components.service entry and usually an associated runOptions profile for executing contract tests.
  4. dependencies - Defines dependent services used for service virtualization. Typically contains a services array where each item references a components.services entry and optional runOptions (often used to point to mock instances).
  5. specmatic - Specmatic-specific configuration:
    • specmatic.settings - Runtime and backward-compatibility settings (mock/test options, strictMode, baseBranch, delays, timeouts, etc.).
    • specmatic.governance - Reporting and success criteria (formats, outputDirectory, enforcement thresholds).
    • specmatic.license - License path or configuration.

For detailed information on each section, refer to the linked documentation pages.

HTTPS and mTLS Configuration Snippets​

Use these snippets alongside the complete examples above when configuring certificates.

Contract testing against an mTLS service (outgoing client cert)​

specmatic.yaml
version: 3
systemUnderTest:
  service:
    definitions:
      - definition:
          source:
            filesystem:
              directory: ./specs
          specs:
            - employee-api.yaml
    runOptions:
      openapi:
        baseUrl: https://<sut-host>:<sut-port>
        cert:
          keyStore:
            file: <path-to-jks-file>
            alias: <keystore-alias>
            password: <key-password>
          keyStorePassword: <keystore-password>

Mock with incoming mTLS enabled (client cert required)​

specmatic.yaml
version: 3
dependencies:
  services:
    - service:
        definitions:
          - definition:
              source:
                filesystem:
                  directory: ./specs
              specs:
                - <path-to-openapi-or-wsdl-file>
        runOptions:
          openapi:
            baseUrl: https://<mock-host>:<mock-port>
            cert:
              mtlsEnabled: true
              keyStore:
                file: <path-to-jks-file>
                alias: <keystore-alias>
                password: <key-password>
              keyStorePassword: <keystore-password>

Notes​

  • Use mtlsEnabled to enable incoming mTLS for mocks.
  • incomingMtlsEnabled is not a supported configuration key.