Is it a browser-based test?
├── YES: Mark with @pytest.mark.e2e
│   ├── Fast critical path? → Also add @pytest.mark.e2e_quick + @pytest.mark.smoke
│   └── Full workflow?      → Also add @pytest.mark.e2e_full
└── NO: Does it need real DB/Redis?
    ├── YES: Place in tests/integration/ (auto-marked @pytest.mark.integration)
    │   └── Critical for CI? → Also add @pytest.mark.smoke
    └── NO: Place in tests/unit/ (auto-marked @pytest.mark.unit)
        └── Critical for CI? → Also add @pytest.mark.smoke

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/
    ├── python/              # E2E tests (pytest + Playwright)
    │   ├── conftest.py      # Browser fixtures, auth, DB access
    │   └── tests/           # Test files
    └── smoke/               # Infrastructure smoke tests

@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()

@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

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

@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"

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

@pytest.mark.asyncio
@pytest.mark.e2e
@pytest.mark.e2e_quick
async def test_creates_signal_chain(page: Page, db_session, frontend_url: str):
    """Three-layer validation: UI action → DOM update → database state."""

    # LAYER 1: UI Action - Navigate and interact
    await page.goto(f"{frontend_url}/builder")
    await page.fill('[name="chain-name"]', 'My Chain')
    await page.click('button:has-text("Save")')

    # LAYER 2: DOM Update - Verify UI response
    await expect(page.locator('[data-testid="chain-card"]')).to_be_visible()

    # LAYER 3: Database State - Verify persistence
    result = await db_session.execute(
        text("SELECT id FROM signal_chains WHERE name = :name"),
        {"name": "My Chain"}
    )
    assert result.fetchone() is not None

@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"