Playwright E2E Test Suite

The /dapp/e2e/playwright workspace owns every end-to-end test that runs inside the hosted dapp and docs sites. It is designed to do three things well:

Exercise real user journeys — minting, token-gated flows, AI chat, portfolio views, swap widget syncing, and the core marketing pages.
Mock only what we control — private keys, AI backends, and on-chain portfolio data can be stubbed or forwarded deterministically.
Document every assumption — the helpers read environment variables, inject a custom wallet provider, and expose low-level diagnostics so failures are debuggable.

🧭

This section covers the Playwright-specific tooling only. Broader QA guidance still lives under dapp/testing.

Directory Tour

- env.ts
- debug-key.ts
- - index.ts
- wallet.spec.ts
- hp-tokengate.spec.ts
- hp-mint-burn.spec.ts
- portfolio-assets.spec.ts
- swap-widget.spec.ts
- smoke.spec.ts

The docs/content/dapp/playwright directory mirrors this hierarchy and explains each layer in depth. Jump to the page that matches what you are editing: environment, wallet harness, mocks, flows, or spec playbooks.

Test Lifecycle

Every spec follows the same lifecycle, regardless of what it validates:

1. Load environment + wallet config

env.ts loads .env.playwright, normalises the private key, derives the account, and hands the wallet config to wallet/test-setup.ts.

2. Bootstrap the page

setupTest() clears storage (or preserves it if persistConnection is true), injects the mocked/real provider bundle, exposes Node-side signing bridges, and listens for console errors.

3. Attach mocks & flows

Specs optionally install AI or portfolio mocks, then re-use flows/helpers (wallet, NFT, chat, gate, music) so selectors and retries stay consistent across scenarios.

4. Assert the user journey

Each spec focuses on user-observable outcomes: buttons that flip states, rendered chat bubbles, music bars, gate unlocks, or on-chain balance changes. Logs from utils/mocks surface context on failure.

Picking a Mode

Mock mode

Mock mode is used when you omit a private key. The injected provider returns deterministic signatures, crafts synthetic receipts for mint/burn, and the AI + portfolio mocks intercept data calls. This is ideal for local dev or CI runs that should not touch Sepolia.

The remaining pages drill into the pieces referenced here. Start with Environment & Secrets if you need to wire up .env.playwright, then continue through the wallet harness, mocks, reusable flows, spec guides, and troubleshooting tips.