testing

krazyuniks 的头像作者 krazyuniks

使用pytest、 fixtures和mocking进行测试开发。用于编写测试、测试模式、覆盖率、参数化和调试测试失败。

📖 中文导读:使用pytest、 fixtures和mocking进行测试开发。用于编写测试、测试模式、覆盖率、参数化和调试测试失败。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: testing description: Test development with pytest, fixtures, and integration testing. Use for writing tests, test patterns, coverage, parametrization, and debugging test failures. context: fork

Testing Skill

Quick reference for writing tests. For full methodology and philosophy, see Testing Methodology in the wiki.

Philosophy: Test real services, mock only external network APIs. See .claude/rules/integration-testing.md.

Test Type Taxonomy

Test Type What It Tests Location
Unit Tests Single function/class in isolation tests/unit/backend/
Backend-Integration Tests Service orchestration, real DB/Redis tests/integration/backend/
UI-Playwright Tests Browser interactions, DOM elements tests/e2e/playwright/
Smoke Tests Critical path quick validation Marker-based (-m smoke)

Note: The term "E2E" is retired due to ambiguity. Use specific test type names above.

Running Tests

# All quality gates
just check

# Backend tests with coverage
docker compose exec backend pytest /tests/unit/backend/ /tests/integration/backend/ \
    --cov=app --cov-report=term-missing

# Specific test file
docker compose exec backend pytest /tests/integration/backend/api/test_signal_chains.py -v

# UI-Playwright tests (from host)
cd tests/e2e/playwright && pnpm test

Marker-Based Selection

pytest -m smoke          # Fast critical path (< 3 min)
pytest -m unit           # Unit tests only
pytest -m integration    # Backend-Integration tests
pytest -m "not slow"     # Exclude slow tests

Test Structure

tests/
├── conftest.py              # Root config: markers, pytest_plugins
├── fixtures/                # Shared fixtures
│   ├── database.py          # DB session with transaction rollback
│   ├── auth.py              # JWT tokens, auth headers
│   └── factories.py         # Test data factories
├── unit/backend/            # Pure logic, no external deps
├── integration/backend/     # Real DB/Redis tests
└── e2e/playwright/          # UI-Playwright tests (TypeScript)

Key Fixtures

Database Session (Transaction Rollback)

@pytest.fixture(scope="function")
async def db_session(db_engine) -> AsyncGenerator[AsyncSession, None]:
    """Real database with transaction rollback."""
    connection = await db_engine.connect()
    transaction = await connection.begin()

    async_session_factory = async_sessionmaker(
        bind=connection,
        class_=AsyncSession,
        expire_on_commit=False,
    )

    session = async_session_factory()

    try:
        yield session
    finally:
        await session.close()
        await transaction.rollback()
        await connection.close()

Factory Fixture Pattern

@pytest.fixture(scope="function")
def make_signal_chain(db_session: AsyncSession, test_user):
    """Factory for creating signal chains."""
    async def _make_signal_chain(name: str = "Test Chain", **kwargs):
        chain = SignalChain(
            id=uuid4(),
            user_id=test_user.id,
            name=name,
            **kwargs,
        )
        db_session.add(chain)
        await db_session.flush()
        await db_session.refresh(chain)
        return chain

    return _make_signal_chain

Authentication

@pytest.fixture(scope="function")
def auth_headers(auth_token: str) -> dict[str, str]:
    """Authorization headers for authenticated requests."""
    return {"Authorization": f"Bearer {auth_token}"}

Test Patterns

Backend-Integration Test (Preferred)

@pytest.mark.asyncio
async def test_create_signal_chain(client, auth_headers, test_user):
    """Test creating a signal chain via API."""
    response = await client.post(
        "/api/v1/signal-chains",
        json={"name": "Test Chain", "platform": "nam"},
        headers=auth_headers,
    )
    assert response.status_code == 201
    data = response.json()
    assert data["id"] is not None
    assert data["name"] == "Test Chain"

Unit Test (Pure Logic)

def test_signal_chain_validates_name():
    """Test domain validation without database."""
    with pytest.raises(ValueError, match="Name cannot be empty"):
        SignalChainCreate(name="", platform="nam")

UI-Playwright Test

test('creates signal chain', async ({ authenticatedPage }) => {
  // Navigate (required - NOT context.request)
  await authenticatedPage.goto('/builder');

  // DOM assertions (required)
  await authenticatedPage.fill('[name="chain-name"]', 'My Chain');
  await authenticatedPage.click('button:has-text("Save")');

  // Verify result
  await expect(authenticatedPage.getByTestId('chain-card')).toBeVisible();

  // Screenshot evidence (required for feature tests)
  await authenticatedPage.screenshot({ path: 'evidence/chain-created.png' });
});

Mocking External APIs Only

@pytest.mark.asyncio
async def test_t3k_sync_handles_error(db_session, test_user):
    """Mock EXTERNAL API only - never mock internal services."""
    with patch("app.services.t3k_client.fetch_tones") as mock:
        mock.side_effect = ExternalAPIError("T3K down")
        service = T3KSyncService(db_session)
        result = await service.sync_user_tones(test_user.id)
        assert result.status == "failed"

Pytest Markers

Marker Description Auto-Applied
smoke Critical path tests (< 3 min total) tests/e2e/smoke/
unit No external dependencies tests/unit/
integration Real DB/Redis required tests/integration/
slow Tests > 10 seconds Manual
t3k_integration Real Tone3000 API Manual

Coverage

Target: 80%+

docker compose exec backend pytest /tests/unit/backend/ /tests/integration/backend/ \
    --cov=app --cov-fail-under=80 --cov-report=html
  • Testing Methodology - Full methodology (GitHub Wiki)
  • .claude/rules/integration-testing.md - Testing rules