testing
使用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
Related
- Testing Methodology - Full methodology (GitHub Wiki)
.claude/rules/integration-testing.md- Testing rules