metamask-integration/chain138-snap/E2E_PREPARATION.md

E2E Preparation — Token-Aggregation and Companion Site

Complete these steps so that full end-to-end testing (market data, bridge routes, swap quotes) succeeds.

---

1. Token-aggregation service

The Snap and companion site call the token-aggregation API for networks, token list, bridge routes, and swap quotes. You need the service running and reachable.

Option A: Local (recommended for E2E)

1. Prerequisites

   • Node.js 20+
   • PostgreSQL 14+ with TimescaleDB
   • RPC URLs for Chain 138 and 651940 (e.g. from .env.example)

2. Setup

   cd smom-dbis-138/services/token-aggregation
   cp .env.example .env
   # Edit .env: set DATABASE_URL, CHAIN_138_RPC_URL, CHAIN_651940_RPC_URL
   

3. Database

   • Apply migrations (see QUICK_START.md or QUICK_START_COMPLETE.md in that repo), e.g.:

   psql $DATABASE_URL -f ../../explorer-monorepo/backend/database/migrations/0011_token_aggregation_schema.up.sql
   # plus 0012 if used
   

4. Run

   npm install
   npm run build
   npm run dev
   

   Service will listen on http://localhost:3000.
   Verify: curl http://localhost:3000/health and curl http://localhost:3000/api/v1/networks.

Option B: Docker

cd smom-dbis-138/services/token-aggregation
# Ensure .env exists with DATABASE_URL etc.
docker-compose up -d
# API on http://localhost:3000

Option C: Deployed / staging

Use your deployed token-aggregation base URL (e.g. https://your-token-aggregation-api.com). Ensure CORS allows the Snap/site origin and the endpoints below respond:

• GET /api/v1/networks
• GET /api/v1/report/token-list
• GET /api/v1/bridge/routes
• GET /api/v1/quote
• GET /api/v1/tokens (for market summary)

---

2. Companion site environment

The companion site passes apiBaseUrl to the Snap so that market data, bridge, and swap quote cards work.

1. Create env file

   cd metamask-integration/chain138-snap/packages/site
   cp .env.production.dist .env
   # or .env.production for production build
   

2. Set API base URL

   • Local token-aggregation: GATSBY_SNAP_API_BASE_URL=http://localhost:3000
   • Deployed: GATSBY_SNAP_API_BASE_URL=https://your-token-aggregation-api.com
     Do not add a trailing slash.

3. Restart the site if it is already running so the variable is picked up (Gatsby reads env at build/start).

---

3. Run Snap + site

From the Chain 138 Snap monorepo root:

cd metamask-integration/chain138-snap
pnpm run start

• Site and Snap are served at http://localhost:8000.
• Open that URL in a browser where MetaMask Flask is installed.

---

4. Manual E2E checklist

Use the E2E testing checklist (MetaMask Flask) in TESTING_INSTRUCTIONS.md and complete every item (environment, install Snap, RPC methods, companion site cards).

---

5. Optional: automated E2E (Playwright)

To run the automated E2E tests (site loads and shows Snap Connect UI):

cd metamask-integration/chain138-snap
pnpm install
npx playwright install
pnpm run test:e2e

• First time: run npx playwright install to install browser binaries.
• test:e2e starts the dev server if needed and runs Playwright against http://localhost:8000.
• The site must compile successfully for E2E to pass (if Gatsby fails to build, fix the dev environment first).
• It does not drive MetaMask Flask; for full install/connect flow you must run the manual checklist.
• Optional: pnpm run test:e2e:ui to open the Playwright UI.

---

6. Run E2E against deployed Snap site

To run Playwright (or manual checks) against the deployed Snap site (e.g. https://explorer.d-bis.org/snap/):

1. Playwright against a URL: Set the base URL and run tests (if your Playwright config supports it), e.g.:

   • Add a second config or override in playwright.config.ts: baseURL: process.env.SNAP_BASE_URL || 'http://localhost:8000'.
   • Run: SNAP_BASE_URL=https://explorer.d-bis.org/snap pnpm run test:e2e (after adding baseURL to the config).
   • Or run the manual E2E checklist in TESTING_INSTRUCTIONS.md while opening https://explorer.d-bis.org/snap/ in the browser.

2. Environment: The deployed site must be built with GATSBY_SNAP_API_BASE_URL set to the production token-aggregation URL for Market, Bridge, and Swap cards to work. If not set, those cards will show "Set GATSBY_SNAP_API_BASE_URL".

3. CI: You can run scripts/verify-snap-site-vmid5000.sh https://explorer.d-bis.org in CI as a smoke test after deploy (no MetaMask required). Set repo variable SNAP_VERIFY_BASE_URL to enable the verify step in .github/workflows/deploy-snap-site.yml.

---

Last updated: 2026-02-11