Environment & Secrets

All Playwright specs read from dapp/e2e/playwright/env.ts. The file loads .env.playwright, validates it with Zod, derives the wallet address using viem, and exposes two exports:

e2eEnv — the normalized environment (network, chainId, RPC URL, wallet metadata, MCP endpoint).
walletConfigFromEnv — a subset tailored for setupTest() and the wallet flows.

If .env.playwright is missing, the suite falls back to process.env, but tests will fail unless the variables below are defined. The sample file dapp/.env.playwright.example now lists only these keys.

Required variables

Variable	Required?	Description
`PRIVATE_KEY`	Yes	Hex string (with or without 0x). `env.ts` trims quotes, removes zero-width chars, pads to 64 nibbles, and derives the wallet address.
`NETWORK`	No (defaults to Sepolia)	One of `Ethereum`, `Sepolia`, `Ritonet`. Used to infer `chainId` when custom network info is absent.
`CHAIN_ID`	Yes when `NETWORK=Ritonet`	Numeric ID. Optional for mainnet/Sepolia because defaults exist (1 / 11155111).
`RPC_URL`	No	Custom RPC endpoint for the wallet bridge. When omitted, `test-setup.ts` picks a public Sepolia node.
`TEST_BASE_URL`	No	Overrides the origin Playwright hits. Leave empty to use `playwright.config`’s default.
`WALLET_NAME`	No	Label shown inside wallet modals and logs. Defaults to MetaMask.
`TX_DELAY_MS`	No	Upper-bounded (60s) delay that the mock wallet uses before mining synthetic transactions.
`MCP_ENDPOINT`	No (defaults to `/api/mcp`)	AI MCP endpoint. AI mocks respect this allowlist so real MCP requests are never intercepted.

`.env.playwright` workflow

1. Copy the sample

Duplicate .env.playwright.example (or create a fresh file) and fill in the variables above. Keep it outside version control.

2. Normalize the key (optional but recommended)

Run npx tsx dapp/e2e/playwright/debug-key.ts. The script logs each normalization step and confirms the derived address. Fix any errors before running tests.

3. Verify load paths

env.ts searches dapp/.env.playwright first, then the cwd. Confirm the file lives in the dapp root or exported environment variables are set during pnpm test:e2e.

4. Inspect the runtime log

Specs usually call logE2eEnvOnce() (env.ts:205). The console output confirms the network, chain, wallet name, derived address, tx delay, and MCP endpoint. Treat it as a quick sanity check.


# .env.playwright
PRIVATE_KEY="0xfeed...beef"
NETWORK=Sepolia
CHAIN_ID=11155111 # Optional unless NETWORK=Ritonet
RPC_URL=https://rpc.sepolia.org
TEST_BASE_URL=https://preview.ritoswap.com
WALLET_NAME=Test Wallet
TX_DELAY_MS=2500
MCP_ENDPOINT=/api/mcp

☁️

The CI workflow (.github/workflows/playwright-e2e.yml) injects the same variables via secrets:
PRIVATE_KEY comes from secrets.PRIVATE_KEY_PLAYWRIGHT, while TEST_BASE_URL and BASE_URL are pulled from repository/environment variables. Keep the sample file in sync so local runs mirror CI.

Address safety checks

env.ts derives the address via privateKeyToAccount. If the provided address in walletConfig mismatches the derivation, test-setup.ts:120-131 throws before any page interaction.
wallet/test-setup.ts exposes an explicit bridge for RPC, transactions, signMessage, and signTypedData. Real mode only begins when privateKey passes the validation above.

🧪

Use a throwaway Sepolia key. The real-mode specs mint and burn NFTs on-chain (hp-mint-burn.spec.ts, hp-tokengate.spec.ts).

Armed with a valid .env.playwright, you can now focus on the wallet harness that injects those credentials into the browser context.