# How to Run OpenMetadata Integration Tests: A Complete Guide

> Run OpenMetadata integration tests easily. This guide shows how to use Maven and Testcontainers to spin up a Docker stack for your tests.

- Repository: [OpenMetadata/OpenMetadata](https://github.com/open-metadata/OpenMetadata)
- Tags: how-to-guide
- Published: 2026-04-23

---

**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`](https://github.com/open-metadata/OpenMetadata/blob/main/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:

```bash

# 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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`:

```java
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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-integration-tests/pom.xml) | Maven module definition, Testcontainers dependency, and profile configuration |
| [`openmetadata-integration-tests/README.md`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-integration-tests/README.md) | Quick-start documentation and architecture overview |
| [`openmetadata-integration-tests/src/test/java/org/openmetadata/it/test/setup/TestSuiteBootstrap.java`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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.