cannamanage/docs/sprint-5/cannamanage-sprint5-testplan.md

CannaManage — Sprint 5 Test Plan

Date: 2026-06-12 Author: Patrick Plate / Lumen (Planner) Status: Draft v1 Basis: cannamanage-sprint5-plan.md v1

---

Test Overview

ID	Description	Type	Target	Status
T-01	Docker Compose full stack starts healthy	System	docker-compose.yml	⬜
T-02	CORS preflight allows localhost:3000	Integration	SecurityConfig	⬜
T-03	Backend health endpoint responds	Integration	/actuator/health	⬜
T-04	React Query provider mounts without error	Unit	providers.tsx	⬜
T-05	apiFetch uses rewrite proxy correctly	Unit	api-client-browser.ts	⬜
T-06	ApiError formats toast messages	Unit	use-api-error.ts	⬜
T-07	Dashboard loads real club stats	Integration	dashboard/page.tsx	⬜
T-08	Member list renders from API	Integration	members/page.tsx	⬜
T-09	Create member persists to database	Integration	POST /members	⬜
T-10	Edit member updates in database	Integration	PUT /members/{id}	⬜
T-11	Distribution form records to backend	Integration	POST /distributions	⬜
T-12	Quota exceeded returns 409 with details	Integration	ComplianceService	⬜
T-13	Under-21 member enforces 30g limit	Integration	ComplianceService	⬜
T-14	Batch creation adds stock	Integration	POST /stock/batches	⬜
T-15	Batch recall changes status	Integration	PUT /stock/batches/{id}/recall	⬜
T-16	PDF report downloads as binary	Integration	GET /reports/monthly?format=pdf	⬜
T-17	CSV report downloads correctly	Integration	GET /reports/member-list?format=csv	⬜
T-18	Portal login with session auth	Integration	POST /portal/login	⬜
T-19	Portal dashboard shows real quota	Integration	GET /portal/dashboard	⬜
T-20	Staff list loads for ADMIN	Integration	GET /staff	⬜
T-21	Staff invite sends email	Integration	POST /staff/invite	⬜
T-22	Permission update persists	Integration	PUT /staff/{id}/permissions	⬜
T-23	Staff revoke removes access	Integration	DELETE /staff/{id}	⬜
T-24	Non-ADMIN gets 403 on staff endpoints	Security	SecurityConfig	⬜
T-25	Seed data creates deterministic test state	System	R__test_seed.sql	⬜
T-26	Full E2E: login → distribute → verify quota	System	system-test.spec.ts	⬜
T-27	System test exit code 0 on success	System	docker-compose.test.yml	⬜
T-28	Error state renders when backend down	Unit	error-state.tsx	⬜
T-29	Loading skeleton appears during fetch	Unit	skeleton-card.tsx	⬜
T-30	Empty state shown when no data	Unit	dashboard/members pages	⬜

Status: ⬜ Open | ✅ Passed | ❌ Failed | ⏭️ Skipped

---

Test Cases (Detail)

T-01: Docker Compose full stack starts healthy

Type: System Target: docker-compose.yml

Preconditions:

• Docker Desktop running
• No port conflicts (5432, 8080, 3000)
• Images buildable (Maven + Node available)

Scenarios:

#	Input	Expected Result
a	docker compose up -d	All 3 containers reach "healthy" within 60s
b	docker compose ps	db=healthy, backend=healthy, frontend=running
c	curl http://localhost:3000	Returns HTML (login page)
d	curl http://localhost:8080/actuator/health	Returns {"status":"UP"}

Post-conditions:

• All containers stable for 30s without restart loops

---

T-02: CORS preflight allows localhost:3000

Type: Integration Target: SecurityConfig.java CORS bean

Preconditions:

• Backend running on port 8080

Scenarios:

#	Input	Expected Result
a	OPTIONS /api/v1/members with Origin: http://localhost:3000	200 + Access-Control-Allow-Origin: http://localhost:3000
b	OPTIONS /api/v1/members with Origin: http://evil.com	No Access-Control-Allow-Origin header (or 403)
c	GET /api/v1/members with Origin: http://localhost:3000 + valid JWT	200 + CORS headers present

---

T-03: Backend health endpoint responds

Type: Integration Target: Spring Boot Actuator

Scenarios:

#	Input	Expected Result
a	GET /actuator/health (no auth)	200 {"status":"UP"}
b	Backend with DB down	503 {"status":"DOWN"}

---

T-04: React Query provider mounts without error

Type: Unit Class: providers.tsx

Scenarios:

#	Input	Expected Result
a	Render providers with children	No console errors, children visible
b	Check React Query DevTools in dev mode	DevTools panel accessible (floating button)

