End-to-end test framework for decentralized application (dApp) interactions using Playwright and Synpress (MetaMask automation).
| Suite | Tests | What It Covers |
|---|---|---|
| Wallet Connection | 8 | Connect, disconnect, reject, network switch, page refresh persistence |
| Network Switching | 7 | Switch networks, reject switch, balance update, wrong network, rapid switching |
| Token Transfer | 6 | Send ETH, reject tx, invalid address, zero amount, insufficient balance, on-chain verification |
| NFT Mint | 5 | Mint, gallery update, reject, on-chain ownership, disabled state |
| Token Swap | 6 | Swap execution, reject, price impact, zero amount, insufficient balance, ERC-20 approval flow |
E2E: 32 test cases (+ 2 unit tests for MetaMaskHelper parsing) — 34 total
flowchart TB
subgraph Automation["Automation"]
PW["Playwright runner"]
Fixtures["Custom fixtures<br/>(dapp + metamask)"]
POM["Page Objects<br/>(DAppPage)"]
MM["MetaMask helper<br/>(Synpress)"]
Chain["ethers.js<br/>(on-chain verification)"]
Env["Env vars / secrets<br/>SEED_PHRASE + WALLET_PASSWORD<br/>DAPP_URL + RPC_URL"]
Env --> PW
Env --> MM
PW --> Fixtures
Fixtures --> POM
Fixtures --> MM
PW --> Chain
end
subgraph Browser["Chromium"]
UI["dApp UI"]
Ext["MetaMask extension"]
end
PW -->|drives| Browser
POM --> UI
MM --> Ext
RPC["RPC endpoint / testnet"]
UI -->|JSON-RPC| RPC
Chain -->|JSON-RPC queries| RPC
PW --> Artifacts["Artifacts<br/>playwright-report/"]
dapp-e2e-tests/
├── src/
│ ├── pages/
│ │ ├── BasePage.ts # Base page object with shared methods
│ │ ├── DAppPage.ts # dApp UI interactions (POM pattern)
│ │ └── MetaMaskHelper.ts # MetaMask popup automation + transaction detail extraction
│ ├── fixtures/
│ │ └── dapp.fixture.ts # Custom Playwright fixtures
│ └── utils/
│ └── blockchain.ts # On-chain verification helpers (ethers.js)
├── tests/
│ ├── metamask-helper.spec.ts # MetaMask helper unit tests (transaction detail parsing)
│ ├── wallet-connect.spec.ts # Wallet connection tests
│ ├── network-switch.spec.ts # Network switching tests
│ ├── token-transfer.spec.ts # ETH transfer tests
│ ├── nft-mint.spec.ts # NFT minting tests
│ └── swap.spec.ts # Token swap tests
├── playwright.config.ts # Playwright configuration
└── .github/workflows/e2e.yml # CI pipeline
- Page Object Model (POM) — UI interactions encapsulated in reusable page classes
- Custom Fixtures — Playwright fixtures for DAppPage and MetaMaskHelper injection
- On-Chain Verification — Tests verify blockchain state using ethers.js, not just UI assertions
- Separation of Concerns — UI testing, wallet automation, and chain queries are isolated
| Tool | Purpose |
|---|---|
| Playwright | Browser automation and test runner |
| Synpress | MetaMask wallet automation |
| ethers.js | On-chain state verification |
| TypeScript | Type-safe test code |
| GitHub Actions | CI/CD pipeline |
# Install dependencies
npm install
# Install Playwright browsers
npx playwright install --with-deps chromium
# Copy environment config
cp .env.example .env
# Edit .env with your test wallet and contract addresses# Run all tests
npm test# Run tagged suites
npm run test:smoke
npm run test:onchain
# Run with browser visible
npm run test:headed
# Run specific suite
npm run test:wallet
npm run test:transfer
npm run test:nft
npm run test:swap
# View HTML report
npm run report@smoke: fast sanity checks for CI / PRs@onchain: tests with explicit RPC reads (requires stableRPC_URLand deployed contracts where applicable)@manual: requires a manual precondition (test willskipif not satisfied)
| Variable | Description |
|---|---|
DAPP_URL | dApp frontend URL |
RPC_URL | Ethereum RPC endpoint (Sepolia) |
SEED_PHRASE | Test wallet seed phrase (never use real funds) |
WALLET_PASSWORD | MetaMask password for test wallet |
CHAIN_ID | Target chain ID (11155111 = Sepolia) |
TOKEN_CONTRACT | ERC-20 token contract address |
NFT_CONTRACT | ERC-721 NFT contract address |
On every push / PR to main, GitHub Actions runs lightweight checks that are safe for public CI:
- Type Check & Unit Tests —
tsc --noEmit+ MetaMask helper unit tests (no secrets required) - Structure Check — Ensures critical framework files exist
The workflow badge reflects these push/PR checks. The full Playwright E2E suite (wallet + on-chain flows) is available via workflow_dispatch once you configure repository secrets SEED_PHRASE and WALLET_PASSWORD, and provide a reachable DAPP_URL.
MIT