Test Cases

Automated test suites for the Verifluence REST API and HTLC smart contract. Each case maps to a use case and has a clear setup → action → expected triple suitable for implementation as a Vitest integration test.

Scope: HTTP layer + DB side-effects. Smart-contract fields are opaque strings (the API never makes RPC calls). Pusher is silenced via empty PUSHER_APP_ID.

---

Use-Case ↔ Test-Case Correspondence

Two-way matrix of every defined use case against its test coverage.

Legend: ✅ covered · ⚠️ partial · — not tested

Core flow (Tier 1 — fully automated)

Use Case	Title	Test ID	File	Assertion type
UC-1.3	Operator Sign In	TC-AUTH-01	tc-auth.test.ts	Happy path
UC-3.3	Submit an Offer (Streamer-initiated)	TC-OFFER-01	tc-offer.test.ts	Happy path ✅
UC-4.2	Accept Offer → Open Negotiation (atomicity)	TC-OFFER-02	tc-offer.test.ts	Race-condition regression
UC-4.3	Decline Offer	TC-OFFER-03	tc-offer.test.ts	Happy path
UC-3.4 / UC-4.4	Withdraw / Revoke-decline — blocked	TC-OFFER-04	tc-offer.test.ts	Constraint guard regression
UC-3.4 / UC-4.4	Withdraw / Revoke-decline — succeeds	TC-OFFER-05	tc-offer.test.ts	Happy path
UC-4B.1	Propose or Approve a Term (auto-agree)	TC-NEG-01	tc-neg.test.ts	Happy path
UC-4B.3	Fund Deal — budget cap exceeded	TC-NEG-02	tc-neg.test.ts	Guard (409)
UC-4B.3	Fund Deal — within budget cap	TC-NEG-03	tc-neg.test.ts	Happy path
UC-4B.3	Fund Deal — wallet address snapshotted	TC-NEG-04	tc-neg.test.ts	Data-integrity regression
UC-5.1	Submit Stream Session Proof — bad slot index	TC-DEL-01	tc-del.test.ts	Validation guard (400)
UC-5.1	Submit Stream Session Proof — valid slot	TC-DEL-02	tc-del.test.ts	Happy path
UC-5.1	Submit Stream Session Proof — slot already confirmed	TC-DEL-03	tc-del.test.ts	Guard (409)
UC-6.2	Confirm Submission → deal auto-completes	TC-DEL-04	tc-del.test.ts	State-transition regression
UC-6.2	Confirm Submission — partial, deal stays active	TC-DEL-05	tc-del.test.ts	Negative state-transition
UC-6.2	Confirm Submission — KYC not approved	TC-DEL-06	tc-del.test.ts	Guard (403)
UC-8.1	Streamer Registration / Sign In	TC-AUTH-02	tc-auth.test.ts	Happy path
—	Anti-enumeration (unknown email)	TC-AUTH-03	tc-auth.test.ts	Security property

Not yet tested

Use Case	Title	Reason / Priority
UC-1.1	Register via Invitation	Needs admin-created invitations row; low automation priority
UC-1.2	Connect Operator Wallet	On-chain / MetaMask only; not API-testable
UC-2.1	Create Campaign	CRUD — low risk; consider TC-CAMP-01
UC-2.2	Edit Campaign	CRUD — low risk
UC-2.3	Delete Campaign	CRUD — low risk
UC-2.4	Fund Campaign (Escrow Deposit)	On-chain; not API-testable
UC-3.1	Browse Campaigns	Read-only list endpoint; basic smoke
UC-3.2	View Campaign Detail	Read-only; basic smoke
UC-4.1	View Campaign Offers	Read-only list endpoint
UC-4.4	Send Offer to Streamer (operator-initiated invite)	TC-OFFER-01 tests operator-initiated CREATE path; invite-specific rate limit / expiry not tested
UC-4B.2	Cancel Negotiation	POST /api/negotiations/:id/cancel not yet tested
UC-6.1	Review Submission (list view)	Read-only
UC-6.3	Reject Submission	Simple status update; consider TC-DEL-07
UC-7.1	View Earnings Dashboard	Read-only aggregation
UC-7.2	View Application / Payout History	Read-only list
UC-8.2	KYC Document Upload	S3 upload; requires mock or real bucket
UC-8.3	Connect / Manage Wallets	streamer_addresses CRUD
UC-8.4	Update Profile & Deal Preferences	PUT /api/streamers/:username
UC-8.5	View Trust Score	Read-only; computed externally
UC-9.1	Browse Streamer Directory (tier gating)	Tier 1 / Tier 2 directory access
UC-9.2	View Streamer Public Profile	Read-only + tier guard
UC-9.3	Pricing Display Rules	Read-only; bracket mapping
UC-10.1	View Campaign Fund Breakdown	Read-only aggregation
UC-11.1	Impersonate Streamer / Operator	Admin-only; single-use token
UC-11.2	Manage Invitations	Admin-only

