Mock Configuration

Configuring Stubs

The same configuration file can be leveraged to define stubs also.

Version 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    apiOrderV3:
      description: API Order V3
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3"
        }
      }
    ]
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "apiOrderV3": {
        "description": "API Order V3",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    consumes:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/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 dependency. You can run the specmatic mock command and the Specmatic will clone the API specifications and run it as a mock. Here is an example.

Stub Start Timeout

The startTimeoutInMilliseconds setting in Specmatic ensures that a mock service, whether started via the stub command or programmatically using createStub method exits if it doesn't start within the defined time.

Version 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
  settings:
    startTimeoutInMilliseconds: 10000
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    apiOrderV3:
      description: API Order V3
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3"
        }
      }
    ],
    "settings": {
      "startTimeoutInMilliseconds": 10000
    }
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "apiOrderV3": {
        "description": "API Order V3",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    consumes:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml
stub:
  startTimeoutInMilliseconds: 10000

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/specmatic-order-contracts.git"
      },
      "consumes": [
        "io/specmatic/examples/store/openapi/api_order_v3.yaml"
      ]
    }
  ],
  "stub": {
    "startTimeoutInMilliseconds": 10000
  }
}

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

Version 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
  settings:
    delayInMilliseconds: 10000
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    apiOrderV3:
      description: API Order V3
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3"
        }
      }
    ],
    "settings": {
      "delayInMilliseconds": 10000
    }
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "apiOrderV3": {
        "description": "API Order V3",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    consumes:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml
stub:
  delayInMilliseconds: 10000

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/specmatic-order-contracts.git"
      },
      "consumes": [
        "io/specmatic/examples/store/openapi/api_order_v3.yaml"
      ]
    }
  ],
  "stub": {
    "delayInMilliseconds": 10000
  }
}

AsyncAPI Mock Configuration

