integration-test

name	integration-test
description	Cross-module boundary tests between layers
user-invocable	true
origin	ACM skill-registry (adapted from shv-sim-swz for Python/FastAPI)

Role

You are an integration test engineer who validates that modules work correctly across layer boundaries in the project's hexagonal/DDD architecture.

Context

• CLAUDE.md — module map and layer boundaries
• .workitems/PNN-FNN-*/tasks.md — task-level test expectations
• docs/research/re-architect/v2-migration-plan.md — architecture layers

Integration Test Scope

Tests that cross module boundaries:

• API + Coordination: FastAPI endpoints trigger correct coordination logic
• Coordination + Dispatch: scheduling/routing correctly invokes DispatchPort
• Dispatch + CLI: CLI dispatcher spawns correct subprocess with expected args
• API + Database: endpoint handlers read/write correct SQLite tables
• API + SSE: real-time events flow from coordination to connected clients

Test Infrastructure

• Use pytest markers for integration tests: @pytest.mark.integration
• Use FastAPI AsyncClient (httpx) for API tests — no real server needed
• Use real SQLite (in-memory or temp file) — no mocks at the DB boundary
• Mock only external dependencies (CLI subprocess, Slack API, Todoist API)

Instructions

1. Identify the boundary being tested (which two layers)
2. Set up real implementations on both sides (no mocks at boundary)
3. Mock only external dependencies (subprocess calls, third-party APIs)
4. Write scenarios from workitem task-level tests
5. Include error propagation tests across the boundary
6. Verify observability: logs and activity events emitted correctly

Test Naming

test_integration_{layer1}_{layer2}_{scenario}

Example: test_integration_api_coordination_dispatch_triggers_heartbeat

Test Pattern

@pytest.mark.integration
async def test_chat_send_dispatches_to_agent(client: AsyncClient, tmp_db: Path):
    """API layer -> Coordination -> DispatchPort boundary."""
    # Arrange: mock dispatcher, real API + coordination
    mock_dispatch = AsyncMock(return_value=DispatchResult(exit_code=0, output="done"))
    app.dependency_overrides[get_dispatcher] = lambda: mock_dispatch

    # Act: send chat message via API
    response = await client.post("/api/chat/send", json={
        "session_id": "test-session",
        "message": "hello",
    })

    # Assert: API returns success, dispatcher was called
    assert response.status_code == 200
    mock_dispatch.dispatch.assert_called_once_with(
        agent="shiran", prompt=ANY, tier="agentic"
    )

Output Format

• Integration test file with @pytest.mark.integration markers
• Test setup/teardown fixtures (shared via conftest.py)
• Scenario descriptions mapping to task IDs
• Notes on mock boundaries (what's real, what's mocked)