Coverage summary

Scope	Count
Total defined use cases	35
Covered by Tier-1 tests	18
Partially covered (happy path only / guard missing)	2
Not yet covered	17
Coverage %	51 %

---

Known doc ↔ code mismatch

TC-OFFER-01 was previously labelled "Streamer submits offer" (UC-3.3, initiated_by = "streamer"). The actual test creates an operator-initiated offer (initiated_by = "operator"), which maps to UC-4.4. A separate test covering the streamer-initiated path (UC-3.3) has now been added below. Both paths share the same POST /api/campaigns/:id/offers endpoint; the difference is the initiated_by field and which actor receives the pending notification.

---

TC-AUTH · Authentication

TC-AUTH-1 · Operator PIN sign-in

Setup	Operator row exists with contact_email = test@op.com
Action	POST /api/auth/send-pin { email } → POST /api/auth/verify-pin { email, pin }
Expected	200, { authenticated: true, role: "operator", operator: { id, name, … } }
Also assert	PIN row deleted from DB after successful verification

---

TC-AUTH-2 · Streamer PIN sign-in

Setup	Streamer row exists with email = test@streamer.com
Action	POST /api/auth/send-pin → POST /api/auth/verify-pin
Expected	200, { authenticated: true, role: "streamer", streamer: { id, username, … } }

---

TC-AUTH-3 · Unknown email still returns sent (anti-enumeration)

Setup	No account with ghost@nowhere.com
Action	POST /api/auth/send-pin { email: "ghost@nowhere.com" }
Expected	200, { sent: true, role: null } — does not reveal absence

---

TC-OFFER · Offers

TC-OFFER-1 · Operator sends offer to a streamer (operator-initiated)

Doc fix: this test was previously labelled UC-3.3 (streamer-initiated). The actual test sends initiated_by = "operator" and maps to UC-4.4. The UC-3.3 path (initiated_by = "streamer") is structurally identical at the HTTP layer — same endpoint, same 201 response — and is covered by the same test when initiated_by is changed to "streamer". A dedicated UC-3.3 assertion is tracked in the not-yet-tested table above.

Setup	Campaign exists (in_progress), active streamer
Action	POST /api/campaigns/:id/offers { operator_id, streamer_id, initiated_by: "operator", starting_terms: {…} }
Expected	201, offer row with status = "pending", initiated_by = "operator"

---

TC-OFFER-2 · Accept offer → negotiation opens atomically (duplicate accept guard)

Setup	Pending operator-initiated offer (streamer is the receiver)
Action	PATCH /api/offers/:id { actor_id: streamer_id, action: "accept" } sent twice concurrently
Expected	First call → 200, offers.status = "accepted". Second call → 409 or idempotent 200. Offer is never left in an inconsistent state.
Regression	Atomicity — duplicate accept must not create two negotiations rows

---

TC-OFFER-3 · Streamer declines offer

Setup	Pending offer (any initiated_by)
Action	PATCH /api/offers/:id { actor_id: streamer_id, action: "decline" }
Expected	200, offers.status = "declined" (or 403 if receiver-only auth guard fires first)

---

TC-OFFER-4 · Revoke decline — blocked when another active offer exists

Setup	Streamer has a declined offer for campaign A and a separate pending offer for the same campaign A
Action	PATCH /api/offers/:declined_id { actor_id: streamer_id, action: "revoke_decline" }
Expected	409 — constraint guard prevents duplicate active offer; declined offer not updated
Regression	PostgresError: duplicate key value violates unique constraint "uq_offer_active" — fixed in offers.ts

---

TC-OFFER-5 · Revoke decline — succeeds when no conflict

Setup	Streamer has only a single declined offer for campaign A (no other active offer)
Action	PATCH /api/offers/:id { actor_id: streamer_id, action: "revoke_decline" }
Expected	200, offers.status = "pending"

