Troubleshooting & Tips

Even with solid helpers, complex flows can fail for mundane reasons. Use this page as a checklist when debugging CI runs or local flakes.

Common issues

Environment

`.env.playwright` not found

Ensure the file lives inside dapp/.env.playwright. env.ts logs [e2e env] .env.playwright not found when both search paths fail.

Private key format errors

Run npx tsx dapp/e2e/playwright/debug-key.ts to see where normalization fails (invisible chars, stray quotes, incorrect length).

CHAIN_ID undefined

If you set NETWORK=Ritonet, CHAIN_ID becomes mandatory. env.ts throws with [e2e env] CHAIN_ID is required....

Wallet

Provider missing

Always await setup.waitForProvider() before interacting with the page. If wagmi initialises first, it won’t detect the injected provider.

Address mismatch

setupTest compares the derived address with walletConfig.address. When they differ, it throws before navigation. Fix the config instead of stubbing the error away.

State leaks between tests

Forgetting clearStorage: true or reusing the same page across tests can keep wagmi’s session alive. Use per-test setupTest() calls and call ensureDisconnected() in afterEach if needed.

Mocks & MCP

MCP call fails

The AI mock logs [AI Mock MCP] Tool call failed. Verify the JWT cookie exists and the MCP endpoint matches e2eEnv.mcpEndpoint. For authenticated tests, log in before sending chat messages.

Mock intercepts the wrong endpoint

If you see missing API responses elsewhere, ensure you didn’t change the allowlist in ai-provider.mock.ts. Never route-match **/api/** without the explicit /api/chat check.

Portfolio data missing

The chain-portfolio mock only responds when it finds tokenType and chainId query params. Confirm the page still sends those (selectors in portfolio.flow.ts assume they exist).

Gate & NFT

Gate unlock timeout

Increase waitForResponseMs/waitForUIVisibleMs or enable refreshOnFail. Also make sure no modals are blocking the button—unlockTokenGateWithRetry attempts to dismiss them but new UI could require updates.

Mint/Burn stuck

In real mode, check the Sepolia account balance and the RPC status. In mock mode, ensure txDelayMs isn’t set to something huge. Logs from wallet/injected/provider.ts show pending tx hashes.

Inline renderer assertions flake

Call smartChat(..., skipResponseCheck: true) when expecting non-text output and then use the dedicated assertion helpers. They already wait for SVG/GIF elements.

Debugging tips

Enable debug flags — Most helpers accept debug: true (e.g. installPortfolioAlchemyMock). Verbose logs are invaluable on CI.
Capture screenshots — ScreenshotUtils.capture('gate-error') stores before/after screenshots under test-results/screenshots.
Console filtering — setupTest pipes wallet-related console logs to the terminal. Add your own page.on('console') listeners for component-specific debugging.
Use test.step — Wrapping flows in test.step('Gate unlock', async () => { ... }) produces readable trace chunks in Playwright HTML reports.
Surface retries in logs — Helpers already log attempt counts. If you add new retries, follow the [Component] Attempt x/y format to stay consistent.

🪪

Never mask genuine backend failures with mocks. The existing mocks only bypass unreliable external data (AI + portfolio). Everything else should keep talking to the staging API so we notice regressions.

Still stuck? Cross-reference the spec playbook for the relevant test or inspect the Playwright trace (npx playwright show-trace trace.zip) to see DOM timing issues.