Map your app

Build a map of your app's pages from its code and a crawl, and see which pages each role reaches.

A map is Rehearsal's list of your app's pages and API routes, with the roles that reached each page. This page shows how to build one from both sides and how to read it, and what an exploration does with it.

The two sides know different things. Your code knows every route, including pages no link leads to. rehearsal map scan reads it on your computer. A crawl knows which pages each account can really reach. rehearsal map crawl opens the app in a browser, signed out and then as each test account. rehearsal map show puts the two together, so you can see which pages a role reached and which it never did.

Each of the three asks which app when the project has more than one. Answer with --app to skip the question, or save the app for this folder with rehearsal init.

Scan your code Link to Scan your code

Terminal
rehearsal map scan
Output
Found 18 pages and 9 API routes in this Nuxt app. It also found 2 roles and 6 record types.Identifier: <scan-id>

Run the scan in the folder that holds the app's code, or name that folder, as in rehearsal map scan apps/web. It reads Nuxt, Next.js, SvelteKit, Express and Hono apps, and it skips installed packages, build output and every file git ignores. Rehearsal receives the list of what the scan found, with the file and line each entry came from, and never the files themselves.

Besides the routes, the scan notes what the code says about roles, permissions, records, emails, scheduled tasks and outside services, and which files changed recently. Scanning needs Manage projects.

Each scan replaces the app's routes, so scan the folder that holds the whole app. A folder with no routes in it is refused, and nothing is sent.

Crawl the app Link to Crawl the app

Terminal
rehearsal map crawl --account member --wait
Output
Identifier: <crawl-id>Status: CompletedPages: 42 across 17 routes  visitor: 9 pages  member: 33 pages

A crawl opens one environment of the app in a browser on Rehearsal's servers. It follows the app's links signed out first, as the visitor, then signs in as each account you name and follows them again. It sends no form except the sign-in form, and it starts no paid work. Crawling needs Manage projects, as scanning does.

Name each account by its label. A crawl signs in with a password, so it takes the project's password accounts that sign in to that environment. It takes one account for each role and skips a second account with the same role. When the app has several environments, the crawl asks which one; --environment staging answers it. An environment on your computer needs its connection open while the crawl runs.

Without --wait, the command returns as soon as the crawl starts. With it, the command follows the crawl to the end, for up to ten minutes unless you set --timeout. When a role adds nothing to the map, the output lists it under Not mapped with the reason, such as a sign-in that asks for more than a password.

Read the map Link to Read the map

Terminal
rehearsal map show
Output
Route        Kind  member   visitor/            Page  Covered  Covered/cards       Page  Covered  Missing/cards/:id   Page  Covered  Missing/invite/:id  Page  Missing  Missing/api/cards   API   Unknown  Unknown

Every role has a column, both the roles your code names and the roles a crawl walked as. An account's role is the one you gave it, or else its label. Covered means a crawl reached the page as that role, and Missing means a crawl went through the app as that role and never reached it. Unknown means nothing says yet, either because no crawl has run as that role or because the route is an API, which a crawl never opens.

A missing page is not always a bug. Some pages are reached only through an email link or a form, such as an invitation, and no crawl follows those. Add --environment staging to count only what crawls reached in one environment.

How an exploration uses the map Link to How an exploration uses the map

You do not have to build a map before you explore. rehearsal explore opens the app's pages itself before it writes its plan.

Add --map reuse to plan from the map the app already has, when it has one. The exploration then skips that first walk through every page.

Next steps Link to Next steps