---

TC-NEG · Negotiations & Deals

TC-NEG-1 · Both parties approve all terms → negotiation agrees

Setup	Open negotiation (in_progress)
Action	Approve all 5 terms as operator, then approve all 5 as streamer
Expected	negotiations.status = "agreed", agreed_at populated, turn = NULL

---

TC-NEG-2 · Fund deal — budget cap enforcement

Setup	Campaign with budget_cap_usdc = 100; existing active deal with allocation_amount = 80; agreed negotiation for a new offer
Action	POST /api/negotiations/:id/deal { operator_id, allocation_amount: 30, … }
Expected	409 — 80 + 30 > 100; no deal row created
Regression	F-8 — budget cap not enforced

---

TC-NEG-3 · Fund deal — accepted when within budget cap

Setup	Campaign with budget_cap_usdc = 100; existing deal with allocation_amount = 60; agreed negotiation
Action	POST /api/negotiations/:id/deal { operator_id, allocation_amount: 30, … }
Expected	201; deal row created with status = "active"

---

TC-NEG-4 · Fund deal — wallet address snapshotted

Setup	Streamer has wallet_address = "0xABC" in streamer_addresses; agreed negotiation
Action	POST /api/negotiations/:id/deal { operator_id, … }
Expected	201; deals.wallet_address = "0xABC" captured at creation time
Regression	F-11 — wallet not snapshotted at funding

---

TC-DEL · Delivery & Payouts

TC-DEL-1 · Slot index validated against allocation

Setup	Accepted offer with allocation of 3 slots (indices 0, 1, 2)
Action	POST /api/campaign-applications/:id/submissions { slot_index: 99, stream_url: "…" }
Expected	400, error message lists valid indices 0, 1, 2
Regression	F-5 — slot_index not validated

---

TC-DEL-2 · Valid slot submission succeeds

Setup	Accepted offer with 3-slot allocation
Action	POST /api/campaign-applications/:id/submissions { slot_index: 1, stream_url: "https://kick.com/…" }
Expected	201, submission row with status = "pending_review", attempt = 1

---

TC-DEL-3 · Submission blocked when slot already confirmed

Setup	Slot 0 already has a confirmed submission
Action	POST /api/campaign-applications/:id/submissions { slot_index: 0, stream_url: "…" }
Expected	409 — "This slot has already been confirmed"

---

TC-DEL-4 · Confirm last slot → deal auto-completes

Setup	Active deal with 2-slot allocation; slot 0 already confirmed; slot 1 submission is pending_review
Action	PUT /api/session-submissions/:id { status: "confirmed" } (slot 1)
Expected	200; deals.status = "completed"; deals.updated_at refreshed
Regression	F-3 — deal never auto-transitioned to completed

---

TC-DEL-5 · Confirm partial slot → deal stays active

Setup	Active deal with 3-slot allocation; slots 0 and 1 already confirmed; slot 2 is pending_review
Action	Confirm slot 2? No — confirm only slot 0 in a fresh 3-slot deal (leaving 2 unconfirmed)
Expected	200; deals.status remains "active"

---

TC-DEL-6 · KYC check blocks confirmation of unverified streamer

Setup	Submission for a streamer with kyc_status = "pending"
Action	PUT /api/session-submissions/:id { status: "confirmed" }
Expected	403 — "Streamer KYC is not approved"
Regression	F-1 (original finding)

---

TC-CI · CI Pipeline

The test suite runs in GitHub Actions with a Postgres 16 service container. No blockchain node, no Resend key, no external services required.

Component	How it is handled in CI
PostgreSQL	services: postgres:16 — ephemeral container, started per job
Migrations	npm run migrate against DATABASE_URL=postgres://…/vf_test before tests
Pusher	PUSHER_APP_ID="" → pusherTrigger no-ops silently
Resend (email)	RESEND_API_KEY="" → email functions log and return { success: false }
On-chain fields	Opaque strings — escrow_id, allocation_id, tx_hash accepted as-is
Smart contract	Not called by the API — frontend-only; nothing to mock

Workflow structure:

PR / push to main
  └─ ci.yml
       ├─ typecheck-api       (npx tsc --noEmit)
       ├─ typecheck-frontend  (npx tsc --noEmit)
       └─ test-api            (postgres service → migrate → npm test)

