Migrating to Specmatic Enterprise

This guide helps you migrate from legacy commercial Specmatic artifacts (viz. openapi, asyncapi, studio, grpc and graphql) to the unified Specmatic Enterprise artifact.

For a broader migration path (including send-report migration and config v2 to v3), see the Migration Guide.

What changed

All legacy artifacts have moved into a single artifact and image:

• New Maven/Gradle coordinates: io.specmatic.enterprise:executable
• New Docker image: specmatic/enterprise

Why change

Moving to the unified enterprise artifact helps you by:

• Reducing dependency and image sprawl across OpenAPI/AsyncAPI/Studio/gRPC/GraphQL.
• Simplifying upgrades and governance with a single version, artifact, and image to track.
• Standardizing tooling and behavior across protocol-specific workflows.
• Simplifying onboarding and licensing with one artifact and image to learn and manage.
• Letting multi-protocol applications use a single artifact and image, and receive new features across protocols at once.

Quick before/after

Docker (example):

docker run --rm specmatic/specmatic-openapi test contract.yaml

docker run --rm specmatic/enterprise test contract.yaml

Maven/Gradle (example): replace any legacy coordinates with io.specmatic.enterprise:executable.

Artifact mapping

Replace each legacy artifact with the new unified artifact:

Maven/Gradle coordinates

Module	Legacy coordinates	New coordinates
Specmatic OpenAPI	io.specmatic.openapi:specmatic-openapi	io.specmatic.enterprise:executable
Specmatic AsyncAPI	io.specmatic.async:specmatic-async	io.specmatic.enterprise:executable
Specmatic gRPC	io.specmatic.grpc:specmatic-grpc	io.specmatic.enterprise:executable
Specmatic GraphQL	io.specmatic.graphql:specmatic-graphql	io.specmatic.enterprise:executable

Docker images

Module	Legacy image	New image
Specmatic OpenAPI	specmatic/specmatic-openapi	specmatic/enterprise
Specmatic AsyncAPI	specmatic/specmatic-async	specmatic/enterprise
Specmatic Studio	specmatic/studio	specmatic/enterprise
Specmatic gRPC	specmatic/specmatic-grpc	specmatic/enterprise
Specmatic GraphQL	specmatic/specmatic-graphql	specmatic/enterprise

JUnit runner update

If your tests used Junit integration, your "ContractTest" implemented a JUnit Runner interface from the legacy artifact. Replace it with the simplified interface:

Interface mapping

Module	Old interface(s)	New interface
Specmatic OpenAPI	io.specmatic.test.SpecmaticJUnitSupport or io.specmatic.test.SpecmaticContractTest	io.specmatic.enterprise.SpecmaticContractTest
Specmatic AsyncAPI	io.specmatic.async.test.SpecmaticAsyncContractTest	io.specmatic.enterprise.SpecmaticContractTest
Specmatic gRPC	io.specmatic.grpc.junit.SpecmaticGrpcContractTest	io.specmatic.enterprise.SpecmaticContractTest
Specmatic GraphQL	io.specmatic.graphql.test.SpecmaticGraphQLContractTest	io.specmatic.enterprise.SpecmaticContractTest

note

SpecmaticContractTest is a marker interface (no methods to implement). It automatically starts Specmatic mocks and runs your contract tests, so no extra Specmatic configuration is required. If your test class manually sets up mocks/stubs, remove that code when migrating. In some environments, mocks may bind to random ports (when depending on multiple specs); use Specmatic configuration version 3 to improve per-mock port binding. Your existing JUnit annotations will continue to work:

Maven

pom.xml

<dependency>
  <groupId>io.specmatic.enterprise</groupId>
  <artifactId>executable</artifactId>
  <version>1.4.0</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>5.8.2</version>
  <scope>test</scope>
</dependency>

Gradle

build.gradle[.kts]

dependencies {
  testImplementation("io.specmatic.enterprise:executable:1.4.0")
  testImplementation("org.junit.jupiter:junit-jupiter:5.8.2")
}

Java

import io.specmatic.enterprise.SpecmaticContractTest;
public class ContractTest implements SpecmaticContractTest {
  // Leave the class body empty - no methods to implement.
  // You may add setup/teardown methods if needed by your application setup, but they are not required.
}

Kotlin

import io.specmatic.enterprise.SpecmaticContractTest
class ContractTest : SpecmaticContractTest {
  // Leave the class body empty - no methods to implement.
  // You may add setup/teardown methods if needed by your application setup, but they are not required.
}