Test Plan and Coverage

Test Plan & Coverage

This document defines the testing strategy and coverage plan for the Local History Story Map project, focusing on the MVP milestone.

---

1. Testing Strategy

Our testing approach combines multiple layers to validate both technical correctness and user-facing behavior.

1.1 Unit Tests

Unit tests verify individual functions and components in isolation.

Backend (Python / FastAPI):

• Validation logic: email format, password strength rules, required fields
• Utility functions: coordinate parsing, date range validation, file size checks
• Authentication helpers: password hashing, JWT token generation and verification
• Model constraints: uniqueness rules, foreign key relationships

Frontend (React):

• Form validation components (registration, story creation)
• UI utility functions: date formatting, coordinate display
• Individual components rendered in isolation (using a component testing library)

Tool: pytest for backend, component test runner for frontend

---

1.2 Integration Tests

Integration tests verify that multiple components work correctly together, including the database and the service layer.

Scope:

• User registration flow: API → service → database write → response
• Login flow: credential lookup → token issuance → response
• Story creation flow: authenticated request → media reference stored → DB record created with correct user FK
• Story retrieval flow: DB query → correct geospatial data returned in response
• Permission enforcement: unauthorized requests correctly rejected at the API boundary

Tool: pytest with FastAPI TestClient and a test database instance

---

1.3 API Tests

API-level tests validate the full HTTP interface of the backend without a running browser.

Approach:

• Each endpoint is tested for success cases, expected error cases, and invalid input cases
• Authentication headers are exercised (missing token, expired token, valid token)
• HTTP status codes are asserted for every scenario
• Response body structure is validated against expected schemas

Endpoints to be covered (MVP):

Endpoint	Method	Tests
/auth/register	POST	Valid registration, duplicate email, missing fields, weak password
/auth/login	POST	Valid credentials, wrong password, unknown email
/stories	POST	Authenticated creation, unauthenticated attempt, missing required fields
/stories	GET	Returns list with correct geospatial data
/stories/{id}	GET	Returns correct story, 404 for missing ID
/stories/search	GET	Returns results matching query, empty result for no match
/health	GET	Returns 200 OK

Tool: pytest + httpx with FastAPI TestClient

---

1.4 Mock Data

Controlled test data is used to make tests reproducible and independent of production state.

Strategy:

• A dedicated test database is seeded before each test run
• Factory functions generate users, stories, and media file references with realistic but controlled values
• Geographic coordinates are fixed to known test locations (e.g., Boğaziçi University campus)
• Historical date ranges cover edge cases (single day, multi-year range, date at epoch boundary)
• Media files are simulated with small in-memory byte objects; no real cloud storage is called during tests

---

2. Test Coverage

2.1 Technical Coverage (What we test)

The following functional requirements are covered by automated tests in the MVP:

Requirement	Coverage
1.1.4.1 — User registration (username, email, password)	Unit + API tests
1.1.4.2 — Login with registered email and password	API + integration tests
1.2.4.1.1 — Email uniqueness enforced	Unit + API tests
2.2.2.1 — Password meets safety criteria	Unit tests
1.1.3.1 — Story creation (location, date, date range, text)	API + integration tests
1.1.3.2 — Post uploaded after required fields complete	API tests
1.2.7.2 — Required fields validated before submission	Unit + API tests
1.2.7.3 — Created post returned after submission	API tests
1.2.7.4 — Post stored as persistent DB record	Integration tests
1.2.7.5 — Post has unique primary key	Integration tests
1.2.7.6 — Post associated with authenticated user (FK)	Integration tests
1.2.2.1 — Story mapped to latitude/longitude	Unit + integration tests
1.2.5.1 — Only authenticated users can upload	API tests
1.2.5.2 — Unauthenticated users cannot upload	API tests
1.1.6.1 — Search stories by place name	API tests
2.2.4.1 — File size validated and rejected if over limit	Unit + API tests

---

2.2 User Acceptance Coverage (Validating the right thing)

This section defines the user acceptance criteria for the MVP — the conditions under which the platform is considered to deliver real value to users.

Acceptance Criterion 1: A new user can create an account and log in

Scenario: A person hears about the platform and wants to share a story.

• They visit the registration page and fill in username, email, and password
• They receive confirmation that their account was created
• They log in with their email and password and are taken to the main map view

Pass condition: Registration and login complete without error; user is authenticated and can see the map

---

Acceptance Criterion 2: An authenticated user can share a story pinned to a location

Scenario: A user wants to share a memory about a neighborhood park from 1987.

• They click "Create Story" from the main page
• They drag the map to the exact location of the park and pin it
• They select a historical date (year or date range)
• They write a text description
• They attach a photograph from their device
• They submit the story and see a success confirmation

Pass condition: Story is stored correctly with location, date, and media; success message is shown

---

Acceptance Criterion 3: Stories appear on the map for all visitors

Scenario: An unauthenticated visitor explores the platform to discover local history.

• They open the map without logging in
• They can see markers for published stories at their geographic locations
• They click a marker to see a preview of the story (title, date, thumbnail)
• They can open the full story detail page

Pass condition: Markers visible without authentication; story detail accessible; no login required to read

---

Acceptance Criterion 4: Users can find stories by searching for a place name

Scenario: A user wants to find stories about "Bebek."

• They type "Bebek" into the search bar
• Stories linked to that location appear in results
• They can click a result to navigate to that story on the map

Pass condition: Search returns relevant stories; empty query or unknown name returns no results without error

---

Acceptance Criterion 5: The platform correctly enforces access permissions

Scenario: An unauthenticated user tries to post a story.

• They attempt to submit a story without logging in
• The system rejects the request with a clear message asking them to log in

Pass condition: Unauthenticated POST to /stories returns 401; no story is created; user is prompted to authenticate

---

Acceptance Criterion 6: Story data is correctly stored and retrievable after submission

Scenario: A user posts a story and later returns to view it.

• They submit a story and receive a confirmation
• They navigate away and return to the story via the map or search
• The story displays with all original data intact (text, location, date, media)

Pass condition: All story fields are persisted correctly; retrieval returns identical data to what was submitted

---

3. What Scenarios Must the MVP Handle

The following use cases define the minimum set of scenarios the MVP must successfully support to be considered acceptable for release:

1. New user registration and login — the authentication flow works end-to-end
2. Story creation with location pin, date, and text — the core posting workflow functions correctly
3. Media file upload (image, video, audio) — files are accepted and stored
4. Map display with story markers — all published stories appear at their correct geographic coordinates
5. Story detail view — clicking a marker reveals the full story content
6. Place name search — users can find stories by typing a location name
7. Permission enforcement — unauthenticated users cannot create content; authenticated users can
8. File size rejection — files exceeding the size limit are rejected with a clear error
9. Duplicate email rejection — registration with an already-used email fails gracefully
10. Required field validation — story or registration submission with missing fields is blocked before submission

---

4. Out of Scope for MVP Testing

The following features are planned for later milestones and are not part of MVP test coverage:

• Likes, comments, and saves (Milestone 2)
• In-app audio/video recording (Milestone 2)
• Stories near me / geospatial proximity queries (Milestone 2)
• Reporting and admin moderation (Milestone 2)
• Auto-transcription of audio (Milestone 3)
• Advanced filtering by date, type, country/city (Milestone 3)
• User dashboard and view statistics (Milestone 3)
• Badge system (Milestone 3)
• Google authentication (Milestone 3)
• Mobile Android app (Milestone 2+)