• 1. Overview
• 2. Testing Strategy
• 3. Testing Frameworks & Tools
• 4. Test Architecture
• 5. Backend Test Plan
• 6. Frontend Test Plan
• 7. CI/CD Integration
• 8. Core Use Case Scenarios
• 9. User Acceptance Criteria
• 10. Traceability Matrix

This document defines the testing strategy, test plan, and acceptance criteria for the Local History Story Map project. The project follows a monorepo structure with a Django REST Framework backend, a React (Vite) frontend, and a React Native mobile app.

Testing Philosophy:

• Every feature must include unit tests (enforced via PR checklist)
• Tests must pass locally before opening a pull request
• CI pipeline gates merges on test results

We follow the standard test pyramid approach, prioritizing a large base of fast unit tests, supported by integration and API tests, with end-to-end tests covering critical user flows.

1. Isolation: Each test is independent. State is reset between tests using setup_method (backend) and beforeEach (frontend).
2. Real Database: Backend tests run against a real MySQL 8.0 instance (via pytest-django), not mocks. This catches migration and constraint issues early.
3. Fast Test Execution: Test settings use MD5PasswordHasher instead of production-grade hashers to keep the suite fast, and locmem.EmailBackend for in-memory email.
4. DOM Simulation: Frontend tests run in a jsdom environment, simulating browser behavior without a real browser.
5. User-Centric Frontend Tests: Frontend tests interact with components the way a real user would — via labels, roles, and visible text — following Testing Library best practices.
6. Mock External Dependencies: API service calls in the frontend are mocked at the module level so component tests remain isolated from the backend.

Configuration (backend/pytest.ini):

[pytest]
addopts = --ds=config.settings.test
python_files = tests/test_*.py
python_classes = Test*
python_functions = test_*

Test settings (backend/config/settings/test.py):

• DEBUG = False — mirrors production behavior
• Strips debug_toolbar from apps and middleware
• Uses in-memory email backend
• Uses fast password hasher for speed

Configuration (in frontend/vite.config.js):

test: {
  globals: true,
  environment: "jsdom",
  setupFiles: "./src/test/setup.js",
  css: true,
}

Each Django app follows a consistent test structure:

backend/
├── conftest.py                    # Shared fixtures (user, story, etc.)
├── <app>/
│   └── tests/
│       ├── test_models.py         # Model layer tests
│       ├── test_serializers.py    # Serializer validation tests
│       ├── test_services.py       # Business logic / service layer tests
│       ├── test_views.py          # API endpoint / view tests
│       └── test_permissions.py    # Permission class tests
└── common/
    └── tests/
        ├── test_exceptions.py     # Custom exception handler tests
        ├── test_validators.py     # Shared validator tests
        └── test_permissions.py    # Shared permission class tests

Apps with test coverage: users, stories, interactions, gamification, media, notifications, reports, tags, common

Frontend tests are co-located with the code they test using a __tests__/ directory convention:

frontend/src/
├── test/
│   └── setup.js                   # Global test setup (jest-dom matchers)
├── pages/
│   └── __tests__/
│       └── <PageName>.test.jsx    # Page-level tests
├── components/
│   └── __tests__/
│       └── <Component>.test.jsx   # Component-level tests
└── services/
    └── __tests__/
        └── <service>.test.js      # Service-level tests

Backend: A global conftest.py provides reusable pytest fixtures for common entities (users, stories). Each app may define local helper functions for creating test data specific to its domain.

Frontend: Each test file defines render helpers that wrap components with required providers (e.g., BrowserRouter) and form-fill helpers to reduce boilerplate. API services and router hooks are mocked using vi.mock().

Every Django app must have model tests covering:

Serializer tests validate the contract between API input/output and internal models:

• Required vs. optional field enforcement
• Input validation rules (email format, password strength, uniqueness)
• Write-only fields are excluded from responses
• Nested serializer behavior

Service tests verify business logic orchestration:

• Correct model creation and mutation
• Password hashing and token generation
• Error handling for invalid inputs and edge cases
• Anti-enumeration patterns (e.g., login does not reveal whether an email exists)

View tests validate the HTTP contract of each endpoint:

• Every custom permission class is tested with all role combinations (guest, authenticated, owner, admin)
• Custom exception handlers are tested to ensure consistent error response format
• Shared validators (e.g., password strength) are tested with valid, invalid, and edge-case inputs

Each page component is tested for:

Shared UI components are tested for:

• Correct rendering based on props
• User interaction behavior (click, toggle, hover)
• Accessibility attributes (ARIA labels, roles)

• Mocking Strategy: API service calls are mocked at the module level (vi.mock); router hooks are mocked to test navigation without real routing
• User Event Simulation: All interactions use @testing-library/user-event for realistic event sequences (type, click, clear)
• Accessibility-First Queries: Tests query elements by role, labelText, and text rather than CSS selectors or test IDs

The CI pipeline runs automatically on pushes to main and pull requests targeting main. It consists of two parallel jobs:

┌─────────────────────────────────┐  ┌─────────────────────────────────┐
│  backend-tests                  │  │  frontend-checks                │
│  ─────────────                  │  │  ────────────────                │
│  • Ubuntu latest, Python 3.12   │  │  • Ubuntu latest, Node.js 20    │
│  • MySQL 8.0 service container  │  │  • npm ci                       │
│  • pip install requirements     │  │  • npm run lint                  │
│  • pytest -v                    │  │  • npm run test:run              │
│                                 │  │  • npm run build                 │
└─────────────────────────────────┘  └─────────────────────────────────┘

• All backend tests must pass before a PR can be merged
• All frontend lint checks, tests, and builds must pass before a PR can be merged
• New features must include corresponding tests — PRs without tests will be flagged during review

This section defines the end-to-end user journeys the application must successfully handle. Each scenario represents a critical user flow that must be validated through a combination of unit, integration, and (where applicable) E2E tests.

Actor: Unregistered visitor Goal: Discover local history stories by exploring a map

Actor: New user Goal: Create an account, log in, and submit a local history story

Actor: Registered, logged-in user Goal: Engage with stories through likes and comments

Actor: Registered user Goal: View profile with username, contribution count, and submitted stories

Actor: Logged-in user Goal: Securely end session

Actor: Any user (guest or registered) Goal: Find specific stories by title, location, or time period

Every pull request must satisfy these criteria (enforced via PR template):

• Project builds successfully
• Code follows the style guidelines of this project
• Hard-to-understand parts are commented
• Self-review has been performed
• Tests have been added or updated for the change
• New and existing unit tests pass locally