How to Run OpenMetadata Integration Tests: A Complete Guide

Run OpenMetadata integration tests using Maven with Testcontainers to automatically spin up a full Docker stack including the database, search engine, and OpenMetadata server.

OpenMetadata's integration test suite validates end-to-end platform behavior against a real running server. These tests live in the openmetadata-integration-tests Maven module and exercise the Java SDK, REST API, authentication, versioning, tags, soft-delete, and pagination. Understanding how to run OpenMetadata integration tests is essential for contributors validating changes and teams extending the platform.

Prerequisites for Running Integration Tests

Before executing any test commands, ensure your environment meets these requirements:

• Docker must be running and accessible to your current user
• Maven 3.8+ installed for build orchestration
• Java 17 or later (required by OpenMetadata 1.0+)
• Sufficient memory available for Docker containers (recommended 8GB+)

The integration test framework uses Testcontainers to automatically download and start container images for MySQL/PostgreSQL, Elasticsearch/OpenSearch, and the OpenMetadata server itself.

Available Maven Profiles for Integration Tests

The openmetadata-integration-tests/pom.xml defines four profiles that pair databases with search engines:

Profile	Database	Search Engine	Use Case
mysql-elasticsearch (default)	MySQL 8.x	Elasticsearch 8.x	Production-like stack
postgres-opensearch	PostgreSQL 15+	OpenSearch 2.x	AWS-compatible stack
postgres-elasticsearch	PostgreSQL 15+	Elasticsearch 8.x	Hybrid configuration
mysql-opensearch	MySQL 8.x	OpenSearch 2.x	Legacy migration testing

These profiles control which Docker images Testcontainers pulls and starts. All containers share a single JVM lifecycle through TestSuiteBootstrap, minimizing startup overhead.

Running OpenMetadata Integration Tests

Default Profile: MySQL + Elasticsearch

Execute the full integration test suite with the default configuration:

# From repository root

mvn test -pl :openmetadata-integration-tests

This command:

• Compiles the openmetadata-integration-tests module
• Triggers TestSuiteBootstrap to start Docker containers via JUnit's LauncherSessionListener
• Runs all test classes extending BaseEntityIT
• Stops and removes containers after test completion

Alternative Profile: PostgreSQL + OpenSearch

Run tests against a PostgreSQL and OpenSearch stack:

mvn test -pl :openmetadata-integration-tests -Ppostgres-opensearch

Add -DskipUnitTests if you want to skip unit tests in other modules and focus solely on integration coverage.

Single Test Class Execution

During development, run a specific entity test to reduce feedback time:

mvn test -pl :openmetadata-integration-tests -Dtest=TableResourceIT

Replace TableResourceIT with any concrete implementation like TopicResourceIT, DashboardResourceIT, or PipelineResourceIT.

Debug Mode with Container Logs

Preserve containers for debugging when tests fail:

mvn test -pl :openmetadata-integration-tests -Dtestcontainers.reuse.enable=true

Then inspect running containers with docker ps and logs with docker logs <container_id>.

Understanding the Test Architecture

Testcontainers Bootstrap via TestSuiteBootstrap

In openmetadata-integration-tests/src/test/java/org/openmetadata/it/test/setup/TestSuiteBootstrap.java, a JUnit 5 LauncherSessionListener handles container lifecycle:

• Before all tests: Starts MySQL/PostgreSQL, Elasticsearch/OpenSearch, Fuseki (RDF), and the OpenMetadata server
• Container reuse: Shares containers across all tests in the JVM run
• After all tests: Graceful shutdown and cleanup

This approach pays the Docker startup cost once per Maven execution rather than per test class.

BaseEntityIT: The Foundation for Entity Tests

The abstract class BaseEntityIT in openmetadata-integration-tests/src/test/java/org/openmetadata/it/tests/BaseEntityIT.java provides comprehensive test coverage:

Feature Flag	Validates
supportsPatch	JSON Patch operations for entity updates
supportsSoftDelete	Soft delete with deleted flag
supportsIncludeDeleted	include=deleted query parameter
supportsVersioning	Entity version history and ChangeDescription
supportsTags	Classification and tag assignment

Concrete implementations override abstract methods to provide entity-specific SDK calls. For example, TableResourceIT implements createEntity() by calling SdkClients.adminClient().tables().create(req).

SDK Client Validation

All API interactions flow through OpenMetadataClient in openmetadata-sdk/src/main/java/org/openmetadata/sdk/client/OpenMetadataClient.java. This ensures:

• Client-server compatibility: Tests validate the actual SDK that users consume
• Authentication flows: JWT and basic auth configurations tested end-to-end
• Error handling: Server error responses propagated through SDK exceptions

