agent-test-route-discovery

name	agent-test:route-discovery
description	Use when starting an agent test on a new project to discover all navigable routes and sub-routes for 100% coverage. Produces a ROUTE_MAP.md and initial state file.

Route Discovery

Overview

Discover every navigable route and sub-route in a web application. Produces a route map file that drives the entire agent test pipeline. Project-agnostic — works with any SPA or MPA.

Discovery Strategies

Choose based on project access:

Strategy A: Code-Based Discovery (Preferred)

If you have access to the project source code, scan route definitions:

Search patterns (framework-agnostic):
- React Router:    path: "...", element: ...
- Vue Router:      { path: '...', component: ... }
- Angular:         { path: '...', component: ... }
- Next.js:         app/**/page.tsx, pages/**/*.tsx
- Nuxt:            pages/**/*.vue
- Generic:         routes.ts, router.ts, *routes*.*

Steps:

1. Glob for route definition files: **/*route*.*, **/router.*, **/pages/**
2. Extract all path values and their hierarchy
3. Identify parent/child relationships
4. Classify each route by page type (list, detail, create, tool, auth)
5. Exclude auth/error/tool routes from test scope

CRITICAL: Only read route definition files. Do NOT read component implementations, business logic, or other source code. Minimize codebase exposure.

Strategy B: Browser-Based Discovery (Fallback)

If no source code access, explore via browser using Agent Browser only (headless by default):

agent-browser open {base_url}
agent-browser wait --load networkidle

1. Login to the application (fill credentials, submit)
2. Take a DOM snapshot: agent-browser snapshot -i
3. Extract all navigation links recursively from sidebar/nav
4. For each top-level section, click to expand sub-menus
5. After each expansion: agent-browser snapshot -i to capture new links
6. Record all discovered URLs
7. agent-browser close

CRITICAL: Use agent-browser for ALL browser interactions. Do NOT install Playwright, Puppeteer, Selenium, or any other browser tool.

Strategy C: Provided Route Map

User supplies a route list or existing route map. Validate and normalize it.

Output: ROUTE_MAP.md

# Route Map

> Auto-generated by route discovery. Total: {N} testable routes.
> Generated: {timestamp}
> Source: {strategy used}

## Route Registry

| # | Route | Page Type | Parent | Known Actions | Status |
|---|-------|-----------|--------|---------------|--------|
| 1 | /settings/general | list+detail | /settings | create,edit,delete | pending |
| 2 | /settings/billing | list+detail | /settings | create,edit,enable,disable | pending |
...

## Excluded Routes (not testable)

| Route | Reason |
|-------|--------|
| /login | Auth flow |
| /exception/* | Error pages |
...

## Route Categories

### Category 1: {Section Name} ({count})
- /section/route-a
- /section/route-b
...

Classification Rules

Page Type	Indicators
list	Table/grid, toolbar, pagination
list+detail	List page + navigable :uuid detail page
create	Form/wizard for resource creation
detail	Single resource view with tabs/actions
tool	Special-purpose page (terminal, editor, topology)
dashboard	Charts, metrics, overview cards
settings	Configuration forms

Exclusion Criteria

Exclude from agent test queue:

• Auth pages: /login, /sso/*, /oauth/*, /select-identity
• Error pages: /exception/*, /404, /500
• Remote tools: /web-ssh, /novnc, /inspector-*
• Setup wizards: /wizard, /setup
• Redirect stubs: Routes that only redirect to :uuid or other routes
• External iframes: Plugin/vendor pages loaded via iframe

Checklist

• Route definition files identified (Strategy A) or navigation explored (Strategy B)
• All routes extracted with parent/child hierarchy
• Routes classified by page type
• Non-testable routes excluded with reasons
• ROUTE_MAP.md written to project root
• Initial state file created via state-management skill