Discovery

What Discovery Does

A discovery runs in three stages. If you supplied test credentials, a login stage signs in first. Then a crawl drives a real browser from your starting URL: on every page it collects the links, buttons and controls, fires them one by one, and records every distinct UI state it lands in — a page, an open menu, a dialog, a filtered list — with a screenshot, a DOM snapshot and the browser console. It does not fill in forms or invent data, so it maps what is reachable by clicking.

Finally a review reads the crawl: the screenshots, the DOMs and the state graph. It writes a description of what the application is and does, groups the pages by purpose, drafts the tests the suite should contain, and reports problems it saw — console errors, broken layouts, silent failures.

The end result is an app map — every state the crawler reached and how it got there — and a set of draft tests and findings that you accept or dismiss.

When to Use Discovery

• Getting started with a new app. If you just set up a project and have no tests yet, run a discovery first. It will give you a set of suggested tests to start from, so you do not have to write everything from scratch.
• After a major refactor. When your app has changed significantly — new pages, restructured navigation, redesigned features — run a fresh discovery to see what the app looks like now and identify any new areas that need test coverage.
• Periodic coverage checks. Run a discovery every few weeks to find pages or features that exist in the app but have no test tests. This helps you close the gap between what your team thinks the product does and what it actually does.

Discovery is broad — it explores everything it can reach. Tests are deep — they test one specific flow thoroughly. Use discovery to figure out what to test, then use tests to test it.

How to Run a Discovery

Go to Setup > Discovery in the sidebar and click Run Discovery.

You will see a few fields:

• Project. Select which project this discovery belongs to. Test suggestions will be created under this project.
• Starting URL. Where the crawl begins. Use the home page, or the login page if the app requires authentication. Query parameters are kept: if your app needs a flag to expose a surface to testing, put it here.

Click Run and the discovery starts. You can watch it live: the app map fills in as states are found, and the review stage shows the reviewer reading screens and drafting. A typical crawl takes one to twenty minutes depending on the size of the application; the review a few minutes more.

Want to run discoveries programmatically? See the Discoveries API reference.

What You Get Back

When a discovery completes, you get three things:

• App map. Every UI state the crawler reached, grouped into pages by purpose, with the screenshot, the interactive elements and the click that led there. Pages your tests have already driven are tinted, so the map doubles as a coverage view.
• Draft tests. A ranked set of tests derived from what the app can do, written the way the writing guide asks: a goal and what the agent cannot invent as instructions, the observed path as dated hints, and outcome-level validations with a negative case wherever a flow changes state. Each draft also says what running it does beyond reading pages — creates data, sends email, spends money — and whether it covers an end-user or an operator surface.
• Draft findings and the report. Problems the reviewer saw, each pointing at the crawl state that evidences it, plus a written description of the application. The full trace of the review is available too, so you can see which screens the reviewer looked at before drafting.

Acting on Results

The most valuable output of a discovery is the test suggestions. Here is the typical workflow:

• Review the drafts. Open each suggested test to see its goal, hints, validations, entry point and side effects. Some will be exactly what you need, others will need the domain knowledge only you have — a correct answer, a right total — added to the validations.
• Accept the ones you want. Accepting creates a draft test on the project; open it, adjust anything, and set it active when you are happy. Dismiss the rest. Check the side effects before scheduling a test against a production environment.
• Add to a schedule. Once you have a set of tests, add them to a schedule so they run automatically on a recurring basis.

You do not have to accept every draft. Start with the ones that cover your most critical flows, then add more over time. Re-running a discovery after a release shows the reviewer your existing tests, so it proposes what is new rather than what you already have. See the Writing Effective Tests guide for how to sharpen a draft's validations.

Discovering authenticated pages

If your application requires login, the crawler needs a way past the authentication gate; without one it maps only the public pages.

Give the discovery a dedicated test account's credentials when you start it. They are used once, by a login stage that signs in before the crawl, and are never stored or shown again. Use a throwaway account: the credentials are handed to an agent in plain text, as with any test.

If the login flow involves a magic link or verification email, create a mailbox for the test account and attach it to the tests you accept from the discovery. The mailbox gives the agent read access to the inbox so it can complete the email step.