diff --git a/07 - Development/Testing.md b/07 - Development/Testing.md index 702bc53..9a8ebce 100644 --- a/07 - Development/Testing.md +++ b/07 - Development/Testing.md @@ -7,6 +7,9 @@ tags: [development] Both repos use **Jest** as the unit/integration runner. The frontend additionally uses **React Testing Library** for component tests and **Playwright** for end-to-end browser tests. This page covers what exists today, how to run it, and how to add new tests. +For cross-service procedures, live-dev E2E scenarios, scanner payment runs, CI +verification, and release-blocking test gaps, see [[11 - Testing/Testing Overview]]. + --- ## Backend testing diff --git a/11 - Testing/Escrow Marketplace E2E Procedure.md b/11 - Testing/Escrow Marketplace E2E Procedure.md new file mode 100644 index 0000000..3106c62 --- /dev/null +++ b/11 - Testing/Escrow Marketplace E2E Procedure.md @@ -0,0 +1,207 @@ +--- +title: Escrow Marketplace E2E Procedure +tags: [testing, e2e, escrow, marketplace, buyer, seller] +created: 2026-06-06 +--- + +# Escrow Marketplace E2E Procedure + +This procedure validates the marketplace flow with one buyer and at least two +sellers. Use it for live dev validation after payment, marketplace, delivery, +or scanner changes. + +## Preconditions + +- Dev API is reachable: `GET https://dev.amn.gg/api/version`. +- Backend, frontend, and scanner containers are healthy. +- Admin credentials are available through a secure local channel, not docs. +- BSC Testnet wallet has enough tBNB for gas and enough canonical tUSDT. +- Backend/scanner chain 97 registry points to `0x109F54Dab34426D5477986b0460aE5dFBA65f022`. +- Local wallet private key or mnemonic is stored only in ignored `.env`. + +## Actors + +| Actor | Count | Role | +|---|---:|---| +| Buyer | 1 | Creates request, accepts offer, funds payment, confirms delivery. | +| Sellers | 2 minimum, 3 preferred | Submit competing offers and delivery evidence. | +| Admin | 1 | Creates test users and can inspect/repair state. | + +## High-Level Procedure + +1. Generate a run id. +2. Admin creates one buyer and at least two sellers. +3. Buyer creates purchase request with a min/max USDT budget. +4. Sellers submit bids inside the budget range. +5. Randomize or vary: + - bid amount, + - delivery timing, + - seller note, + - delivery method. +6. Buyer selects a bid. +7. Backend creates scanner payment intent. +8. Buyer pays with BSC Testnet tUSDT. +9. Scanner confirms the payment. +10. Seller marks delivery. +11. Buyer confirms delivery. +12. Record current block: flow pauses before automated release policy. + +## Expected State Transitions + +| Step | Purchase request expectation | Payment expectation | +|---|---|---| +| Request created | request visible to sellers | no payment | +| Offers submitted | `received_offers` or equivalent offer-ready state | no payment | +| Offer accepted | selected offer stored | payment intent can be created | +| Payment sent | payment/check pending or processing | scanner sees chain/token/destination/amount | +| Scanner confirms | request can proceed to delivery path | status paid/confirmed/completed depending endpoint | +| Seller delivers | `delivery` | escrow remains held | +| Buyer confirms | `delivered`, `deliveryConfirmed=true` | release policy not automatic yet | + +## Buyer Request Template + +Use unique values so live data can be filtered later: + +```json +{ + "title": "Scanner BSC Testnet E2E R", + "description": "Automated scanner payment test round ", + "productType": "physical_product", + "productLink": "https://example.test/e2e//", + "quantity": 1, + "budget": { + "min": 0.18, + "max": 0.48, + "currency": "USDT" + }, + "urgency": "medium" +} +``` + +## Seller Bid Rules + +For each round: + +- create at least two bids; +- prefer three bids so ranking/selection is clearer; +- keep all bids within buyer min/max budget; +- vary delivery timing, for example 1 day, 4 days, 7 days; +- pick a deterministic winner rule for automation, such as lowest price. + +Example bid set: + +| Seller | Amount | Delivery | +|---|---:|---| +| seller1 | `0.31 USDT` | `7 days` | +| seller2 | `0.28 USDT` | `5 days` | +| seller3 | `0.26 USDT` | `4 days` | + +## Delivery Proof + +Seller delivery should include structured proof where the API supports it: + +```json +{ + "proof": { + "type": "e2e", + "runId": "", + "round": 1, + "note": "Seller delivery proof for automated dev test" + } +} +``` + +Buyer confirmation may use similar metadata: + +```json +{ + "proof": { + "type": "e2e-confirmation", + "runId": "", + "round": 1 + } +} +``` + +## Assertions + +Minimum assertions per round: + +| Assertion | Required | +|---|---| +| Buyer login succeeds | yes | +| Seller logins succeed | yes | +| Request id is created | yes | +| At least two offer ids are created | yes | +| Selected offer id matches accepted seller | yes | +| Payment id is created | yes | +| Payment chain id is `97` | yes | +| Payment token is canonical tUSDT | yes | +| On-chain tx hash exists | yes | +| Scanner check returns paid/confirmed | yes | +| Seller delivery returns HTTP 200 | yes | +| Buyer confirm delivery returns HTTP 200 | yes | +| Final request status is `delivered` | yes | + +## Reference Execution - 2026-06-06 + +Run id: + +```text +20260606043238 +``` + +Generated users: + +| Actor | Email | +|---|---| +| Buyer | `amn-e2e-20260606043238-buyer@example.test` | +| Seller 1 | `amn-e2e-20260606043238-seller1@example.test` | +| Seller 2 | `amn-e2e-20260606043238-seller2@example.test` | +| Seller 3 | `amn-e2e-20260606043238-seller3@example.test` | + +Round 1: + +| Field | Value | +|---|---| +| purchaseRequestId | `732e9de8-9631-484e-a5ac-bb657ca55020` | +| paymentId | `f7f02ba4-9154-4408-984b-d3481d1ec5fa` | +| selectedOfferId | `263b30f0-7ee6-4e63-9d0a-af2d7624fdde` | +| selected seller | `seller3` | +| amount | `0.26 USDT` | +| token | `0x109F54Dab34426D5477986b0460aE5dFBA65f022` | +| txHash | `0x7a5c2785161df3367374574d8e1af00c548131c8a44c3fa06b592966920e3edc` | +| scanner result | paid | +| final request status | `delivered` | + +Round 2: + +| Field | Value | +|---|---| +| purchaseRequestId | `da34d9bc-2b2d-4dc3-98f0-aa1a07a55ebb` | +| paymentId | `2e8582eb-3ac3-4793-b10f-ea721b6466d4` | +| selectedOfferId | `36e3a912-2121-4f07-87e6-4c73b1adf224` | +| selected seller | `seller2` | +| amount | `0.32 USDT` | +| token | `0x109F54Dab34426D5477986b0460aE5dFBA65f022` | +| txHash | `0x861a1197d7d345609f5a46b1a3723a29877ba9929bd1e7b21f7060381a1b14d0` | +| scanner result | paid | +| final request status | `delivered` | + +Important finding from this run: + +- Payment confirmation succeeded after correcting the chain 97 token registry to the actual tUSDT contract. +- Buyer delivery confirmation initially failed with HTTP 403 because user ids were compared across stores directly. Backend `2.8.117` fixed the id comparison; both confirmations then returned HTTP 200. + +## Current Product Boundary + +The procedure currently stops at `delivered`. + +Release policy is not complete: + +- physical-product grace period is not implemented; +- gift-card/digital immediate release is not implemented; +- dispute-to-release/refund automation is not complete. + +Use [[Testing Expansion Backlog]] before extending this scenario into fund release. + diff --git a/11 - Testing/Scanner BSC Testnet Payment Procedure.md b/11 - Testing/Scanner BSC Testnet Payment Procedure.md new file mode 100644 index 0000000..baff5d1 --- /dev/null +++ b/11 - Testing/Scanner BSC Testnet Payment Procedure.md @@ -0,0 +1,180 @@ +--- +title: Scanner BSC Testnet Payment Procedure +tags: [testing, scanner, payment, bsc-testnet, usdt] +created: 2026-06-06 +--- + +# Scanner BSC Testnet Payment Procedure + +This procedure validates that dev payments use the correct BSC Testnet tUSDT +contract and that scanner confirms the payment. + +Related docs: + +- [[04 - Flows/Payment Flow - Scanner]] +- [[01 - Architecture/Scanner Architecture]] +- [[03 - API Reference/Scanner API]] + +## Preconditions + +- Dev stack is healthy. +- Scanner is deployed from the latest Forgejo `scanner` commit. +- Backend and scanner token registries agree on chain 97 USDT. +- Frontend `2.8.118+` is deployed if wallet UI is part of the test. +- Test wallet has: + - tBNB for gas, + - tUSDT at `0x109F54Dab34426D5477986b0460aE5dFBA65f022`. + +## Chain Registry Smoke + +Run from backend: + +```bash +cd ~/CascadeProjects/escrow/backend +BASE_URL=https://dev.amn.gg bash scripts/smoke/bsc-testnet-payment-registry.sh +``` + +Expected: + +- chain 97 exists; +- USDT address is `0x109f54dab34426d5477986b0460ae5dfba65f022`; +- decimals are `18`; +- RPC URL is a BSC Testnet RPC; +- frontend/backend metadata does not point to the old token. + +## Live Scanner Balance Check + +From a backend or host context that can reach scanner, check the funded wallet +by symbol. + +Expected fields: + +| Field | Expected | +|---|---| +| `chainId` | `97` | +| `tokenSymbol` | `USDT` | +| `tokenAddress` | `0x109f54dab34426d5477986b0460ae5dfba65f022` | +| `decimals` | `18` | +| `balance` | positive base-unit balance | + +If BscScan shows token balance but scanner returns zero, the usual cause is a +token contract mismatch. + +## Direct-Balance Payment Flow + +```mermaid +sequenceDiagram + autonumber + actor B as Buyer wallet + participant FE as Frontend/API test + participant BE as Backend + participant SC as Scanner + participant BSC as BSC Testnet + + FE->>BE: Create payment intent + BE->>SC: Store baseline balance for destination/token + SC->>BSC: balanceOf(destination) + SC-->>BE: baseline recorded + FE-->>B: Show destination, amount, token + B->>BSC: transfer tUSDT to destination + FE->>BE: "I paid" / direct-balance check + BE->>SC: POST /balances/check + SC->>BSC: balanceOf(destination) + SC-->>BE: delta >= expected amount + BE-->>FE: payment paid/confirmed +``` + +## Required Assertions + +| Assertion | Why | +|---|---| +| Intent uses chain `97` | Ensures testnet path, not BSC mainnet. | +| Intent uses token `0x109F54...` | Ensures canonical test USDT. | +| Amount base units equals decimal amount * `10^18` | Prevents 6-vs-18 decimal errors. | +| Destination address matches scanner check | Prevents false positives from wrong wallet. | +| Tx hash exists on BSC Testnet | Confirms buyer transfer actually happened. | +| Scanner reports `paid` or `confirmed` | Confirms scanner sees the transfer. | +| Backend marks payment paid/confirmed | Confirms scanner result reaches business state. | + +## Negative Scenarios + +These are designed and should be automated before release confidence is claimed. + +### Wrong token + +1. Create a chain 97 tUSDT intent. +2. Pay the same amount using a different token contract. +3. Run scanner balance check. + +Expected: + +- intended tUSDT destination delta is unchanged; +- payment remains pending; +- logs explain token mismatch or no matching delta. + +### Underpayment + +1. Create an intent for `0.30 USDT`. +2. Transfer `0.29 USDT`. +3. Run scanner balance check. + +Expected: + +- scanner returns unpaid or insufficient delta; +- backend does not mark payment paid. + +### Wrong destination + +1. Create a valid intent. +2. Transfer exact token/amount to a different address. +3. Run scanner balance check for the intended destination. + +Expected: + +- intended payment remains pending. + +### Duplicate payment + +1. Complete a payment successfully. +2. Transfer the same amount to the same destination again. +3. Trigger check/webhook path again. + +Expected: + +- no duplicate ledger credit; +- payment remains single-paid; +- second transfer is either ignored or tracked as overpayment/manual recovery. + +### Missing gas + +1. Use a wallet with tUSDT but no tBNB. +2. Attempt payment through checkout UI. + +Expected: + +- wallet cannot broadcast transaction; +- UI shows wallet/network/gas error; +- scanner does not mark paid. + +## UI Assertions + +For frontend `2.8.118+`: + +| UI item | Expected | +|---|---| +| Network row | `BSC Testnet (97)` | +| Token contract row | `USDT 0x109F...f022` with copy/link support | +| Address link | `https://testnet.bscscan.com/address/...` | +| Tx link | `https://testnet.bscscan.com/tx/...` | +| Wallet switch | chain id `97` is supported by Wagmi config | + +## Troubleshooting + +| Symptom | Likely cause | Check | +|---|---|---| +| Wallet funded but scanner sees zero | Wrong token contract in scanner/backend registry | `tokens.json`, `supported-chains.json`, scanner balance result | +| Intent id looks like `undefined-c56-USDC` | Backend adapter fell back to global merchant/default context | `scannerContext` in backend AMN scanner intent path | +| Payment waits for too many confirmations | Runtime/admin threshold for chain 97 too high | `confirmation_threshold:97` | +| UI links to mainnet BscScan | Frontend explorer map missing chain 97 | frontend checkout version | +| Wallet cannot switch to testnet | Wagmi config missing `bscTestnet` | frontend `src/web3/config.ts` | + diff --git a/11 - Testing/Smoke and Regression Procedure.md b/11 - Testing/Smoke and Regression Procedure.md new file mode 100644 index 0000000..327161a --- /dev/null +++ b/11 - Testing/Smoke and Regression Procedure.md @@ -0,0 +1,168 @@ +--- +title: Smoke and Regression Procedure +tags: [testing, smoke, regression, ci, deploy] +created: 2026-06-06 +--- + +# Smoke and Regression Procedure + +This page defines the standard checks before and after backend/frontend/scanner +changes. + +## Local/Pre-Push Rules + +For frontend or backend code changes: + +1. Run focused tests for the touched area. +2. Run typecheck. +3. Run `git diff --check`. +4. Bump backend and frontend patch versions together if a build/deploy will be pushed. +5. For payment/scanner changes, run the relevant smoke script before pushing. + +Docs-only changes do not require version bumps. + +## Backend Smoke Scripts + +Backend smoke scripts live in: + +```text +backend/scripts/smoke/ +``` + +Current scripts: + +| Script | Purpose | +|---|---| +| `backend-health.sh` | Basic API health/version target check. | +| `auth-basic.sh` | Basic auth behavior. | +| `addresses-basic.sh` | Address APIs. | +| `bsc-testnet-payment-registry.sh` | Chain 97 token/RPC registry sanity. | +| `confirmation-thresholds.sh` | Confirmation threshold APIs/settings. | +| `funds-ledger-repo.sh` | Funds ledger repository behavior. | +| `marketplace-request-budget.sh` | Purchase request budget validation. | +| `rn-intent.sh` | Request Network / in-house intent creation smoke. | +| `rn-webhook.sh` | Webhook shape/signature flow. | +| `user-admin-postgres.sh` | Admin user persistence. | +| `user-dependencies.sh` | User dependency smoke. | + +Run against dev: + +```bash +cd ~/CascadeProjects/escrow/backend +BASE_URL=https://dev.amn.gg bash scripts/smoke/bsc-testnet-payment-registry.sh +``` + +Run against local: + +```bash +BASE_URL=http://127.0.0.1:5001 bash scripts/smoke/backend-health.sh +``` + +## Focused Automated Tests + +Payment/scanner backend focus: + +```bash +cd ~/CascadeProjects/escrow/backend +npm test -- --runTestsByPath \ + __tests__/rn-in-house-checkout.test.ts \ + __tests__/decentralized-payment-verifier.test.ts \ + __tests__/amn-pay-adapter-intent.test.ts \ + --runInBand +``` + +Marketplace/delivery focus: + +```bash +npm test -- --runTestsByPath \ + __tests__/simple-marketplace.test.ts \ + __tests__/marketplace-idor.test.ts \ + __tests__/escrow-state-machine.test.ts \ + --runInBand +``` + +Frontend checkout focus: + +```bash +cd ~/CascadeProjects/escrow/frontend +npx tsc --noEmit --ignoreDeprecations 6.0 +npx eslint src/web3/config.ts src/web3/types.ts src/sections/payment/checkout/rn-in-house-checkout-view.tsx +npm run build +``` + +Scanner focus: + +```bash +cd ~/CascadeProjects/escrow/scanner +go test ./... +``` + +## CI/Deploy Verification + +Use Woodpecker with token from the local environment: + +```bash +export WOODPECKER_SERVER=https://ci.tbs.amn.gg +export WOODPECKER_TOKEN= +``` + +Never commit or paste the token into docs. + +Poll latest pipelines by repo id: + +| Repo | Woodpecker repo id | Expected pipeline | +|---|---:|---| +| backend | `5` | typecheck, build-and-deploy, notify | +| frontend | `7` | build-and-deploy, notify | +| scanner | `8` | build/test/deploy | + +Required post-deploy checks: + +```bash +curl -fsS https://dev.amn.gg/api/version +curl -fsS -I https://dev.amn.gg/ +ssh -i root@ \ + "docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}' | grep -E 'escrow-(backend|frontend|scanner)'" +``` + +Expected: + +- `/api/version` matches package version for backend/frontend build pair; +- frontend root returns HTTP 200; +- backend/frontend/scanner containers are healthy; +- corresponding Woodpecker pipelines are `success`. + +## Regression Evidence Format + +For every test run, record: + +```markdown +### YYYY-MM-DD - + +- Target: `https://dev.amn.gg` +- Versions: backend/frontend/scanner +- CI: backend #, frontend #, scanner # +- Commands: + - `...` +- Live scenarios: + - run id + - request ids + - payment ids + - tx hashes +- Result: pass/fail/blocked +- Residual risk: + - ... +``` + +## When To Stop a Release + +Stop or roll back if any P0 condition fails: + +- payment can be marked paid without correct chain/token/destination/amount evidence; +- buyer cannot complete a valid payment; +- non-buyer can confirm delivery; +- frontend cannot connect/switch to the chain returned by backend checkout; +- backend/frontend/scanner registry mismatch exists; +- CI deploy reports success but live containers are not healthy; +- secrets appear in git status, logs, docs, or CI output. + diff --git a/11 - Testing/Test Environment and Data.md b/11 - Testing/Test Environment and Data.md new file mode 100644 index 0000000..ffc69d6 --- /dev/null +++ b/11 - Testing/Test Environment and Data.md @@ -0,0 +1,142 @@ +--- +title: Test Environment and Data +tags: [testing, environment, data, secrets, bsc-testnet] +created: 2026-06-06 +--- + +# Test Environment and Data + +This page defines the shared test environment and safe test-data practices. + +## Environments + +| Environment | URL / location | Purpose | +|---|---|---| +| Dev web/API | `https://dev.amn.gg` | Live development deployment used for end-to-end validation. | +| Dev host | Deployment host over SSH | Docker stack, Woodpecker agent, scanner/backend/frontend containers. | +| Forgejo | `git.tbs.amn.gg` | Source of pushed backend/frontend/scanner/docs repos. | +| Woodpecker | `https://ci.tbs.amn.gg` | CI/CD for dev images and Docker stack updates. | +| BSC Testnet | chain id `97` | Real testnet chain used for token payment validation. | + +## Secrets Policy + +Do not write secrets into docs, commits, shell history snippets, screenshots, or +issue reports. + +Secrets include: + +- admin password +- CI token +- SSH private key +- wallet mnemonic +- wallet private key +- `.env` contents +- scanner API keys or webhook secrets + +Safe to document: + +- public wallet addresses +- public tx hashes +- token contract addresses +- chain ids +- request/payment/offer ids from test data +- command shapes with placeholder env vars + +## Wallets + +For live payment tests, create a fresh test wallet programmatically and store +the secret material only in an ignored local `.env`. + +Required checks: + +```bash +cd ~/CascadeProjects/escrow/backend +git check-ignore -v .env +git status --short --ignored .env +stat -f '%Sp %N' .env +``` + +Expected: + +- `.env` is ignored. +- `.env` is not tracked. +- file mode is restrictive, ideally `600`. + +Current funded dev test wallet public address: + +```text +0x052D3D7F112A2CF1B0f65D9B8D6a91899d46e898 +``` + +Never document its seed phrase or private key. + +## BSC Testnet Tokens + +| Token | Chain id | Contract | Decimals | Notes | +|---|---:|---|---:|---| +| Test USDT | `97` | `0x109F54Dab34426D5477986b0460aE5dFBA65f022` | `18` | Canonical dev tUSDT for scanner tests. | +| Test USDC | `97` | `0x64544969ed7EBf5f083679233325356EbE738930` | `18` | Secondary test token. | + +The backend, scanner, and frontend must agree on the same chain/token registry. +If the wallet has tUSDT but scanner reads zero, first check that chain 97 USDT +points at `0x109F54...`, not an older faucet token. + +## Test Users + +Use generated users with a unique run id: + +```text +amn-e2e--buyer@example.test +amn-e2e--seller1@example.test +amn-e2e--seller2@example.test +amn-e2e--seller3@example.test +``` + +Roles: + +| Actor | Suggested role | Why | +|---|---|---| +| Buyer | `tester` | Allows testnet payment rails when dev config gates them by tester role. | +| Sellers | seller-capable test users | Submit bids and delivery evidence. | +| Admin | existing admin account | Creates users and can inspect/repair state. | + +Do not commit generated passwords. If an automation creates passwords, keep the +pattern inside the local script or secret manager, not in docs. + +## Run ID Convention + +Every live E2E run should generate one run id and include it in: + +- test user emails +- purchase request titles +- product links +- delivery proof metadata +- local log filename + +Example: + +```text +runId = 20260606043238 +title = Scanner BSC Testnet E2E 20260606043238 R1 +``` + +## Evidence To Capture + +For every live payment round, record: + +| Field | Example | +|---|---| +| run id | `20260606043238` | +| buyer email | generated `@example.test` email | +| seller emails | generated `@example.test` emails | +| purchase request id | UUID | +| selected offer id | UUID | +| payment id | UUID | +| chain id | `97` | +| token address | `0x109F54...` | +| amount base units | `260000000000000000` | +| tx hash | `0x...` | +| scanner status | `paid` / `confirmed` | +| delivery status | `delivery` / `delivered` | +| CI builds | backend/frontend/scanner pipeline numbers | + diff --git a/11 - Testing/Test Scenario Catalog.md b/11 - Testing/Test Scenario Catalog.md new file mode 100644 index 0000000..08c7b8b --- /dev/null +++ b/11 - Testing/Test Scenario Catalog.md @@ -0,0 +1,91 @@ +--- +title: Test Scenario Catalog +tags: [testing, scenarios, qa, e2e] +created: 2026-06-06 +--- + +# Test Scenario Catalog + +This catalog lists the designed test flows. Each scenario should eventually +have an automation owner, a smoke command, and a UAT checklist. + +## Priority Model + +| Priority | Meaning | +|---|---| +| P0 | Blocks release or payment trust if failing. | +| P1 | Core user experience or operational reliability. | +| P2 | Important edge case with workaround. | +| P3 | Nice-to-have or exploratory. | + +## Scenario Matrix + +| ID | Scenario | Priority | Current status | Procedure | +|---|---|---:|---|---| +| ESCROW-E2E-001 | Buyer creates request, multiple sellers bid, buyer accepts, pays, seller delivers, buyer confirms | P0 | Live tested on dev, two rounds | [[Escrow Marketplace E2E Procedure]] | +| PAY-SCAN-001 | BSC Testnet tUSDT direct-balance scanner confirms funded wallet transfer | P0 | Live tested on dev | [[Scanner BSC Testnet Payment Procedure]] | +| PAY-SCAN-002 | Scanner/backend/frontend token registry consistency for chain 97 | P0 | Smoke covered | [[Smoke and Regression Procedure]] | +| PAY-SCAN-003 | Wrong token contract does not confirm payment | P0 | Designed, needs automated negative test | [[Scanner BSC Testnet Payment Procedure#Negative scenarios]] | +| PAY-SCAN-004 | Underpayment does not confirm payment | P0 | Designed, needs automated negative test | [[Scanner BSC Testnet Payment Procedure#Negative scenarios]] | +| PAY-SCAN-005 | Wrong destination does not confirm payment | P0 | Designed, needs automated negative test | [[Scanner BSC Testnet Payment Procedure#Negative scenarios]] | +| DELIVERY-001 | Seller delivery advances request to `delivery` | P0 | Live tested on dev | [[Escrow Marketplace E2E Procedure]] | +| DELIVERY-002 | Buyer delivery confirmation advances request to `delivered` | P0 | Live tested after `2.8.117` id fix | [[Escrow Marketplace E2E Procedure]] | +| DELIVERY-003 | Non-buyer cannot confirm delivery | P0 | Designed, should be regression test | [[Testing Expansion Backlog]] | +| RELEASE-001 | Physical product enters grace period before release | P0 | Product policy not implemented | [[Testing Expansion Backlog]] | +| RELEASE-002 | Gift card/digital product releases immediately after proof/confirmation | P0 | Product policy not implemented | [[Testing Expansion Backlog]] | +| DISPUTE-001 | Buyer opens dispute before release | P0 | Backend incomplete / needs route alignment | [[Testing Expansion Backlog]] | +| DISPUTE-002 | Admin resolves dispute for seller and release path is unblocked | P0 | Not complete | [[Testing Expansion Backlog]] | +| DISPUTE-003 | Admin resolves dispute for buyer and refund path is unblocked | P0 | Not complete | [[Testing Expansion Backlog]] | +| CI-001 | Code push builds and deploys backend/frontend/scanner via Woodpecker | P0 | Live used | [[Smoke and Regression Procedure]] | +| UI-CHAIN-001 | Checkout shows BSC Testnet, tUSDT contract, and testnet explorer links | P1 | Implemented in frontend `2.8.118` | [[Scanner BSC Testnet Payment Procedure]] | +| AUTH-001 | Admin-created generated users can log in and execute role actions | P0 | Live used | [[Escrow Marketplace E2E Procedure]] | +| CLEANUP-001 | Test users/requests can be identified and excluded from reports | P2 | Designed | [[Test Environment and Data]] | + +## Core Escrow Scenario + +```mermaid +flowchart LR + A["Create buyer and sellers"] --> B["Buyer creates purchase request"] + B --> C["Sellers submit bids"] + C --> D["Buyer accepts one bid"] + D --> E["Buyer pays tUSDT on BSC Testnet"] + E --> F["Scanner confirms payment"] + F --> G["Seller delivers"] + G --> H["Buyer confirms delivery"] + H --> I["Policy boundary: grace, release, or dispute"] +``` + +## Payment Negative Scenario Families + +| Family | What to mutate | Expected result | +|---|---|---| +| Wrong token | Pay old BSC Testnet USDT or USDC instead of canonical tUSDT | Scanner does not mark intended payment paid. | +| Wrong chain | Pay on chain `56` or another EVM chain | Scanner watch for chain `97` remains pending. | +| Wrong amount | Send less than expected base-unit amount | Direct-balance delta below threshold, no paid transition. | +| Wrong destination | Send correct token/amount to another address | Intended destination delta unchanged, no paid transition. | +| Duplicate payment | Send twice to same destination after paid | First payment confirms; second must not double-credit escrow ledger. | +| Late payment | Pay after expiration/cancellation | Payment should not auto-credit an inactive intent without explicit recovery. | + +## Release Policy Scenario Families + +These are not implemented yet, but they define the test shape we need before +shipping fund release automation. + +| Product type | Expected policy | +|---|---| +| Physical product | Delivery proof starts a grace period. Funds release only after buyer confirmation, no dispute, or grace expiry. | +| Gift card | Delivery should require immediate proof and release funds immediately or near-immediately after buyer acceptance, depending on final policy. | +| Digital file/license | Same as gift card unless manual review is required. | +| Service | May need milestone acceptance and dispute window. | + +## Scenario Completion Criteria + +A scenario is complete when all are true: + +1. It has a written procedure. +2. It has deterministic test data setup. +3. It captures expected API statuses and DB/business states. +4. It has at least one automated test or smoke script where practical. +5. It has a documented live-dev verification result. +6. It names residual risk or product gaps. + diff --git a/11 - Testing/Testing Expansion Backlog.md b/11 - Testing/Testing Expansion Backlog.md new file mode 100644 index 0000000..004e889 --- /dev/null +++ b/11 - Testing/Testing Expansion Backlog.md @@ -0,0 +1,145 @@ +--- +title: Testing Expansion Backlog +tags: [testing, backlog, qa, release] +created: 2026-06-06 +--- + +# Testing Expansion Backlog + +This is the testing backlog to complete before expanding the escrow test suite +or claiming release confidence. + +## P0 - Product Policy Gaps + +### Physical product grace period + +Need implementation and tests for: + +- seller marks delivery; +- buyer receives delivery window; +- grace period starts; +- buyer can confirm delivery before expiry; +- buyer can dispute before expiry; +- funds release only after buyer confirmation, no dispute, or grace expiry. + +Acceptance tests: + +| ID | Expected | +|---|---| +| RELEASE-PHYS-001 | Physical delivery starts hold/grace timer. | +| RELEASE-PHYS-002 | Buyer confirmation before expiry makes funds releasable. | +| RELEASE-PHYS-003 | Dispute before expiry blocks release. | +| RELEASE-PHYS-004 | Grace expiry without dispute makes funds releasable. | + +### Immediate release for gift cards/digital goods + +Need implementation and tests for: + +- product type is gift card or digital; +- seller proof is required immediately; +- buyer acceptance or product policy triggers immediate/near-immediate release; +- dispute path can still stop release if policy includes a short challenge window. + +Acceptance tests: + +| ID | Expected | +|---|---| +| RELEASE-DIGI-001 | Gift card delivery does not use physical-product grace period. | +| RELEASE-DIGI-002 | Gift card proof advances to releasable immediately after buyer acceptance. | +| RELEASE-DIGI-003 | Wrong/missing proof blocks release. | + +## P0 - Dispute Coverage + +The dispute mechanism is not complete enough for end-to-end fund movement. + +Tests needed: + +| ID | Scenario | Expected | +|---|---|---| +| DISPUTE-001 | Buyer opens dispute after seller delivery, before release | payment/request enters dispute hold | +| DISPUTE-002 | Seller cannot force release while dispute is open | release attempt rejected | +| DISPUTE-003 | Admin resolves for seller | release becomes available | +| DISPUTE-004 | Admin resolves for buyer | refund becomes available | +| DISPUTE-005 | Duplicate dispute resolution | idempotent or rejected safely | +| DISPUTE-006 | Dashboard dispute route vs release-hold route | no route shadowing ambiguity | + +## P0 - Payment Negative Tests + +Automate: + +- wrong token; +- wrong chain; +- wrong destination; +- underpayment; +- duplicate payment; +- late payment after cancelled/expired intent; +- payment with no gas; +- scanner unavailable during payment; +- scanner webhook signature invalid; +- balance check baseline missing or stale. + +## P0 - Authorization and ID Boundaries + +Add regression tests for cross-store id comparisons: + +| Route/action | Required test | +|---|---| +| buyer delivery confirmation | buyer can confirm even when session id and request buyer id use different stores | +| buyer delivery confirmation | non-buyer cannot confirm | +| seller delivery update | only selected seller/admin can deliver | +| offer acceptance | only buyer/admin can accept | +| payment check | only buyer/admin/system can advance payment where applicable | + +## P1 - UI/Browser E2E + +Add Playwright tests for: + +- checkout renders BSC Testnet chain label; +- token contract row shows canonical tUSDT; +- testnet explorer links are generated correctly; +- wrong wallet chain shows switch button; +- insufficient balance warning appears; +- payment submitted screen waits for scanner confirmation; +- paid socket/poll fallback transitions to success. + +## P1 - CI and Deployment + +Add a deployment smoke checklist artifact after every pipeline: + +- backend version endpoint; +- frontend root 200; +- scanner `/health`; +- chain 97 token balance check; +- current Docker image digests; +- last commit SHA per service. + +## P1 - Test Data Lifecycle + +Need cleanup strategy: + +- flag generated users with run id; +- archive or tag generated purchase requests; +- prevent test data from polluting analytics; +- define whether test tx/payment rows are permanent audit evidence or can be purged. + +## P2 - Observability + +Add dashboards/log queries for: + +- scanner intent lifecycle; +- balance-check deltas; +- payment state transitions; +- delivery status changes; +- dispute holds; +- release/refund attempts. + +## Suggested Next Automation Order + +1. Convert the two-round BSC Testnet E2E procedure into a committed smoke script. +2. Add non-buyer delivery confirmation regression test. +3. Add scanner negative tests for wrong token and underpayment. +4. Implement physical vs digital release policy. +5. Add release-policy tests. +6. Resolve dispute route/policy gaps. +7. Add dispute-to-release/refund E2E tests. + diff --git a/11 - Testing/Testing Overview.md b/11 - Testing/Testing Overview.md new file mode 100644 index 0000000..e64a4ec --- /dev/null +++ b/11 - Testing/Testing Overview.md @@ -0,0 +1,73 @@ +--- +title: Testing Overview +tags: [testing, qa, e2e, smoke] +created: 2026-06-06 +--- + +# Testing Overview + +This section is the home for Amanat test procedures and designed test scenarios. +It complements [[07 - Development/Testing]], which documents the test runners and +repository-level commands. + +Use this section when planning or executing end-to-end validation across buyer, +seller, payment scanner, delivery, payout, dispute, and deployment behavior. + +## Documents + +| Document | Purpose | +|---|---| +| [[Test Environment and Data]] | Environments, accounts, wallets, tokens, and secret-handling rules. | +| [[Test Scenario Catalog]] | Canonical scenarios we have designed or need to extend. | +| [[Escrow Marketplace E2E Procedure]] | Buyer/seller/request/bid/delivery procedure, including the current two-round flow. | +| [[Scanner BSC Testnet Payment Procedure]] | BSC Testnet tUSDT scanner payment procedure and failure modes. | +| [[Smoke and Regression Procedure]] | CLI, CI, and post-deploy smoke checks. | +| [[Testing Expansion Backlog]] | Gaps to cover before broader release confidence. | + +## Test Layers + +| Layer | Goal | Primary owner | +|---|---|---| +| Unit tests | Validate isolated services, state machines, utilities, components. | Backend/frontend/scanner repos | +| Integration tests | Validate repository adapters, payment orchestration, webhooks, auth, marketplace APIs. | Backend/frontend repos | +| Smoke tests | Fast checks for one deployment target, usually via `BASE_URL`. | Backend scripts | +| Browser E2E | Validate user-visible web flows. | Frontend Playwright | +| Live dev E2E | Validate real dev deployment, CI image, scanner service, BSC Testnet, and test tokens. | QA/operator | +| UAT | Validate product scenarios and acceptance criteria. | Product + QA | + +## Golden Path Coverage + +The minimum live-dev confidence path is: + +1. Admin creates one buyer and at least two sellers. +2. Buyer creates a request with a bounded USDT budget. +3. Each seller submits a bid inside the budget with different amount and delivery timing. +4. Buyer accepts one bid. +5. Buyer funds escrow with BSC Testnet tUSDT. +6. Scanner confirms the token transfer. +7. Seller delivers. +8. Buyer confirms delivery. +9. Flow pauses at the current product-policy boundary: release/grace/dispute automation is not complete. + +The current live tested version of this path is documented in +[[Escrow Marketplace E2E Procedure#Reference execution - 2026-06-06]]. + +## Definitions + +| Term | Meaning | +|---|---| +| Dev deployment | `https://dev.amn.gg`, backed by the dev Docker stack on the deployment host. | +| Scanner | Separate in-house AMN scanner service that verifies token payments. | +| Direct-balance rail | Scanner payment mode where balance deltas on a destination address confirm payment. | +| BSC Testnet tUSDT | Test ERC-20 used for dev payments: `0x109F54Dab34426D5477986b0460aE5dFBA65f022`. | +| Grace period | Product-policy delay after delivery before automatic fund release. Not implemented yet. | +| Immediate release | Product-policy mode for digital goods such as gift cards. Not implemented yet. | + +## Rules + +- Never commit seed phrases, private keys, admin passwords, CI tokens, or `.env` files. +- Use generated test users with unique run IDs. Do not reuse personal accounts for destructive scenarios. +- Record enough evidence to reproduce a failure: request id, offer id, payment id, tx hash, chain id, token address, HTTP status, and CI build number. +- Treat a passing local test as necessary but not sufficient for scanner/payment work. Payment changes must also be verified against dev after deploy. +- Every live-dev test should state what remains untested or blocked. +