frontend-test

# Frontend Testing via Playwright MCP ## Step 0: Execution Mode (MANDATORY) Before doing ANY work, ask the user: > "Want me to delegate this to the **frontend-tester** agent (isolated, structured testing), or proceed inline in this chat?" - If user chooses agent → launch the **frontend-tester** agent with the target URL and context. STOP here — do not continue with the steps below. - If user chooses inline → proceed with the methodology below. - If user doesn't respond clearly → default to agent. --- Test a running application's frontend by navigating pages, interacting with UI elements, collecting errors, and generating a structured health report. All browser interaction happens via Playwright MCP tools — no manual browser needed. ## Prerequisites - The application must be running and accessible (localhost or remote URL) - Playwright MCP server must be connected (check with `/mcp`; the plugin's server is listed as `plugin:codemap-dev:playwright`) - Tool names: the plugin declares the `playwright` server itself, so the tools are named `mcp__plugin_codemap-dev_playwright__<tool>` (for example `mcp__plugin_codemap-dev_playwright__browser_snapshot`). This skill uses the short `browser_*` names - If the app requires authentication, ask the user for credentials before starting ## Step 1: Determine Target URL Resolve the application URL in this order: 1. **User provided URL** — use it directly (add `http://` if missing) 2. **Detect from project** — check `package.json` scripts for dev server port, `docker-compose.yml` for exposed ports, `.env` for `PORT` or `BASE_URL` variables 3. **Ask the user** — if nothing is detectable, ask for the URL Common patterns: - Next.js / React: `http://localhost:3000` - Flask / Django: `http://localhost:5000` or `http://localhost:8000` - Docker Compose: check `ports` mapping in `docker-compose.yml` - Admin panels: often at `/admin`, `/dashboard`, `/panel` ## Step 2: Discovery Phase Navigate to the app and map its structure. ### 2a. Initial Page Load 1. Use `browser_navigate` to open the target URL 2. Use `browser_snapshot` to get the accessibility tree of the landing page 3. Use `browser_console_messages` to check for immediate JavaScript errors 4. Use `browser_network_requests` to check for failed resource loads (4xx/5xx) ### 2b. Navigation Mapping From the accessibility tree, identify: - **Top-level navigation** — menus, navbars, sidebars, header links - **Page links** — all internal links discoverable from the current page - **Authentication state** — is the user logged in? Is there a login page? - **Key sections** — main content areas, footers, modals Build a page list by extracting links from the snapshot. Visit up to **10 unique pages** (prioritize distinct routes, not paginated variants). ### 2c. Page-by-Page Scan For each discovered page: 1. `browser_navigate` to the page URL 2. `browser_snapshot` to capture the accessibility tree 3. `browser_console_messages` to collect JS errors/warnings 4. `browser_network_requests` to check for failed API calls 5. Note the page title, main content structure, and any interactive elements (forms, buttons, tables) Record findings per page: - **URL and title** - **Key elements** (forms, tables, lists, buttons, media) - **Console errors** (if any) - **Failed network requests** (if any) ## Step 3: Interaction Testing Test the interactive elements discovered during the scan. ### 3a. Form Testing For each form found: 1. Identify form fields via `browser_snapshot` (inputs, selects, textareas, checkboxes) 2. Test empty submission — `browser_click` the submit button without filling fields. Check for validation messages 3. Test with valid data — `browser_fill_form` or `browser_type` to fill fields, then submit. Check for success/error responses 4. Check field types — do email fields validate email format? Do required fields show errors? **Do NOT submit forms that create real data in production.** If unsure whether the app is a development instance, ask the user before submitting forms. ### 3b. Navigation Testing 1. Click through the main navigation items using `browser_click` 2. Verify each link leads to the expected page (check URL and page title) 3. Test the browser back button with `browser_navigate_back` 4. Check for broken links (pages that return errors or show empty content) ### 3c. Interactive Elements 1. Test buttons — do they trigger expected actions (modals, toggles, expandable sections)? 2. Test dropdowns — do `browser_select_option` calls work? Do options load? 3. Test search — if a search bar exists, `browser_type` a query and check results 4. Test modals/dialogs — can they be opened and closed? Do `browser_handle_dialog` calls work? ## Step 4: Error Analysis Compile all errors collected during Steps 2 and 3. ### 4a. Console Errors Categorize console messages: - **Errors** (red) — JavaScript exceptions, failed assertions, uncaught promises - **Warnings** (yellow) — deprecation notices, React warnings, CSP violations - **Info** — development messages (usually ignorable) Focus on errors. Group by type (e.g., "TypeError: Cannot read property X" across 3 pages). ### 4b. Network Failures Categorize failed requests: - **4xx errors** — missing API endpoints, unauthorized access, not found resources - **5xx errors** — server crashes, timeouts, internal errors - **CORS issues** — blocked cross-origin requests - **Missing resources** — 404 for images, scripts, stylesheets, fonts ### 4c. UI Issues Note any structural problems detected from accessibility snapshots: - Empty pages or sections with no content - Missing labels on form fields (accessibility issue) - Broken layouts (elements with unusual positioning inferred from tree structure) - Missing alt text on images - Non-functional buttons or links ## Step 5: Generate Report Create the report at `docs/codemap/FRONTEND.md`. ### Report Structure ```markdown # Frontend Report — {App Name} **URL:** {base URL} **Tested:** {date} **Pages scanned:** {count} ## Summary {2-3 sentence overview: how many pages found, how many errors, overall health assessment} | Metric | Count | |--------|-------| | Pages scanned | X | | Console errors | X | | Console warnings | X | | Failed network requests | X | | Forms tested | X | | Broken links | X | ## Pages Discovered | # | URL | Title | Status | |---|-----|-------|--------| | 1 | / | Home | OK / Issues found | | 2 | /about | About | OK | | ... | ... | ... | ... | ## Console Errors ### {Error type/message} - **Pages affected:** {list of URLs} - **Frequency:** {count} - **Impact:** {what functionality is affected} ## Network Failures ### {Endpoint or resource} - **Status:** {HTTP status code} - **Pages affected:** {list of URLs} - **Impact:** {what breaks — missing data, broken images, etc.} ## Forms ### {Form name/location} - **URL:** {page URL} - **Fields:** {count and types} - **Validation:** {works / missing / broken} - **Submission:** {tested / skipped — reason} ## UI Issues ### {Issue description} - **URL:** {page URL} - **Element:** {what element is affected} - **Impact:** {accessibility, usability, visual} ## Recommendations 1. {Highest priority fix — with specific location and suggested action} 2. {Next priority} 3. {Next priority} ``` ### Report Rules - Use real URLs, page titles, and error messages from the test — no generic placeholders - Group similar errors (e.g., same TypeError across pages) instead of listing each individually - Prioritize recommendations by impact: data-loss risks first, then broken features, then UI polish - If everything is working well, say so — don't invent issues - Include the date of the test so the report can be compared with future runs - Create `docs/codemap/` directory if it doesn't exist ## Error Handling ### App not reachable If `browser_navigate` fails with a connection error: > "Cannot reach {URL}. Make sure the application is running. Check with `npm run dev`, `docker compose ps`, or the relevant start command for your project." ### Authentication required If the landing page is a login screen: 1. Ask the user for credentials (username/password or login method) 2. Use `browser_fill_form` or `browser_type` to log in 3. After login, proceed with the discovery phase from the authenticated state 4. Note in the report that testing was done in authenticated mode ### Playwright MCP not connected If Playwright MCP tools are unavailable: > "Playwright MCP server is not connected. Run `/mcp` to check server status. The plugin expects a `playwright` MCP server configured in `.mcp.json`." ### Dynamic content / SPAs For single-page applications where content loads asynchronously: - Use `browser_wait_for` after navigation to wait for key content to appear - Check `browser_network_requests` for pending API calls before taking snapshots - Retry snapshot if the page appears empty on first capture