nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: add testing procedures and scenario catalog

Browse Source
This commit is contained in:
Siavash Sameni
2026-06-06 10:35:47 +04:00
parent b3eea176d5
commit 9267961909
8 changed files with 1009 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

207
11 - Testing/Escrow Marketplace E2E Procedure.md Normal file
View File

@@ -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 <runId> R<round>",
"description": "Automated scanner payment test round <round>",
"productType": "physical_product",
"productLink": "https://example.test/e2e/<runId>/<round>",
"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": "<runId>",
"round": 1,
"note": "Seller delivery proof for automated dev test"
}
}
```
Buyer confirmation may use similar metadata:
```json
{
"proof": {
"type": "e2e-confirmation",
"runId": "<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.

180
11 - Testing/Scanner BSC Testnet Payment Procedure.md Normal file
View File

@@ -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` |

168
11 - Testing/Smoke and Regression Procedure.md Normal file
View File

@@ -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=<local secret>
```
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 <ssh-key> root@<dev-host> \
"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 - <short summary>
- 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.

142
11 - Testing/Test Environment and Data.md Normal file
View File

@@ -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-<YYYYMMDDHHMMSS>-buyer@example.test
amn-e2e-<YYYYMMDDHHMMSS>-seller1@example.test
amn-e2e-<YYYYMMDDHHMMSS>-seller2@example.test
amn-e2e-<YYYYMMDDHHMMSS>-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 |

91
11 - Testing/Test Scenario Catalog.md Normal file
View File

@@ -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.

145
11 - Testing/Testing Expansion Backlog.md Normal file
View File

@@ -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.

73
11 - Testing/Testing Overview.md Normal file
View File

@@ -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.