---

T-05: apiFetch uses rewrite proxy correctly

Type: Unit Class: api-client-browser.ts

Scenarios:

#	Input	Expected Result
a	apiFetch("/members")	Fetches /api/backend/members
b	Backend returns 401	Throws ApiError with status 401
c	Backend returns 500	Throws ApiError with status 500, message from body
d	Backend returns non-JSON error	Throws ApiError with statusText as message
e	Network error (backend down)	Throws TypeError (fetch failure)

---

T-06: ApiError formats toast messages

Type: Unit Class: use-api-error.ts

Scenarios:

#	Input	Expected Result
a	ApiError(401, "Unauthorized")	Toast: "Sitzung abgelaufen" (destructive)
b	ApiError(403, "Forbidden")	Toast: "Zugriff verweigert" (destructive)
c	ApiError(409, "Quota exceeded: 5g remaining")	Toast: "Kontingent überschritten" with message
d	TypeError (network)	Toast: "Verbindungsfehler — Backend nicht erreichbar"
e	ApiError(500, "Internal error")	Toast: "Fehler" with generic message

---

T-07: Dashboard loads real club stats

Type: Integration Target: Dashboard page + GET /clubs/stats (or equivalent)

Preconditions:

• Backend running with seed data
• User logged in as ADMIN

Scenarios:

#	Input	Expected Result
a	Navigate to dashboard	KPI cards show numbers matching DB (5 members from seed)
b	Refresh page	Data reloads (React Query refetch)
c	Backend returns error	Error state shown with retry button
d	Slow response (>2s)	Skeleton cards visible during loading

---

T-08: Member list renders from API

Type: Integration Target: Members page + GET /members

Preconditions:

• Seed data loaded (5 members)

Scenarios:

#	Input	Expected Result
a	Navigate to /members	Table shows 5 seed members
b	Search "Müller"	Filtered to Max Müller only
c	Empty DB (no members)	Empty state: "Keine Mitglieder vorhanden"
d	Loading state	Skeleton table rows visible

---

T-09: Create member persists to database

Type: Integration Target: POST /api/v1/members

Preconditions:

• Logged in as ADMIN or STAFF with MANAGE_MEMBERS permission

Scenarios:

#	Input	Expected Result
a	Valid member data (name, email, DOB, phone)	201 Created, member appears in list
b	Duplicate email	409 Conflict with error message
c	Missing required field (firstName blank)	400 Bad Request with validation errors
d	Future date of birth	400 Bad Request (validation)
e	Under-18 date of birth	400 Bad Request (CanKG minimum age)

---

T-10: Edit member updates in database

Type: Integration Target: PUT /api/v1/members/{id}

Scenarios:

#	Input	Expected Result
a	Change phone number	200 OK, phone updated in DB
b	Change status to SUSPENDED	200 OK, member shows suspended badge
c	Invalid member ID	404 Not Found
d	Unauthorized role	403 Forbidden

---

T-11: Distribution form records to backend

Type: Integration Target: POST /api/v1/distributions

Preconditions:

• Available batch exists (≥ requested grams)
• Member is ACTIVE
• Quota not exceeded

Scenarios:

#	Input	Expected Result
a	10g Amnesia Haze to Max Müller	201 Created, distribution ID returned
b	Batch available_grams decreases by 10g	GET /stock/batches/{id} shows -10g
c	Member quota updates	Compliance endpoint shows 10g used today
d	Stock chart updates after mutation	React Query invalidates batch cache

---

T-12: Quota exceeded returns 409 with details

Type: Integration Target: ComplianceService quota enforcement

Preconditions:

• Member already at 24g today (daily limit = 25g)

Scenarios:

#	Input	Expected Result
a	Request 5g distribution	409: "Daily quota exceeded. Remaining: 1g"
b	Request 1g distribution	201 Created (exactly at limit)
c	Request 26g in single distribution	409: "Daily limit is 25g"

---

T-13: Under-21 member enforces 30g monthly limit

Type: Integration Target: ComplianceService age-based quota

Preconditions:

• Member Jonas Fischer (DOB: 2005-11-01, age 20 in 2026) in seed data

Scenarios:

#	Input	Expected Result
a	Check quota for Jonas	monthlyLimitGrams: 30, isUnder21: true
b	Distribute 29g across month	Success
c	Distribute 1g more (total 30g)	Success (at limit)
d	Distribute 1g more (total 31g)	409: "Monthly quota exceeded for under-21 member"

---

T-14: Batch creation adds stock

Type: Integration Target: POST /api/v1/stock/batches

Scenarios:

