Skip to main content

Mock Configuration

Configuring Mocks​

The same configuration file can be leveraged to define mocks 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.

Mock Start Timeout​

The startTimeoutInMilliseconds setting in Specmatic ensures that a mock service, whether started via the mock 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

AsyncAPI Mock Configuration​

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

Start with AsyncAPI Configuration for the server model, inline and referenced servers, shared and per-spec settings, and complete examples.

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
            schemaRegistry:
              kind: CONFLUENT
              url: ${SCHEMA_REGISTRY_URL:http://localhost:8085}
              username: admin
              password: admin-secret
            servers:
              - server:
                  host: ${KAFKA_BROKER:localhost:9092}
                  protocol: kafka
                  type: external
                  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​

PropertyDescription
typeMust be mock for AsyncAPI service virtualization.
serversShared runtime server list. At least one effective server is required.
servers[].server.hostBroker host or endpoint for an inline server.
servers[].server.protocolMessaging protocol used by the server.
specs[].spec.servers[].server.$serverRefAsyncAPI 3 local server reference used in a per-spec override instead of host and protocol.
servers[].server.typeRequired lifecycle: external or in-memory.
servers[].server.adminCredentialsProtocol-specific admin properties used to provision or inspect broker resources.
servers[].server.client.producerProducer client properties passed through to the protocol client.
servers[].server.client.consumerConsumer client properties passed through to the protocol client.
specsOptional per-spec overrides selected by specification id.
schemaRegistryOptional schema registry settings for Avro-based AsyncAPI mocks.
schemaRegistry.kindSchema registry type. Currently CONFLUENT is supported.
schemaRegistry.urlSchema registry endpoint URL.
schemaRegistry.usernameOptional username for the schema registry.
schemaRegistry.passwordOptional password for the schema registry.

Notes​

  • Mark a server type: in-memory when Specmatic should start it. Kafka, JMS, and AMQP support in-memory brokers.
  • Mark a server type: external when Specmatic should connect to an existing broker.
  • inMemoryBroker is deprecated. Replace it with a server entry whose type is in-memory; see migration guidance.
  • 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.

gRPC Mock Configuration Commercial​

gRPC mocks use runOptions.protobuf.

runOptions:
  protobuf:
    type: mock
    port: 50051
    importPaths:
      - ./proto-imports
    protocVersion: 3.25.5

port is optional when it is supplied by the command that starts the mock. importPaths supplies directories used to resolve imported proto files, and protocVersion selects the compiler version.

GraphQL Mock Configuration Commercial​

GraphQL SDL mocks use runOptions.graphqlsdl.

runOptions:
  graphqlsdl:
    type: mock
    host: 0.0.0.0
    port: 9000

Both host and port are optional. When omitted, Specmatic uses the protocol defaults.

Strict Mode​

Mock may run in strict mode. You can read more about mock in strict mode here.

You can configure Specmatic to run mock server 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 Mock Server on Different Ports for Different Specifications​

If you want to run mock server 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.