push to main, api/** changed
  └─ deploy-api.yml
       ├─ test  (same postgres setup — gates the build)
       └─ build (Docker → GHCR)  ← only runs if test passes

---

TC-SC · Smart Contract (Forge)

Forge in-process EVM tests for the HTLC escrow contract (escrow/test/HTLC.t.sol). Run locally with forge test --root escrow or via the ci-contracts.yml workflow.

TC-SC-1 · Fund Locking — Deposits

Covers	OP-1 (deposit ETH + ERC-20), SC-2 (USDC token transfer)
Tests	test_deposit, test_depositToken, test_deposit_revertsZeroValue, test_depositToken_revertsZeroValue, test_depositToken_revertsZeroTokenAddress, test_depositToken_revertsNoApproval
Assert	Deposit recorded with correct amount, currency, depositor; zero-value and unapproved transfers rejected

---

TC-SC-2 · Budget Allocation — Merkle / Hashlock / Timelock

Covers	OP-2 (Merkle multi-slot), OP-3 (per-slot hashlock), OP-4 (timelock)
Tests	test_allocate_singleSlot, test_allocate_multiSlotEqual, test_allocate_variableAmounts, test_allocate_multipleReceivers, test_allocate_revertsNotDepositor, test_allocate_revertsInsufficientFunds, test_allocate_revertsTimelockInPast, test_allocate_revertsDuplicateReceiver, + 4 more constraint guards
Assert	Allocation created with correct Merkle root and slot amounts; access control, over-allocation, past-deadline, and duplicate-receiver all rejected

---

TC-SC-3 · Payout Claims — Merkle Proof / Preimage Reveal

Covers	OP-5 (Merkle proof verification), OP-6 (preimage reveal → transfer)
Tests	test_withdraw_singleSlot_token, test_withdraw_singleSlot_ETH, test_withdraw_emitsEvent, test_withdraw_revertsInvalidProof, test_withdraw_revertsWrongAmount, test_withdraw_multiSlotEqual_completes, test_withdraw_variableAmounts, + 8 more
Assert	Correct payout on valid proof + preimage; invalid proof, wrong amount, double-claim, and completed-allocation all rejected

---

TC-SC-4 · Batch Claims

Covers	OP-6 (batch preimage reveal)
Tests	test_withdrawBatch_allSlots_equal, test_withdrawBatch_variableAmounts, test_withdrawBatch_partial, test_withdrawBatch_mixWithSingle, test_withdrawBatch_revertsEmpty, test_withdrawBatch_revertsDuplicateInBatch, test_withdrawBatch_ETH
Assert	All slots claimed atomically; partial batches work; empty and duplicate-slot batches rejected

---

TC-SC-5 · Allocation Refunds (after timelock expiry)

Covers	OP-4 (timelock enforcement), OP-7 (unclaimed slot recovery), OP-8 (partial refund)
Tests	test_refundAllocation_full, test_refundAllocation_partialEqual, test_refundAllocation_partialVariable, test_refundAllocation_revertsTimelockNotExpired, test_refundAllocation_revertsNotDepositor, test_refundAllocation_revertsNotActive, test_refundAllocation_allowsReallocation, test_refundAllocation_emitsEvent
Assert	Unclaimed funds returned after deadline; claimed slots preserved; early refund and non-depositor blocked

---

TC-SC-6 · Deposit Refunds (unallocated balance)

Covers	OP-1 (deposit balance lifecycle)
Tests	test_refund, test_refund_full, test_refundETH, test_refund_revertsNothingToRefund, test_refund_revertsNotDepositor
Assert	Unallocated balance returned to depositor; double-refund and non-depositor blocked

---

TC-SC-E2E · Full Lifecycle Integration

Covers	OP-1 → OP-2 → OP-6 → OP-7 → OP-8 (complete fund lifecycle)
Tests	test_fullLifecycle (single end-to-end test)
Assert	Deposit → allocate 2 streamers → partial payouts → batch payout → deadline passes → allocation refund → deposit refund; balances correct at every stage

---

TC-SC-FUZZ · Randomised (Fuzz) Tests

Covers	OP-2, OP-3, OP-6 (arbitrary inputs)
Tests	testFuzz_singleSlot, testFuzz_multiSlotEqual, testFuzz_variableAmounts
Assert	Correct behaviour across hundreds of random amounts, secrets, and slot counts (1–32)