Skip to main content

Mock Configuration

Configuring Stubs​

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

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

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.

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

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

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

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:

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

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.

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

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.

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
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.