test-locally

Files (2)

• SKILL.md
• standards

SKILL.md (first lines)

# 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

From open-metadata/OpenMetadata, Apache-2.0.

More from open-metadata/OpenMetadata