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.
Last updated on