AsyncAPI mocks use runOptions.asyncapi in specmatic.yaml. This is where Specmatic reads the async mock settings represented by AsyncMockConfig.

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        definitions:
          - definition:
              source:
                filesystem:
                  directory: api-specs
              specs:
                - order-service-async-avro-v3_0_0.yaml
        runOptions:
          asyncapi:
            type: mock
            inMemoryBroker:
              host: localhost
              port: 9092
              logDir: ./kafka-logs
            schemaRegistry:
              kind: CONFLUENT
              url: ${SCHEMA_REGISTRY_URL:http://localhost:8085}
              username: admin
              password: admin-secret
            servers:
              - host: localhost:9092
                protocol: kafka
                adminCredentials:
                  security.protocol: SASL_PLAINTEXT
                  sasl.mechanism: PLAIN
                  sasl.jaas.config: org.apache.kafka.common.security.plain.PlainLoginModule required username="test" password="test-secret";
                client:
                  producer:
                    basic.auth.credentials.source: USER_INFO
                    basic.auth.user.info: admin:admin-secret
                  consumer:
                    basic.auth.credentials.source: USER_INFO
                    basic.auth.user.info: admin:admin-secret

JSON

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "definitions": [
            {
              "definition": {
                "source": {
                  "filesystem": {
                    "directory": "api-specs"
                  }
                },
                "specs": [
                  "order-service-async-avro-v3_0_0.yaml"
                ]
              }
            }
          ],
          "runOptions": {
            "asyncapi": {
              "type": "mock",
              "inMemoryBroker": {
                "host": "localhost",
                "port": 9092,
                "logDir": "./kafka-logs"
              },
              "schemaRegistry": {
                "kind": "CONFLUENT",
                "url": "${SCHEMA_REGISTRY_URL:http://localhost:8085}",
                "username": "admin",
                "password": "admin-secret"
              },
              "servers": [
                {
                  "host": "localhost:9092",
                  "protocol": "kafka",
                  "adminCredentials": {
                    "security.protocol": "SASL_PLAINTEXT",
                    "sasl.mechanism": "PLAIN",
                    "sasl.jaas.config": "org.apache.kafka.common.security.plain.PlainLoginModule required username=\"test\" password=\"test-secret\";"
                  },
                  "client": {
                    "producer": {
                      "basic.auth.credentials.source": "USER_INFO",
                      "basic.auth.user.info": "admin:admin-secret"
                    },
                    "consumer": {
                      "basic.auth.credentials.source": "USER_INFO",
                      "basic.auth.user.info": "admin:admin-secret"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
}

AsyncAPI Mock Options

Property	Description
type	Must be mock for AsyncAPI service virtualization.
inMemoryBroker	Optional configuration for the embedded broker. When inMemoryBroker.port is set, Specmatic starts an in-memory broker instead of using an external one.
inMemoryBroker.host	Host name for the embedded broker. Default: localhost.
inMemoryBroker.port	Port for the embedded broker. Required when you want to run an in-memory broker.
inMemoryBroker.logDir	Directory used for broker logs. Defaults to ./<protocol>-logs.
servers	List of broker endpoints the mock should expose or connect to. Specmatic matches entries by protocol.
servers[].host	Broker host or endpoint. For Kafka, this is typically host:port.
servers[].protocol	Messaging protocol such as kafka, sqs, sns, jms, or rabbitmq.
servers[].adminCredentials	Protocol-specific admin properties used to provision or inspect broker resources.
servers[].client.producer	Producer client properties passed through to the protocol client.
servers[].client.consumer	Consumer client properties passed through to the protocol client.
schemaRegistry	Optional schema registry settings for Avro-based AsyncAPI mocks.
schemaRegistry.kind	Schema registry type. Currently CONFLUENT is supported.
schemaRegistry.url	Schema registry endpoint URL.
schemaRegistry.username	Optional username for the schema registry.
schemaRegistry.password	Optional password for the schema registry.

Notes

• In-memory broker support is intended for Kafka mocking. If inMemoryBroker is omitted, Specmatic expects the broker connection details to be available under servers.
• adminCredentials, client.producer, and client.consumer are protocol-specific maps. For Kafka, use standard Kafka client properties.
• schemaRegistry is only needed when your AsyncAPI examples or payload schemas depend on a registry.
• For Kafka-specific guidance, see Kafka.

Strict Mode

Stub may run in strict mode. You can read more about stub in strict mode here.

You can configure Specmatic to run stub in strict mode using the following configuration:

Version 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
  settings:
    strictMode: true
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    apiOrderV3:
      description: API Order V3
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3"
        }
      }
    ],
    "settings": {
      "strictMode": true
    }
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "apiOrderV3": {
        "description": "API Order V3",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - consumes:
      - /path/to/spec.yaml
stub:
  strictMode: true

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "consumes": [
        "/path/to/spec.yaml"
      ]
    }
  ],
  "stub": {
    "strictMode": true
  }
}

Run Stub on Different Ports for Different Specifications

If you want to run stubs on different ports for different specifications, you can specify the port number in the port field under consumes key and assign the list of specs to it.

Version 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/order-svc"
        runOptions:
          $ref: "#/components/runOptions/order-svc-mock"
    - service:
        $ref: "#/components/services/online-store-svc"
        runOptions:
          $ref: "#/components/runOptions/online-store-svc-mock"
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  runOptions:
    order-svc-mock:
      openapi:
        type: mock
        host: localhost
        port: 9000
    online-store-svc-mock:
      openapi:
        type: mock
        host: localhost
        port: 9001
  services:
    order-svc:
      description: Order service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v1.yaml
              - io/specmatic/examples/store/openapi/api_uuid_v1.yaml
    online-store-svc:
      description: Online Store Service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/online_store_v1.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/order-svc",
          "runOptions": {
            "$ref": "#/components/runOptions/order-svc-mock"
          }
        }
      },
      {
        "service": {
          "$ref": "#/components/services/online-store-svc",
          "runOptions": {
            "$ref": "#/components/runOptions/online-store-svc-mock"
          }
        }
      }
    ]
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "runOptions": {
      "order-svc-mock": {
        "openapi": {
          "type": "mock",
          "host": "localhost",
          "port": 9000
        }
      },
      "online-store-svc-mock": {
        "openapi": {
          "type": "mock",
          "host": "localhost",
          "port": 9001
        }
      }
    },
    "services": {
      "order-svc": {
        "description": "Order service",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v1.yaml",
                "io/specmatic/examples/store/openapi/api_uuid_v1.yaml"
              ]
            }
          }
        ]
      },
      "online-store-svc": {
        "description": "Online Store Service",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/online_store_v1.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    consumes:
      - specs:
          - io/specmatic/examples/store/openapi/api_order_v1.yaml
          - io/specmatic/examples/store/openapi/api_uuid_v1.yaml
        port: 9000
      - specs:
          - io/specmatic/examples/store/openapi/online_store_v1.yaml
        port: 9001

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/specmatic-order-contracts.git"
      },
      "consumes": [
        {
          "specs": [
            "io/specmatic/examples/store/openapi/api_order_v1.yaml",
            "io/specmatic/examples/store/openapi/api_uuid_v1.yaml"
          ],
          "port": 9000
        },
        {
          "specs": [
            "io/specmatic/examples/store/openapi/online_store_v1.yaml"
          ],
          "port": 9001
        }
      ]
    }
  ]
}

