# 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**
   ```bash
   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.:
   ```bash
   psql $DATABASE_URL -f ../../explorer-monorepo/backend/database/migrations/0011_token_aggregation_schema.up.sql
   # plus 0012 if used
   ```

4. **Run**
   ```bash
   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

```bash
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**
   ```bash
   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:

```bash
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)](TESTING_INSTRUCTIONS.md#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):

```bash
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
