Integration (HTTP e2e) Coverage Tickets — Bridge API

Drafted coverage tickets for the missing HTTP e2e flows. Not yet in the sprint — pending review/approval before being added.

These run in the existing real-stack harness: the real Express app driven over HTTP (supertest) against real MySQL 8 + real Redis 7 (Testcontainers, nothing internal mocked). Only external network boundaries are mocked (Didit, email/validation providers, S3/Bunny). No worker process runs in tests, so anything asynchronous (emails, certificate PDFs, bulk/onboarding jobs) is asserted at the enqueue / PENDING boundary.

Current coverage: only the V-Learning member slice (assignments, planner, lesson progress/gating, certificate read/download) plus health/auth-gate/404. Every other route group below has zero e2e.

Acceptance Criteria convention (all e2e tickets): coverage % is not the yardstick for journey tests. Each ticket's AC is: the listed flows/cases pass end-to-end through HTTP against the real-stack harness; only external boundaries mocked; new tests live in tests/integration/ and self-skip without Docker; all tests pass.

---

E2E Ticket 1 — Auth lifecycle & sessions

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-auth

Test Root: tests/integration/

Description

Real-stack HTTP coverage for the entire /api/v1/auth/* surface and session management, including the register → verify → login → refresh → logout journey, recovery, and OTP. Email/validation providers mocked at the boundary; activation jobs assert at the "enqueued" boundary (no worker runs).

Files / Scope

tests/integration/http/authHttp.integration.test.ts

Test Cases

• register: 201 creates Pending + kyc_verified=false, activation email enqueued; duplicate email → 400; registration-disabled and referral-only gates; validation failures → 400; DISABLE_EMAIL_VERIFICATION=true → auto-Active.
• verify-email: valid token → Active + redirect with verified=true; invalid/expired token → error redirect.
• login: Pending blocked (200, status pending, no token); Active success (access + refresh token); wrong password → 401; Suspended/Terminated → 401.
• refresh: valid → rotated tokens; reused/invalid/expired → 401.
• logout / logout-all: session revoked → subsequent authed call 401; logout-all revokes every session.
• sessions: list, revoke specific.
• recovery: forget-password (no enumeration leak) → reset-password (valid/expired token) → login with new password; resend-email-verification (rate-limited, no leak).
• OTP: send-login-otp (only for Active) → login-with-otp (valid/invalid/expired/attempt-limit).
• update-password: requires auth; wrong current password → 401; success.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness (Testcontainers MySQL + Redis); only external boundaries (email/validation providers) mocked. Tests self-skip without Docker. All tests pass.

---

E2E Ticket 2 — KYC flow & gating

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-kyc

Test Root: tests/integration/

Description

Real-stack coverage for /api/v1/kyc/* and the KYC access gate in verifyToken. Didit provider mocked; the webhook is exercised with a genuine HMAC x-signature over the raw body using a known DIDIT_WEBHOOK_SECRET.

Files / Scope

tests/integration/http/kycHttp.integration.test.ts

Test Cases

• status: KYC-not-required setting → kycVerified:true; required + already verified short-circuit; required + unverified returns latest verification status (incl. max_declined).
• verify (get URL): already-verified short-circuit; existing not_started/in_progress returns same URL; declined-at-max-retries → blocked; creates a new session (Didit mocked).
• webhook: missing/invalid signature → 401; stale timestamp → 401; valid signed approved flips kyc_verified=true; declined sets rejection reason; unknown session handled.
• internal/kyc-status-update: invalid/missing x-service-key → 401; valid approved flips kyc_verified.
• cancel: owner/admin allowed, others denied.
• Gating journey: KYC-required + unverified user → gated route returns 401 "KYC verification required"; ignore-path (/kyc/status, /auth/refresh, admin) bypasses; after approval webhook the gated route passes.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness; Didit mocked, webhook signature real. Self-skips without Docker. All tests pass.

---

E2E Ticket 3 — Admin user management & moderation

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-admin-users

Test Root: tests/integration/

Description

Real-stack coverage for admin auth, the requireAdmin/requireRole gates, and the /api/v1/admin/users/* management surface — including the moderation journey and the BR-243 manual inconsistency path.

Files / Scope

tests/integration/http/adminUsersHttp.integration.test.ts

Test Cases

• admin login / gate: non-admin role denied; User token on admin route → 403; admin success.
• list users: pagination, filters (status, kycVerified, country, search), soft-deleted exclusion, sort.
• get / update: PUT /users/:id updates fields; setting kycVerified and status independently (documents the BR-243 manual Pending + kyc_verified=true path).
• status change: suspend → target user login blocked + sessions revoked; reactivate → Active; invalid status → 400; cannot modify own account.
• delete: soft delete (Admin_Removed), cannot delete self, child referrals reassigned.
• revert-failed: single + bulk (Failed → Pending, kyc_verified reset to false).
• bulk ops: bulk-status, bulk-delete, bulk-email (enqueue boundary) + bulk job status.
• level-up review; admin password reset revokes the user's sessions.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness; bulk/email jobs asserted at the enqueue boundary. Self-skips without Docker. All tests pass.

---

E2E Ticket 4 — Member V-Learning: exam → certificate (+ remaining member surface)

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-member-exam

Test Root: tests/integration/

Description

Extends the existing V-Learning member e2e to the untested member surface: the full exam-to-certificate journey, planner edits, module browsing, and notes. Certificate generation asserts at the PENDING/enqueue boundary (no cert worker runs in tests).

Files / Scope

tests/integration/http/memberExamHttp.integration.test.ts (and extend vlearningHttp.integration.test.ts)

Test Cases

• exam info / start: GET /modules/:id/exam; POST .../exam/start creates an attempt; cannot start when ineligible (lessons incomplete / max attempts / cooldown); active-attempt returns the in-flight attempt.
• answer / submit: POST /exam-attempts/:id/answer saves; submit scores → pass enqueues a PENDING certificate, fail does not; results reflect the score.
• anti-cheat: violation records and (at threshold) auto-finalizes; abandon → abandoned; timed-out attempt → timed_out.
• authorization: a user cannot read/submit another user's attempt.
• planner edits: PATCH /planner/:id, DELETE /planner/:id.
• browse: GET /modules, /modules/:id, /current-lesson, lesson notes get/save, resource download, active categories.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness; cert/email async asserted at the enqueue boundary. Self-skips without Docker. All tests pass.

---

E2E Ticket 5 — Member account: profile, referrals, account lifecycle

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-members-account

Test Root: tests/integration/

Description

Real-stack coverage for /api/v1/users/* — profile, the referral cycle/stats, public lookups, and account cancellation — including the referral registration journey.

Files / Scope

tests/integration/http/membersAccountHttp.integration.test.ts

Test Cases

• profile: get; update (validation, email-change notification enqueue).
• public lookups: referral/:code (valid / invalid / referral-rule errors); invitation/:code (valid / invalid / expired).
• referral cycle: referral-cycle list + pagination; CSV export; referrals/stats active-vs-pending counts.
• referral journey: register with a referral code → referrer's referral-cycle/stats reflect the new member; level-up eligibility flips when the circle is full + verified.
• cancel account: Self_Removed, sessions revoked, subsequent login blocked.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness. Self-skips without Docker. All tests pass.

---

E2E Ticket 6 — Content lifecycle: news, posts, events

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-content

Test Root: tests/integration/

Description

Real-stack coverage of the publish lifecycle for news, posts, and events across the admin (requireAdminOrPublisher) and public surfaces, plus event registration. (No capacity/sanitization assertions — those aren't implemented.)

Files / Scope

tests/integration/http/contentHttp.integration.test.ts

Test Cases

• news / posts: admin create draft → absent from public GET → publish → present in public list + get-by-id → unpublish → gone; update; delete; role gate (User → 403); validation → 400.
• events (admin): create → publish/unpublish; update; delete; GET /events/:id/registrations.
• events (public/member): list / upcoming / old / by-category / by-id; register → my-registrations shows it → registration-status → unregister; duplicate registration handled.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness. Self-skips without Docker. All tests pass.

---

E2E Ticket 7 — Platform surfaces: settings, files/documents, notifications, onboarding, webhooks

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-platform

Test Root: tests/integration/

Description

Real-stack coverage for the remaining admin/platform surfaces. Storage (S3/Bunny) and email providers mocked at the boundary; bulk/onboarding jobs asserted at the enqueue boundary.

Files / Scope

tests/integration/http/platformHttp.integration.test.ts

Test Cases

• settings: public GET; admin create / get-by-key / update / delete / bulk-update; a toggled setting (e.g. KYC-required, registration-disabled) is reflected by the consuming route.
• files: upload single + multiple (multer), with the latin1→UTF-8 filename normalization applied to a non-ASCII name; delete; get-url; auth/role gates.
• documents: admin CRUD; public list / get / download.
• notifications: admin send (enqueue), list, get-by-id, queue-status endpoints, purge-waiting-jobs.
• onboarding: CSV upload (validation of good/bad rows) → start → status → retry-email / retry-failed → history / batch details (bulk email enqueued; no worker).
• webhooks: /webhook/postmark (+ the two other provider webhooks) update the email-notification record; invalid payload/signature rejected.

Acceptance Criteria

All listed flows pass through HTTP against the real-stack harness; storage/email mocked, jobs asserted at enqueue. Self-skips without Docker. All tests pass.

---

E2E Ticket 8 — Admin V-Learning authoring (gated)

Issue Type: Task

Area: API Integration Tests (HTTP e2e)

Branch: cov/COV-XXX-e2e-admin-vlearning

Test Root: tests/integration/

Description

Real-stack coverage for the admin V-Learning authoring surface (modules, lessons, exams/questions, categories, announcements, assignments, results). Prerequisite: the admin vLearningController eagerly loads ESM file-type and is currently stubbed out of the e2e harness; this ticket must first make that import test-loadable (lazy/dynamic import or a vitest-compatible shim) so the controller can be driven over HTTP.

Files / Scope

tests/integration/http/adminVlearningHttp.integration.test.ts

Test Cases

• modules: create → get/list → update → publish/unpublish → set/clear recommended → delete; requireAdmin gate.
• categories: CRUD.
• lessons: create → list → update → reorder → delete (video/resource upload paths can be stubbed at the storage boundary).
• exams/questions: create-or-update exam on a module → add/update/delete/reorder questions → get exam.
• assignment & results: assign module to a user → it appears in that member's assignments (cross-checks Ticket 4); module assignments / progress / results / export.

Acceptance Criteria

The file-type import is made test-loadable; all listed flows pass through HTTP against the real-stack harness (storage mocked). Self-skips without Docker. All tests pass.