#	Input	Expected Result
a	New batch: 500g Blue Dream, THC 19%, supplier "BioHemp"	201 Created
b	Stock total increases by 500g	Dashboard total_stock reflects increase
c	Missing strain name	400 Bad Request
d	Negative grams	400 Bad Request

---

T-15: Batch recall changes status

Type: Integration Target: PUT /api/v1/stock/batches/{id}/recall

Scenarios:

#	Input	Expected Result
a	Recall batch b-001	Status changes to RECALLED
b	Recalled batch not available for distribution	Distribution form excludes recalled batches
c	Recall already-recalled batch	400 Bad Request (or idempotent 200)
d	Invalid batch ID	404 Not Found

---

T-16: PDF report downloads as binary

Type: Integration Target: GET /api/v1/reports/monthly?format=pdf

Scenarios:

#	Input	Expected Result
a	Request monthly report (current month)	200, Content-Type: application/pdf
b	Response body is valid PDF	First bytes = %PDF-
c	Browser triggers file download	Content-Disposition: attachment
d	No data for requested month	200 with empty report (or 204 No Content)

---

T-17: CSV report downloads correctly

Type: Integration Target: GET /api/v1/reports/member-list?format=csv

Scenarios:

#	Input	Expected Result
a	Request member list CSV	200, Content-Type: text/csv
b	CSV has header row	First line: column names
c	5 seed members in CSV body	6 lines total (header + 5 data)
d	German umlauts preserved	"Müller" renders correctly (UTF-8 or ISO-8859-1)

---

T-18: Portal login with session auth

Type: Integration Target: POST /portal/login

Scenarios:

