tdd

name	tdd
description	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.
user-invocable	true
argument-hint	<feature or bug description>

Test-Driven Development for OpenMetadata

Enforce RED-GREEN-REFACTOR discipline across all three language stacks.

When to Use

• Implementing any new feature or behavior
• Fixing bugs (write a test that reproduces the bug first)
• Adding new API endpoints, connectors, or UI components

The Cycle

1. RED - Write a Failing Test

Write the smallest test that describes the desired behavior. Run it. It must fail. If it passes, your test isn't testing the new behavior.

Java (JUnit 5):

# Write test in openmetadata-service/src/test/ or openmetadata-integration-tests/
mvn test -pl openmetadata-service -Dtest=YourTestClass#yourTestMethod

Python (pytest):

source env/bin/activate
cd ingestion
# Write test using pytest style — plain assert, no unittest.TestCase
python -m pytest tests/unit/your_test.py::test_your_function -v

TypeScript (Jest):

cd openmetadata-ui/src/main/resources/ui
yarn test path/to/YourComponent.test.ts

Rules for RED:

• Test one behavior per test
• Use descriptive test names that explain what should happen
• Assert on observable outcomes (API responses, database state, rendered output), not internal method calls
• For Python: use assert x == y, not self.assertEqual(x, y)

2. GREEN - Write the Minimum Code to Pass

Write only the code needed to make the test pass. No more.

• Don't add error handling for cases you haven't tested
• Don't generalize — hardcode if that's what the test requires
• Don't clean up or refactor yet

Run the test again. It must pass.

3. REFACTOR - Clean Up While Green

Now improve the code while keeping tests green:

• Remove duplication
• Improve naming
• Extract methods if needed (but don't over-abstract)
• Run the full test suite for the module to check for regressions

# Java — format then test
mvn spotless:apply
mvn test -pl openmetadata-service

# Python — format, lint, then test
cd ingestion && make py_format && make py_format_check
python -m pytest tests/unit/your_test.py -v

# TypeScript — lint then test
cd openmetadata-ui/src/main/resources/ui
yarn lint:fix
yarn test path/to/YourComponent.test.ts

4. Repeat

Go back to RED with the next behavior. Each cycle should take minutes, not hours.

What to Test Where

Layer	Test Type	Location	Runner
Java REST API	Integration	openmetadata-integration-tests/	mvn verify
Java service logic	Unit	openmetadata-service/src/test/	mvn test
Python connectors	Unit	ingestion/tests/unit/	pytest
Python integration	Integration	ingestion/tests/integration/	pytest
React components	Unit	Co-located .test.ts files	yarn test
UI E2E flows	E2E	playwright/e2e/	yarn playwright:run

Anti-Patterns to Avoid

• Writing code before the test. If you catch yourself doing this, stop. Write the test first.
• Mocking everything. Mock external boundaries (HTTP clients, third-party APIs), not your own classes. If you need 3+ mocks, write an integration test instead.
• Testing implementation details. Don't assert on internal method calls with verify(). Assert on outcomes.
• Giant test methods. Each test should verify one behavior. Split multi-assertion tests into separate test cases.
• Skipping REFACTOR. The refactor step is where code quality happens. Don't skip it.

OpenMetadata-Specific Patterns

Java integration tests use BaseEntityIT with TestNamespace for isolation and OpenMetadataClient for API calls. Prefer this over heavily mocked unit tests for API testing.

Python connector tests should test real behavior:

# Good: test the actual parsing logic
def test_parse_table_metadata():
    raw = {"name": "users", "columns": [...]}
    result = parse_table(raw)
    assert result.name == "users"
    assert len(result.columns) == 3

# Bad: mock everything and verify calls
def test_parse_table_metadata():
    mock_client = MagicMock()
    mock_client.get.return_value = {...}
    # ... 20 lines of mock setup
    verify(mock_client.get).called_once()  # proves nothing

Frontend tests should render components and assert on visible output:

// Good: test what the user sees
render(<MyComponent data={testData} />);
expect(screen.getByText('Expected Label')).toBeInTheDocument();

// Bad: test implementation details
expect(component.state.internalFlag).toBe(true);