Skip to main content

Migrating from specmatic-kafka and specmatic-async to Specmatic Enterprise

Migrating to Specmatic Enterprise unlocks multi-protocol support, improved configuration, and a unified approach to async contract testing and mocking. This guide walks you through the key steps for a smooth transition.

Migration Steps​

1. Consolidate Configuration​

Move all your configuration into specmatic.yaml. If you have a specmatic-kafka-config.properties file, migrate those properties into the specmatic.yaml config and delete the properties file.

Example specmatic.yaml:

version: 3

systemUnderTest:
  service:
    $ref: "#/components/services/orderService"
    runOptions:
      "$ref": "#/components/runOptions/orderServiceRunOptions"


components:
  sources:
    centralContractRepo:
      filesystem:
        directory: "."
  services:
    orderService:
      description: "Order Service"
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContractRepo"
            specs:
              - spec:
                  path: 'spec/order-service.yaml'
  certificates:
    clientCertificate:
      keyStore:
        file: "path/to/keystore.jks"
        password: "keystore-password"

  runOptions:
    orderServiceRunOptions:
      asyncapi:
        type: test
        servers:
          - host: "<SQS_QUEUE_URL>"
            protocol: sqs
            adminCredentials:
              region: "<REGION>"
              aws.access.key.id: "<AWS_ACCESS_KEY_ID>"
              aws.secret.access.key: "<AWS_SECRET_ACCESS_KEY>"
          - host: "<KAFKA_BROKER_URL>"
            protocol: kafka
            adminCredentials:
              security.protocol: SASL_PLAINTEXT
              sasl.mechanism: PLAIN
              sasl.jaas.config: org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="admin-secret";
            client:
              producer:
                $ref: "#/components/certificates/clientCertificate"
              consumer:
                $ref: "#/components/certificates/clientCertificate"

Refer to the Configuration Reference for all available options.

2. Update Docker Image​

Replace the specmatic/specmatic-kafka or specmatic/specmatic-async image with specmatic/enterprise in your Docker commands.

Before:

docker run specmatic/enterprise test

After:

docker run specmatic/enterprise test

3. Update Programmatic Usage​

If you use Specmatic mocks/tests in code, update class names and imports:

  • Replace KafkaMock with AsyncMock
  • Replace SpecmaticKafkaContractTest or SpecmaticAsyncContractTest with io.specmatic.enterprise.SpecmaticContractTest

Before:

import com.specmatic.kafka.KafkaMock;
import com.specmatic.kafka.SpecmaticKafkaContractTest;

public class KafkaContractTest implements SpecmaticKafkaContractTest {
    // ...
}

After:

import io.specmatic.enterprise.SpecmaticContractTest

public class AsyncContractTest implements SpecmaticContractTest {
    // ...
}

Additional Resources​