/ui-visual-debugging

UI Visual Debugging

Core Rules

• Use a browser-controlled or headless context for routine web UI checks. Do not open tabs in the user's existing browser unless explicitly asked.
• Save screenshots, traces, and throwaway Playwright scripts under .context/; do not commit them.
• Use Peekaboo only when the task needs the real macOS desktop, native windows, a visible browser session, or Accessibility tree inspection.
• For local startup details, use running-and-testing-locally as the source of truth.

Nango Targets

For most frontend work, run:

npm run dev:docker
npm run dev:watch
npm run dev:watch:web

npm run dev:watch and npm run dev:watch:web are long-running commands. Keep them in separate sessions and wait for the initial TypeScript build before browser testing.

Standard Screenshot Workflow

1. Start or reuse the relevant local services.

2. Capture a desktop baseline with a browser-controlled tool. If a Playwright MCP/browser tool is available, use it. Otherwise use headless Playwright without modifying repo dependencies:

   npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3000 .context/nango-webapp-desktop.png

   For Connect UI:

   npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3009 .context/nango-connect-desktop.png

   If Playwright reports that the Chromium executable is missing, install the browser cache without adding repo dependencies:

   npx playwright install chromium

3. Inspect screenshots with view_image, then edit the smallest relevant files.

4. Verify after edits:

   npm run ts-build

   For webapp-only visual work, cd packages/webapp && npm run build is also useful. For Connect UI, run npm run connect-ui:build.

5. Capture fresh desktop screenshots and compare them before finishing.

Headless Interaction

For clicks, form filling, authentication flows, or multi-step checks, create a temporary Playwright script in .context/, run it, and save screenshots there.

Use stable selectors and visible text where possible. Avoid relying on the user's browser state.

Common flows:

• Dashboard sign-in/sign-up at http://localhost:3000.
• Dashboard pages after authentication: Integrations, Connections, Logs, Metrics, and Environment settings.
• Connect UI at http://localhost:3009.

When auth is needed, follow the local credentials and verification-log workflow in running-and-testing-locally.

Startup Troubleshooting

If server startup fails with a Knex error like The migration directory is corrupt, the following files are missing, the local database has migrations from another branch (see Migration mismatch in running-and-testing-locally to tell a branch behind master from an unmerged one). Do not reset the user's database without confirmation. For visual validation only, use a temporary database:

docker exec nango-db psql -U nango -d postgres -c "DROP DATABASE IF EXISTS nango_ui_skill_validation WITH (FORCE)"
docker exec nango-db psql -U nango -d postgres -c "CREATE DATABASE nango_ui_skill_validation"
NANGO_DB_NAME=nango_ui_skill_validation npm run dev:watch:web

After stopping the dev server, clean up the temporary database:

docker exec nango-db psql -U nango -d postgres -c "DROP DATABASE IF EXISTS nango_ui_skill_validation WITH (FORCE)"

Peekaboo Workflow

Use Peekaboo only after checking permissions:

peekaboo permissions status

Required:

Screen Recording (Required): Granted
Accessibility (Required): Granted

Prefer targeted captures by window id. Capturing by app name can hang.

peekaboo list windows --app "Google Chrome" --json
peekaboo image --mode window --window-id <window_id> --retina --path .context/nango-window.png --json-output
peekaboo see --app "Google Chrome" --json-output

Avoid peekaboo open http://... --app "Google Chrome" for routine checks because it creates tabs in the user's existing browser.

Review Checklist

• Baseline screenshot captured before UI edits when layout risk is meaningful.
• Desktop screenshots captured after edits.
• Screenshots, traces, and throwaway scripts stay under .context/.
• Browser automation does not depend on the user's existing browser state.
• npm run ts-build or the relevant package build was run after frontend changes.