Adding New Integration Tests

To create integration tests for a new entity, extend BaseEntityIT:

package org.openmetadata.it.tests;

import org.openmetadata.it.framework.TestNamespace;
import org.openmetadata.it.framework.SdkClients;
import org.openmetadata.sdk.client.OpenMetadataClient;

public class MyEntityIT extends BaseEntityIT<MyEntity, CreateMyEntity> {

    @Override
    protected CreateMyEntity createMinimalRequest(TestNamespace ns) {
        return new CreateMyEntity()
                .withName(ns.prefix("myEntity"))
                .withDescription("Test entity for integration validation");
    }

    @Override
    protected MyEntity createEntity(CreateMyEntity req) {
        return SdkClients.adminClient().myEntities().create(req);
    }

    @Override
    protected MyEntity getEntity(String id) {
        return SdkClients.adminClient().myEntities().getById(id);
    }

    @Override
    protected MyEntity getEntityByName(String fqn) {
        return SdkClients.adminClient().myEntities().getByName(fqn);
    }

    @Override
    protected MyEntity patchEntity(String id, MyEntity entity) {
        return SdkClients.adminClient().myEntities().update(id, entity);
    }

    @Override
    protected void deleteEntity(String id) {
        SdkClients.adminClient().myEntities().delete(id);
    }

    @Override
    protected String getEntityType() {
        return "myEntity";
    }

    @Override
    protected void validateCreatedEntity(MyEntity entity, CreateMyEntity req) {
        assertEquals(req.getName(), entity.getName());
        assertNotNull(entity.getId());
    }

    @Override
    protected ListResponse<MyEntity> listEntities(ListParams params) {
        return SdkClients.adminClient().myEntities().list(params);
    }
}

By implementing these methods, your test automatically inherits 20+ test cases covering CRUD, versioning, soft-delete, pagination, and security.

Key Configuration Files

File	Purpose
openmetadata-integration-tests/pom.xml	Maven module definition, Testcontainers dependency, and profile configuration
openmetadata-integration-tests/README.md	Quick-start documentation and architecture overview
openmetadata-integration-tests/src/test/java/org/openmetadata/it/test/setup/TestSuiteBootstrap.java	JUnit launcher listener for container lifecycle
openmetadata-integration-tests/src/test/java/org/openmetadata/it/tests/BaseEntityIT.java	Abstract base class for all entity integration tests
openmetadata-sdk/src/main/java/org/openmetadata/sdk/client/OpenMetadataClient.java	SDK client used by all integration tests

Summary

Running OpenMetadata integration tests requires Maven, Docker, and the openmetadata-integration-tests module. Key takeaways:

• Testcontainers bootstrap automatically starts the full OpenMetadata stack once per Maven execution via TestSuiteBootstrap
• Four Maven profiles let you test against MySQL/PostgreSQL paired with Elasticsearch/OpenSearch
• BaseEntityIT provides comprehensive test coverage—extend it with ~10 methods to test new entities
• SDK client validation ensures the Java client library works correctly against the server
• Command examples: mvn test -pl :openmetadata-integration-tests for defaults, -Ppostgres-opensearch for alternative stacks, -Dtest=TableResourceIT for single test classes

Frequently Asked Questions

What Docker resources are required to run OpenMetadata integration tests?

The integration test suite starts four container types: the database (MySQL or PostgreSQL), the search engine (Elasticsearch or OpenSearch), Fuseki for RDF processing, and the OpenMetadata application server itself. You need approximately 6-8GB of available memory and Docker daemon access for the user running Maven.

How do I debug an integration test that fails with container startup errors?

Add -Dtestcontainers.reuse.enable=true to your Maven command to prevent container cleanup after tests. Then use docker ps to inspect running containers and docker logs <container_id> to examine startup logs. Check TestSuiteBootstrap.java for container configuration details if images fail to pull or start.

Can I run integration tests without building the entire OpenMetadata project?

No—the integration tests require the server artifact to be built first. Run mvn clean install -DskipTests from the repository root before executing integration tests. The openmetadata-service module produces the JAR that Testcontainers launches as the application server container.

Why do my entity tests need to extend BaseEntityIT instead of using direct API calls?

BaseEntityIT in openmetadata-integration-tests/src/test/java/org/openmetadata/it/tests/BaseEntityIT.java provides 20+ standardized test cases covering CRUD, versioning, soft-delete, pagination, and security that every entity must satisfy. Extending it with approximately 10 method implementations ensures your entity behaves consistently with the rest of the platform while minimizing test code duplication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}