| name | frontend-testing |
| description | Test frontend changes end-to-end and deploy to staging for verification. Use when testing frontend PRs, verifying frontend migrations, testing UI changes, or when the user asks to test the frontend before production. Covers automated checks, local dev server testing, staging deployment, and browser-based verification. |
Frontend Testing
Full testing workflow for frontend changes. The agent runs automated checks and local dev server tests (Phases 1–2), then hands off deployment to the human (Phase 3), and finally verifies the deployed app via the browser MCP (Phase 4).
Phase 1: Automated Checks
Run from the repo root:
npm run lint
npm run build-frontend
npm run build-cli-releases
All must pass before proceeding. Fix any failures introduced by the frontend changes.
Phase 2: Local Dev Server Testing
Kill anything on ports 3000/3001 to avoid conflicts:
lsof -ti:3000,3001 | xargs kill -9 2>/dev/null; echo "ports cleared"
Start the main frontend dev server (from repo root):
cd frontend && DFX_NETWORK=ic npx vite --port 3000
Start the cli-releases frontend (from repo root, in a separate terminal):
cd cli-releases/frontend && npx vite preview --port 3001
What to check
- No runtime errors in the Vite terminal output — look for
[vite] (client) error lines. Warnings (unused CSS selectors, a11y hints) are acceptable.
- HTML shell serves —
curl -s http://localhost:3000/ returns HTML with <div id="root">. Same for http://localhost:3001/.
- SPA routes serve —
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/core returns 200.
Do NOT use the browser MCP on localhost — the embedded browser shows a blank page for this SPA on the Vite dev server. Browser-based verification happens in Phase 4 against the deployed staging build.
Kill the dev servers after checks pass.
Phase 3: Deploy to Staging (Human)
This phase must be run by the human in their terminal. The agent cannot reliably run dfx deploy due to a ColorOutOfRange TTY panic in dfx v0.29.1 within Cursor's shell, and potential macOS keychain prompts for identity access.
Print the following instructions for the human and wait for confirmation before proceeding to Phase 4.
Instructions for the human
Deploy the frontend to the staging assets canister.
Prerequisites:
dfx installed via dfxvmdfx identity with controller access to staging canisters (e.g. mops)- Dependencies installed (
npm install in repo root)
Important: dfxvm automatically uses the dfx version pinned in dfx.json. Do NOT run dfxvm update, dfxvm install, or dfxvm default to "fix" the version — this is correct behavior.
Run from the repo root:
dfx deploy assets --network staging -y
After deployment, tell the agent to continue with Phase 4 verification.
Phase 4: Verify Staging Deploy
The staging URL is: https://ogp6e-diaaa-aaaam-qajta-cai.icp0.io
This phase can be done by the agent (via browser MCP), the human (manually), or both.
Agent verification (browser MCP)
Use user-browsermcp to verify the deployed build:
- Navigate to the staging URL, wait 5s, take a snapshot
- Check package count — "Total packages" must show a non-zero number and packages should be listed on the homepage.
- Click into a package — verify tabs render: Code, Docs, Readme, Versions, Dependencies, Dependents, Tests, Benchmarks
- Check
browser_console_messages — no process is not defined or Package not found errors. Invalid asm.js warnings are pre-existing and acceptable.
- Navigate back to homepage — verify layout, fonts, and styling look correct
Human verification
Give the human the staging link and ask them to visually compare with production:
Key things to check: fonts, button styles, layout, package detail pages, search.
Troubleshooting
- Page blank or doesn't load: Check
dfx canister status assets --network staging for cycle balance.
Package not found errors: The ic-mops npm package may be querying the wrong backend. Ensure the code has window.MOPS_NETWORK set to "ic" for non-local deployments (see frontend/components/package/Package.svelte).
