Agent skill

test-locally

Build and deploy a full local OpenMetadata stack with Docker to test your connector in the UI. Handles code generation, build optimization, health checks, and guided testing.

View SKILL.md on GitHub Repository
Stars 10,170
Forks 1,815

Install this agent skill to your Project

npx add-skill https://github.com/open-metadata/OpenMetadata/tree/main/skills/test-locally

SKILL.md

Test Connector Locally

Build, deploy, and test a connector in a full local OpenMetadata stack with Docker.

When to Activate

When a user asks to "test locally", "start docker", "deploy locally", "test in the UI", "bring up the stack", or "run local docker".

Arguments

  • --skip-maven or --fast: Skip the Maven build (use when only ingestion Python code changed)
  • --rebuild: Tear down existing containers and rebuild
  • --teardown or --down: Just stop and remove containers
  • No arguments: Auto-detect what changed and choose the optimal build strategy

Process

Step 0: Handle Teardown

If the user asked to tear down / stop:

bash
cd docker/development && docker compose down -v

Report success and exit.

Step 1: Check Prerequisites

Verify the environment is ready:

bash
# Check Docker is running
docker info > /dev/null 2>&1 || echo "Docker is not running"

# Check docker compose is available
docker compose version > /dev/null 2>&1 || echo "docker compose not found"

# Check we're in the repo root
test -f docker/run_local_docker.sh || echo "Not in OpenMetadata repo root"

If any check fails, tell the user what to fix and stop.

Step 2: Activate Environment

bash
source env/bin/activate

Step 3: Run Code Generation

Always run code generation to ensure models are up to date:

bash
make generate

If make generate fails, check if the venv is set up:

bash
make install_dev generate

Step 4: Detect Build Strategy

Decide whether to skip the Maven build. Check what files changed:

bash
# Check for Java/schema/UI changes since last build
git diff --name-only HEAD~5 | grep -E "^(openmetadata-spec|openmetadata-service|openmetadata-ui)" | head -5

Skip Maven if:

  • User passed --skip-maven or --fast
  • Only files under ingestion/ changed (Python-only changes)
  • No changes to openmetadata-spec/, openmetadata-service/, or openmetadata-ui/

Full build if:

  • JSON Schema files changed (openmetadata-spec/)
  • Java service code changed (openmetadata-service/)
  • UI code changed (openmetadata-ui/)
  • First time running (no existing Docker images)
  • User explicitly asked for full build

Step 5: Check for Running Containers

bash
docker compose -f docker/development/docker-compose.yml ps --format json 2>/dev/null | head -5

If containers are already running:

  • Ask the user if they want to rebuild or just open the UI
  • If rebuild, tear down first: cd docker/development && docker compose down

Step 6: Build and Deploy

Full build:

bash
./docker/run_local_docker.sh -m ui -d mysql -s false -i true -r true

Fast rebuild (ingestion-only):

bash
./docker/run_local_docker.sh -m ui -d mysql -s true -i true -r false

Tell the user which strategy was chosen and why. The build takes:

  • Full build: ~5-8 minutes
  • Fast rebuild: ~2-3 minutes

Step 7: Wait for Health

The run_local_docker.sh script handles waiting internally. After it completes, verify the services are up:

bash
# Check OpenMetadata server is responding
curl -s -o /dev/null -w "%{http_code}" http://localhost:8585/api/v1/system/version

# Check Elasticsearch
curl -s -o /dev/null -w "%{http_code}" http://localhost:9200

Step 8: Guide the User

Once services are up, tell the user:

The local OpenMetadata stack is running.

Services:
  - OpenMetadata UI:  http://localhost:8585
  - Airflow:          http://localhost:8080 (admin / admin)
  - Elasticsearch:    http://localhost:9200
  - MySQL:            localhost:3306

To test your connector:
  1. Open http://localhost:8585
  2. Go to Settings -> Services -> {your service type}
  3. Click "Add New Service"
  4. Select your connector from the dropdown
  5. Fill in connection details and click "Test Connection"
  6. If test passes, run metadata ingestion

To tear down when done:
  /test-locally --teardown

Troubleshooting

If the user reports issues, check these:

Connector not in dropdown?

bash
# Check service schema registration
grep -l "YourConnector" openmetadata-spec/src/main/resources/json/schema/entity/services/*Service.json

# Need to rebuild without skip-maven
./docker/run_local_docker.sh -m ui -d mysql -s false -i true -r true

Test connection fails?

bash
# Check ingestion container logs
docker compose -f docker/development/docker-compose.yml logs ingestion --tail 50

# Check test_fn keys match test connection JSON
cat openmetadata-service/src/main/resources/json/data/testConnections/{service_type}/{name}.json

Container won't start?

bash
# Check Docker resources (need at least 6GB memory)
docker system info | grep "Total Memory"

# Check port conflicts
lsof -i :8585 -i :8080 -i :9200 -i :3306 | grep LISTEN

# Full reset
cd docker/development && docker compose down -v && docker system prune -f

Build fails?

bash
# Format first, then rebuild
make py_format
mvn spotless:apply
./docker/run_local_docker.sh -m ui -d mysql -s false -i true -r true

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

open-metadata/OpenMetadata

playwright-validation

Use when validating UI changes in a branch require Playwright E2E testing. Reviews branch changes, validates UI with Playwright MCP, and adds missing test cases.

10,170 1,815
Explore
open-metadata/OpenMetadata

writing-playwright-tests

Use when writing new Playwright E2E tests or adding test cases. Provides testing philosophy, patterns, and best practices from the Playwright Developer Handbook.

10,170 1,815
Explore
open-metadata/OpenMetadata

playwright-test

Generate robust, zero-flakiness Playwright E2E tests following OpenMetadata patterns. Creates comprehensive test files with proper waits, API validation, multi-role permissions, and complete entity lifecycle management.

10,170 1,815
Explore
open-metadata/OpenMetadata

connector-review

Review an OpenMetadata connector against golden standards. Runs multi-agent analysis covering architecture, code quality, type safety, testing, and performance. When a PR number is given, automatically posts the quality summary to the PR description and a detailed review as a PR comment.

10,170 1,815
Explore
open-metadata/OpenMetadata

openmetadata-workflow

Meta-skill loaded at session start. Directs Claude to check for applicable OpenMetadata skills before starting any task. Ensures structured workflows are followed.

10,170 1,815
Explore
open-metadata/OpenMetadata

tdd

Use when implementing new features or fixing bugs to enforce test-driven development. Guides the RED-GREEN-REFACTOR cycle for Java (JUnit), Python (pytest), and TypeScript (Jest/Playwright) in OpenMetadata.

10,170 1,815
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results