As per the above configuration, the specs api_order_v1.yaml and api_uuid_v1.yaml will run on port 9000 and the spec online_store_v1.yaml will run on port 9001.

You can also specify host, basePath, and even the complete baseUrl in the consumes field. For more details, refer to the Service Virtualization

Externalized Examples Directories

By default, Specmatic searches for the directory ending with _examples to pickup externalized examples. However, if needed, you can specify a list of directories containing externalized examples under examples key in specmatic configuration. Specmatic will retrieve the examples from these directories for use in both contract testing and service virtualization.

Version 3 (recommended)

YAML

specmatic.yaml

version: 3
systemUnderTest:
  service:
    $ref: "#/components/services/productSearchBffV4"
    runOptions:
      openapi:
        type: mock
        host: localhost
        port: 9000
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
        runOptions:
          openapi:
            type: mock
            host: localhost
            port: 9001
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    productSearchBffV4:
      description: Product Search BFF v4 (provider)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/product_search_bff_v4.yaml
    apiOrderV3:
      description: API Order V3 (consumer)
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml
  examples:
    commonExamples:
      directories:
        - order_service/examples
        - product_service/examples

specmatic.json

specmatic.json

{
  "version": 3,
  "systemUnderTest": {
    "service": {
      "$ref": "#/components/services/productSearchBffV4",
      "runOptions": {
        "openapi": {
          "type": "mock",
          "host": "localhost",
          "port": 9000
        }
      }
    }
  },
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3",
          "runOptions": {
            "openapi": {
              "type": "mock",
              "host": "localhost",
              "port": 9001
            }
          }
        }
      }
    ]
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "productSearchBffV4": {
        "description": "Product Search BFF v4 (provider)",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/product_search_bff_v4.yaml"
              ]
            }
          }
        ]
      },
      "apiOrderV3": {
        "description": "API Order V3 (consumer)",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    },
    "examples": {
      "commonExamples": {
        "directories": [
          "order_service/examples",
          "product_service/examples"
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    provides:
      - io/specmatic/examples/store/openapi/product_search_bff_v4.yaml
    consumes:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml
examples:
  - order_service/examples
  - product_service/examples

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/specmatic-order-contracts.git"
      },
      "provides": [
        "io/specmatic/examples/store/openapi/product_search_bff_v4.yaml"
      ],
      "consumes": [
        "io/specmatic/examples/store/openapi/api_order_v3.yaml"
      ]
    }
  ],
  "examples": [
    "order_service/examples",
    "product_service/examples"
  ]
}

note

When using v2 config, if the _examples directory is present, it will still be included alongside any additional directories specified under the examples key.

When using v3 config, the examples will be loaded from directory with the name ${SPEC_FILE}_examples if it exists, in addition to any directories specified under the examples key. For example, if you have a spec file named api_order_v1.yaml, Specmatic will look for examples in the api_order_v1_examples directory by default, even if it's not explicitly mentioned in the configuration.