docs: add testing procedures and scenario catalog
This commit is contained in:
Siavash Sameni
207
11 - Testing/Escrow Marketplace E2E Procedure.md
Normal file
207
11 - Testing/Escrow Marketplace E2E Procedure.md
Normal 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.
|
||||
|
||||
Reference in New Issue
Block a user