Spec Playbooks
Each spec in dapp/e2e/playwright focuses on a concrete user journey. This page summarises what they cover, which helpers they rely on, and any prerequisites.
High-level scenarios
| Spec | What it verifies | Notable helpers & mocks | Notes |
|---|---|---|---|
smoke.spec.ts | Public pages load (/, /mint, /portfolio, /terms, /privacy, /gate, /swap). Checks header, wallet bar, <title>, canonical links, JSON-LD count, and absence of page errors. | Native Playwright assertions only. | Runs in parallel mode. Use as a quick regression before deeper flows. |
wallet.spec.ts | Wallet connection UX: connect, persist through reload, cancel modal via ESC, disconnect, preview WalletConnect QR, reconnect via preview. | setupTest, WalletTestUtils, wallet flows (ensureConnected, reconnectAfterReload, etc.). | Skips the QR preview on mobile widths. Great reference when debugging connect-modals. |
swap-widget.spec.ts | Ensures the embedded swap widget mirrors the site-wide wallet state (connect/disconnect from either surface, reload persistence). | waitForWidgetReady, wallet flows, persistConnection: true setup. | Confirms the widget uses the shared modal instead of a bespoke flow. |
portfolio-assets.spec.ts | Portfolio page renders ERC-20/721/1155 data for Ethereum and shows empty states on Polygon. | installPortfolioAlchemyMock, portfolio flows (selectNetworks, expectGridRows, etc.). | Dataset lives inline in the spec. Update it when UI expectations change. |
hp-mint-burn.spec.ts | Happy path real mint + burn on Sepolia. | setupTest (real mode), ensureConnected, burnIfKeyPresent, mintKey, burnKey. | Requires funded Sepolia account. Emits wallet bridge logs for post-mortems. |
hp-tokengate.spec.ts | Full experience: mint NFT → gate unlock → play secret song → AI chat (MCP + inline renderers) → submit Msg Rito → burn NFT. | installAIMock with composed handlers, all flows from NFT/chat/music/gate/form, burnIfKeyPresent. | Serialised (
|
Writing new specs
- Import from the barrel —
import { setupTest, installAIMock, mintKey, ... } from '../utils';keeps imports tidy. - Log the environment once —
logE2eEnvOnce()provides immediate visibility into which key/network the spec is using. - Prefer flows over custom selectors — if a UI element is missing from the helpers, add it there rather than inside the spec.
- Scope mocks per spec — attach AI or portfolio mocks inside the test body to avoid cross-test leakage.
- Leave breadcrumbs — the existing specs log significant milestones (
console.log('[Gate Unlock] success')). Follow the same pattern to ease debugging.
🧪
Specs that perform real transactions should live under test.describe.configure({ mode: ‘serial’ }) and clean up after themselves with burnIfKeyPresent to avoid exhausting the wallet balance.
Once your spec is wired, refer to the troubleshooting page for common failure modes and debugging tips.