#	Input	Expected Result
a	Valid member credentials (max@example.com / member123)	200 {"status":"ok"} + Set-Cookie session
b	Invalid password	401 {"error":"Invalid credentials"}
c	Non-member email (admin@...)	401 (not a member)
d	Subsequent /portal/* requests with session cookie	200 (authenticated)

---

T-19: Portal dashboard shows real quota

Type: Integration Target: GET /portal/dashboard

Preconditions:

• Member logged into portal session
• Some distributions recorded for this member

Scenarios:

#	Input	Expected Result
a	Fresh member (no distributions)	Quota: 0g used / 50g limit (≥21 years)
b	After 10g distribution recorded	Quota: 10g used / 50g limit
c	Radial chart shows correct percentage	20% filled (10/50)

---

T-20: Staff list loads for ADMIN

Type: Integration Target: GET /api/v1/staff

Scenarios:

#	Input	Expected Result
a	ADMIN requests staff list	200 with array of staff accounts
b	Includes permissions array per staff	Each item has permissions: [...]
c	STAFF without MANAGE_STAFF permission	403 Forbidden
d	MEMBER role	403 Forbidden

---

T-21: Staff invite sends email

Type: Integration Target: POST /api/v1/staff/invite

Scenarios:

#	Input	Expected Result
a	Valid email + permissions selection	201 Created, invite token generated
b	Email already registered as staff	409 Conflict
c	Invalid email format	400 Bad Request
d	No permissions selected	400 Bad Request (at least one required)

---

T-22: Permission update persists

Type: Integration Target: PUT /api/v1/staff/{id}/permissions

Scenarios:

#	Input	Expected Result
a	Set permissions to [MANAGE_MEMBERS, VIEW_REPORTS]	200, permissions saved
b	Staff can now access members but not stock	GET /members → 200, GET /stock → 403
c	Empty permissions array	200 (staff has no capabilities, effectively read-only)
d	Invalid permission name	400 Bad Request

---

T-23: Staff revoke removes access

Type: Integration Target: DELETE /api/v1/staff/{id}

Scenarios:

#	Input	Expected Result
a	Delete staff account	204 No Content
b	Revoked staff can no longer login	401 on next auth attempt
c	Staff disappears from list	GET /staff excludes deleted
d	Delete non-existent staff ID	404 Not Found

---

T-24: Non-ADMIN gets 403 on staff endpoints

Type: Security Target: SecurityConfig authorization rules

Scenarios:

#	Input	Expected Result
a	STAFF (no MANAGE_STAFF) → GET /staff	403
b	STAFF (no MANAGE_STAFF) → POST /staff/invite	403
c	MEMBER → GET /staff	403
d	Unauthenticated → GET /staff	401
e	ADMIN → GET /staff	200
f	STAFF with MANAGE_STAFF → GET /staff	200

---

T-25: Seed data creates deterministic test state

Type: System Target: R__test_seed.sql

Scenarios:

#	Input	Expected Result
a	Backend starts with profile=test-seed	Seed data inserted on startup
b	SELECT COUNT(*) FROM members WHERE club_id='club-001'	Returns 5
c	SELECT COUNT(*) FROM batches WHERE club_id='club-001'	Returns 3
d	Second startup with same profile	No duplicate insert errors (ON CONFLICT DO NOTHING)
e	Admin user can login with seed credentials	JWT returned successfully

---

T-26: Full E2E: login → distribute → verify quota

Type: System Class: e2e/system-test.spec.ts

Preconditions:

• Full Docker stack running with seed data

Scenarios:

#	Step	Expected Result
a	Login as admin@gruener-daumen.de	Dashboard loads with KPIs
b	Navigate to Members	5 seed members visible in table
c	Navigate to Distributions	Distribution list renders
d	Record 10g Amnesia Haze → Max Müller	Success toast, distribution in list
e	Navigate to Stock	Amnesia Haze batch shows -10g available
f	Navigate to Reports → download monthly PDF	File downloads (200 response)
g	Logout, login as member (max@example.com)	Portal dashboard loads
h	Portal quota shows 10g used	Radial chart at 20%

---

T-27: System test exit code 0 on success

Type: System Target: docker-compose.test.yml

Scenarios:

#	Input	Expected Result
a	All tests pass	Playwright container exits with code 0, compose exits 0
b	A test fails	Playwright exits non-zero, compose exits non-zero
c	Backend fails to start	Tests timeout, compose exits non-zero

---

T-28: Error state renders when backend down

Type: Unit Target: error-state.tsx

Scenarios:

#	Input	Expected Result
a	API fetch throws network error	Error component visible with message
b	Click "Retry" button	Query refetches
c	Multiple errors on same page	Each section shows own error independently

---

T-29: Loading skeleton appears during fetch

Type: Unit Target: skeleton-card.tsx, skeleton-table.tsx

Scenarios:

#	Input	Expected Result
a	Query in isLoading state	Skeleton shimmer visible
b	Query resolves	Skeleton replaced with real content
c	Query in isFetching (background refetch)	No skeleton (data still shown)

---

T-30: Empty state shown when no data

Type: Unit Target: Dashboard, Members, Distributions pages

Scenarios:

#	Input	Expected Result
a	Members list empty (API returns [])	"Keine Mitglieder vorhanden" + Add button
b	Distributions list empty	"Keine Ausgaben erfasst" message
c	Stock empty (no batches)	"Kein Bestand vorhanden" + Add batch button
d	Dashboard with 0 members	KPI cards show 0, no chart data placeholder

---

Test Data Requirements

Entity	Count	Source	Notes
Club	1	R__test_seed.sql	"Grüner Daumen e.V.", Berlin
Admin user	1	Seed	admin@gruener-daumen.de / admin123
Staff user	1	Seed	staff@gruener-daumen.de / staff123
Members	5	Seed	Including 1 under-21 (Jonas Fischer)
Strains	3	Seed	Amnesia Haze, White Widow, Northern Lights
Batches	3	Seed	520g, 430g, 380g available
Distributions	0	Fresh	Tests create distributions during execution

---

Test Coverage Matrix

Component	Unit	Integration	System	Total
Docker/Infra	0	1	2	3
CORS/Security	0	2	0	2
API Client	3	0	0	3
Dashboard	0	1	1	2
Members	0	2	1	3
Distributions	0	3	1	4
Stock	0	2	1	3
Reports	0	2	1	3
Portal	0	2	1	3
Staff	0	5	0	5
UI States	3	0	0	3
Total	6	20	4	30

---

Execution Strategy

Fast feedback loop (during development):

# Frontend unit tests (Vitest — if configured)
cd cannamanage-frontend && pnpm test

# Backend integration tests (existing Testcontainers suite)
cd cannamanage-api && mvn test

# Existing Playwright E2E (mock backend, ~30s)
cd cannamanage-frontend && pnpm exec playwright test

Full system test (before merge):

docker compose -f docker-compose.yml -f docker-compose.test.yml up \
  --build --abort-on-container-exit --exit-code-from playwright

Manual smoke test checklist:

1. docker compose up → all healthy
2. Open http://localhost:3000 → login page
3. Login as admin → dashboard with real data
4. Add member → appears in list
5. Record distribution → quota updates
6. Download PDF report → valid file
7. Login as member (portal) → see personal quota

---

References

• Implementation Plan: docs/sprint-5/cannamanage-sprint5-plan.md (v1)
• Backend Controllers: cannamanage-api/src/main/java/de/cannamanage/api/controller/
• Frontend Types: cannamanage-frontend/src/types/api.ts
• Security Config: cannamanage-api/src/main/java/de/cannamanage/api/security/SecurityConfig.java
• Existing E2E: cannamanage-frontend/e2e/