nick-doc/11 - Testing/Escrow Marketplace E2E Procedure.md

title, tags, created

title	tags	created
Escrow Marketplace E2E Procedure	testing e2e escrow marketplace buyer seller	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.
• Notification checks are enabled in the runner. See Notification Assertion Procedure.

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. Assert initial notification baselines for buyer and sellers.
4. Buyer creates purchase request with a min/max USDT budget.
5. Assert purchase-request notifications for expected sellers.
6. Sellers submit bids inside the budget range.
7. After each seller bid, assert offer notifications for the buyer.
8. Randomize or vary:
   • bid amount,
   • delivery timing,
   • seller note,
   • delivery method.
9. Buyer selects a bid.
10. Assert offer-accepted notification for selected seller and offer-rejected/updated notifications for non-selected sellers when implemented.
11. Backend creates scanner payment intent.
12. Assert payment-pending or payment-started notification where implemented; if missing, record as notification coverage gap.
13. Buyer pays with BSC Testnet tUSDT.
14. Scanner confirms the payment.
15. Assert payment-confirmed notifications for buyer and selected seller.
16. Seller marks delivery.
17. Assert delivery notification for buyer.
18. Buyer confirms delivery.
19. Assert delivery-confirmed notification for selected seller and buyer status notification if implemented.
20. 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

Notification Assertions After Every Step

Notification verification is mandatory after every state-changing step. A step is not complete until the test runner has either:

1. observed the expected notification for every recipient; or
2. recorded a known coverage gap with route/action, expected recipient, and linked issue/backlog item.

Use Notification Assertion Procedure for the exact API/socket checks.

Step	Expected recipients	Required notification assertion
Baseline after user creation	buyer, every seller	Capture unread count and latest notification id for each actor before business mutations.
Buyer creates request	eligible sellers	Sellers receive a request/new-opportunity notification, or the gap is recorded.
Seller submits bid	buyer	Buyer receives a new-offer notification with relatedId or action URL pointing to the request/offer.
Buyer selects bid	selected seller; non-selected sellers if rejection notices are implemented	Selected seller receives acceptance notification. Non-selected sellers receive rejection/update notification where supported.
Payment intent created	buyer	Buyer receives payment-started/pending notification where supported. Missing pending_payment coverage is a known notification gap and must be recorded.
Scanner confirms payment	buyer, selected seller	Buyer and seller receive payment-confirmed/funded notification.
Seller marks delivery	buyer	Buyer receives delivery/proof submitted notification.
Buyer confirms delivery	selected seller; buyer if status-change notices are implemented	Seller receives delivery-confirmed notification.
Dispute raised, when added	buyer, seller, admin/mediator	All parties receive dispute-created/hold notification.
Release/refund, when added	buyer, seller, admin	Funds movement notification is persisted and pushed.

Minimum notification evidence per assertion:

Evidence	Source
unread count before and after	GET /api/notifications/unread-count
latest notification payload	GET /api/notifications?limit=5
recipient id/email	authenticated actor profile or test user record
notification category/type/title/actionUrl	notification payload
socket event, if runner supports it	new-notification on user-<userId>
elapsed time from action to notification visibility	runner timestamp

Buyer Request Template

Use unique values so live data can be filtered later:

{
  "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:

{
  "proof": {
    "type": "e2e",
    "runId": "<runId>",
    "round": 1,
    "note": "Seller delivery proof for automated dev test"
  }
}

Buyer confirmation may use similar metadata:

{
  "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
Notification assertion executed after each state-changing step	yes
Notification gaps are recorded with expected recipient and route/action	yes

Reference Execution - 2026-06-06

Run id:

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.