Core concepts

Learn the words Rehearsal uses and how an exploration leads to bugs, tests and runs.

Rehearsal works with a small set of things, and the app and these docs give each one the same name. This page explains them one by one, then shows how an exploration leads to bugs and tests, and how a test leads to runs.

The words Link to The words

WordWhat it means
WorkspaceYour team's space in Rehearsal. It holds the members, the projects and the plan.
ProjectOne product you test. It holds its apps and everything Rehearsal keeps about them: tests, bugs, runs, test accounts and files.
AppOne thing in a project that Rehearsal tests, such as Parcel's web app, its admin or its docs.
AddressOne place where an app answers, such as Production at https://parcel.example or Local at http://localhost:3000. The app's settings call each one an environment.
ExplorationOne session in which subagents work through an app, check what it does and report what they find. It ends with a report.
Re:agentThe assistant you chat with. It plans each exploration, starts the subagents and answers you, and it can also make a test from a flow you describe.
SubagentAn agent Re:agent starts for one part of the app, working in a browser of its own.
Test caseOne thing the app should do, written as a sentence, such as "A saved card is still listed after signing in again". A subagent checks it and marks how it went.
BugA test case that failed and, usually, failed again when a second subagent repeated it in a fresh browser. Each bug has a number in its project, such as Bug #5.
SuggestionSomething on a page that could look better but is not a bug, such as uneven spacing, a part out of line or text below the contrast WCAG asks for at Level AAA.
Accessibility issueOne problem against a WCAG 2.2 criterion at Level A or AA, such as one text colour with too little contrast, counted once however many places it shows in.
TestA saved Retest test of one flow, which Rehearsal can run again whenever you ask.
SuiteA group of tests you run together, by hand or on a schedule.
RunOne time your tests are checked, whether one test, several or a suite, each at one address of its app, on one screen size in one browser. Choosing two screen sizes starts two runs.
ResultHow one test ended in one run, such as passed, failed or blocked.
Test runOne test checked once in a run. Five tests on two screen sizes are 10 test runs, and your plan counts these.
EvidenceWhat a test left behind in a run: the recording, the steps, a screenshot where it failed, the trace, and what the browser logged and requested.

From an exploration to bugs and tests Link to From an exploration to bugs and tests

Everything starts with an app and one of its addresses. An exploration works on one app: Re:agent goes through its pages, writes a plan of the parts it will test and what it will check in each, then waits for you to press Start testing. The subagents then take the parts between them, and what they check is kept as test cases, each with its outcome. A workspace runs one exploration at a time.

That is how an exploration you start from setup or the chat goes. One started from the CLI or by a coding agent works differently by default. There is no plan to approve and no Start testing, and everyone who can read the project can see it.

A test case that fails is usually not a bug yet. A second subagent repeats it in a fresh browser, and only a failure it sees again becomes a bug, while the rest are kept under Bugs we couldn't reproduce. How a failure becomes a bug says when a failure counts at once. Suggestions and accessibility issues come from the same pages, but each has a list of its own, apart from the bugs.

The test cases that passed show what works in your app today. When the exploration ends, Rehearsal can make tests from them, starting with the journeys it recommends, so you hear about it if one of them stops working later. A bug can become a test too: once you mark it fixed, Rehearsal offers to write a test from its steps, and that test joins the others once it has seen the fix work.

From a test to runs Link to From a test to runs

A test belongs to an app, not to one of its addresses, so the same test can check production one day and a preview the next. Before a new test is ready, Rehearsal runs it twice, the second time in a fresh browser, and the test is ready once both runs pass. Until then it says Verifying, or Could not verify if its last check did not pass.

A run checks the ready tests you give it, each at one address of its app, and writes one result per test. It keeps the test versions and addresses it started with, so a change to a test or a suite applies from the next run. Each result keeps its evidence, so a failure shows the step where the test stopped, what the page showed and the recording.

If a problem on Rehearsal's side stops a run, Rehearsal picks it up again and keeps the results it already has. A run it still cannot finish says Could not run and counts towards nothing. Runs use test runs from your plan, and exploring and making tests use none.

You start runs from Tests in the app, on a schedule for a suite, or from the CLI. GitHub starts them too, when a pull request opens, a branch changes or a deployment is ready, once you connect a repository and add a rule that says which tests run and when.

What Re:agent uses Link to What Re:agent uses

Three pages in a project's settings hold what Re:agent works with. Test accounts holds the accounts Re:agent, the subagents and your tests sign in with, and Files for tests holds the files a test uploads. What Re:agent knows holds the notes Re:agent keeps about each app, which it reads every time it works on the app and which you can change, as What Re:agent knows explains.

Who can do what Link to Who can do what

Someone with the Member role can explore, make tests and start runs, while a Viewer can look at the projects and change nothing. Admins can also invite people, connect GitHub and manage billing, and an owner can make custom roles and delete the workspace as well.

Your chats with Re:agent are private to you, and so is an exploration you start in one, with its bugs. A bug becomes the whole project's once a test has seen it happen or has checked its fix, and its exploration becomes the project's with it. An exploration started from the CLI has no chat, so it belongs to the project from the start, and tests always belong to the project.

Next steps Link to Next steps