backend-test-conventions

Backend Test Conventions

File Location & Naming

• Place tests under tests/backend/unit/, tests/backend/integration/, tests/backend/contract/, or by domain: tests/backend/routes/, tests/backend/errors/, tests/backend/agents/, tests/backend/data/, tests/backend/security/, tests/backend/auth/, tests/backend/knowledge/.
• Name files test_<feature_or_module>.py with descriptive snake_case names.
• Shared test data goes in tests/backend/fixtures/.

File Structure

"""One-paragraph summary of what is being tested and why.

Background
----------
Brief context about the feature or bug fix these tests validate.
"""
from __future__ import annotations

import pytest

pytestmark = [pytest.mark.backend]

Conventions

• Always add pytestmark = [pytest.mark.backend] at module level.
• Group related tests in classes prefixed with Test (e.g. TestStripImageBlocks).
• Use pytest.mark.parametrize for data-driven tests instead of writing repetitive cases.
• Use pytest.fixture() for shared setup; keep fixtures close to where they are used.
• Unit tests must not depend on Flask, network, or external services.
• Mock external calls with unittest.mock.patch / MagicMock; never make real API calls.
• Each test function should verify one behavior and have a clear name: test_<what>_<condition>.

Running Tests

• When running pytest, use -q (quiet mode) instead of -v (verbose mode) for cleaner output.
• Preferred: python -m pytest tests/backend/ -q
• Avoid: python -m pytest tests/backend/ -v 2>&1

Error Handling Test Requirements

Application errors return HTTP 200 with status: "error" in the body. Only auth errors (AUTH_REQUIRED/AUTH_EXPIRED → 401, ACCESS_DENIED → 403) and uncontrolled transport failures (404/413/500) use non-200.

When adding a new route or modifying error handling, include tests for:

1. AppError scenarios — verify HTTP 200 + correct ErrorCode in body:

   def test_missing_table_returns_error():
       with app.test_client() as client:
           resp = client.get('/api/tables/nonexistent')
           assert resp.status_code == 200  # application error → always 200
           data = resp.get_json()
           assert data["status"] == "error"
           assert data["error"]["code"] == "TABLE_NOT_FOUND"