Block a release that breaks
Run saved tests or an exploration from a script or a CI job, and ship only when they pass.
A release script or a CI job can ask Rehearsal to run your saved tests, wait for the verdict and carry on only when every test passed. An exploration can guard a release in the same way.
Two commands do the work. rehearsal run asks Rehearsal to run a set of tests, and returns as soon as the run is queued. The tests run on Rehearsal's servers, not in your job. rehearsal run wait then follows the run and exits with a code that says how it ended. Your script ships on 0 and stops on anything else.
On your computer, you need the CLI signed in, with the project saved by init, and starting a run needs Manage projects in the workspace. In a GitHub Actions job, the CLI signs in by itself, as Run it in GitHub Actions shows.
Choose the tests Link to Choose the tests
Typed alone in a terminal, rehearsal run asks what to run. It lists the project's suites, with the one saved for this folder first, and a row to pick tests one by one. When it ends, it prints the same command with flags, so you can run it again without the questions.
A script names the tests in one of three ways:
# Up to 200 tests, by identifierrehearsal run --test <test-id> --test <test-id># One suite, by name or identifierrehearsal run --suite release# Every approved test of one apprehearsal run --app webFor a release, a suite is the usual choice, because it runs the same tests in the same browsers and screens every time. Parcel's is called release, and rehearsal suites list shows its identifier and how many of its tests are ready:
rehearsal suites listrelease 0c4f8a2e-6b1d-4e9a-8f3c-2d5b7e9a1c40 14 of 14 readyEvery test has a readiness, which tells you what a run would do with it today. A run checks only the tests that are ready. If you give it one that isn't, the run lists it as not ready instead of checking it. rehearsal tests list shows the readiness of each test.
--test takes the identifiers these lists show, and --suite takes a suite's name or identifier. In a script, Rehearsal never picks the tests for you. A suite saved in rehearsal.config.json runs only when someone picks it, so a script names it with --suite each time. With none of the three, the command asks for --suite and lists the suites.
Good to know
A run passes only when every test it was given has passed. One test that is not ready, or that ends without a result, leaves the whole run without a verdict, and run wait exits 5. Before you gate a release on a suite, check that all its tests are ready.
Choose where each app runs Link to Choose where each app runs
An environment is where an app runs, such as production or staging. Each app in a run is tested on one environment. An app with only one needs nothing more. For an app with several, such as Parcel's web with staging and a local copy, rehearsal run asks which one at a terminal. A script names it with --environment:
rehearsal environments list --app webrehearsal run --suite release --environment staging--environment takes a kind, such as production, staging, preview or local, the name of a connected computer, or an environment identifier. A kind covers every app in the run that has one environment of that kind. In a script that leaves it out for an app with several, nothing starts, and the CLI lists the environments to choose from.
Start a run and wait for it Link to Start a run and wait for it
rehearsal run --suite release --environment stagingrehearsal run wait 42 --timeout 10mRun the release suite against staging with Rehearsal, wait for the result and tell me what failed.The agent starts the run with the run tool, then calls wait_run, which waits up to a minute each time, until the run settles.
run prints the run's number and identifier as soon as Rehearsal has queued it. run wait takes either one and follows the run until it ends. It waits 60 seconds unless --timeout sets another limit, up to an hour. When a test fails, it prints what went wrong:
Run #42 failed: a test failedIdentifier 7c1f0a9e-3b52-4d18-a6e4-5f2d9b8c0e13Browser chromiumScreen desktopEnvironment https://staging.parcel.example.comSelected 14Passed 13Failed 1Needs review 0Without a result 0What failed Check out a cart (5b0e2c4d-7f91-4a3b-8e6d-2c1f0a9b8e77) step 4: Check the order confirmation expected: The confirmation page shows an order number. saw: The page shows "Payment failed".The exit code says how the run ended. 0 means every test in the run passed. 5 means the run did not check everything: a test was blocked or got no result, someone stopped the run, or Rehearsal could not run it. An unfinished run exits 5 even when one of its tests failed, so 1 always means a run that checked every test and found a failure. Only 0 is a pass, so a run that could not check everything never reads as one.
If the wait runs out first, run wait exits 7 and the run carries on, so run run wait again to keep following it. Exit codes lists the others, such as 6 for a test that needs review.
Stopping the wait, by timeout or with Ctrl+C, never stops the run. To stop the run itself, use rehearsal run stop 42.
Ask again safely Link to Ask again safely
Starting a run can start paid work, so asking twice must never start two runs. That is what the request key is for. It is a name you give the request, and it makes a retry safe. If the answer gets lost, for example because the network dropped, send the same command with the same key. Rehearsal answers with the run it already started for that key instead of starting another.
In a terminal the CLI makes up a key for you, and before it sends the request it prints the arguments that repeat it with that key. A script, or any command with --json, passes its own with --request-key, using 8 to 200 characters that name this one release, such as a build number. A key belongs to one request, so sending it again with a different selection is refused. Request keys has the details.
rehearsal run --suite release --environment staging --request-key release-1842 --jsonRead a failure Link to Read a failure
rehearsal run report 42rehearsal evidence list 42rehearsal evidence download 42 --artifact <artifact-id> --output ./evidence/step-4.pngRead why Rehearsal run 42 failed, find the cause in our code and fix it.The agent reads the run with the show_run_report tool, and opens a screenshot or a recording with download_evidence.
run report prints the run as one Markdown document: each test, its steps in order, the page each step ended on, the error that stopped it and links to its evidence. The links expire after a few minutes, so run the command again when you need fresh ones.
evidence list shows the screenshots, recordings and traces the run kept. evidence download saves one to the path you give --output, and makes any folder on the way that does not exist yet. To keep the file's own name, give --output a folder that already exists instead. rehearsal run open 42 opens the run's page in your browser, and Read a run explains what each result means.
Run again after a fix Link to Run again after a fix
rehearsal run again 42rehearsal run compare 42 43run again runs the same test versions again, on the same environments, in the same browser and screen. To test somewhere else, start a new run instead. run compare lines up the tests of two runs, oldest first. It calls a test fixed only when it failed before, passes now, and ran the same version on the same environment, in the same browser and screen.
Gate a release on an exploration Link to Gate a release on an exploration
Saved tests check the flows you already have. An exploration looks for bugs nobody has written a test for yet, and --wait turns it into a gate:
rehearsal explore --app web --environment staging \ --focus "Check the cart and checkout before release" --account member \ --minutes 30 --request-key explore-release-1842 --wait --timeout 45mWith --wait, the command follows the exploration until it ends or the --timeout passes, which can be up to an hour. It exits 0 when the exploration checked every case it set out to check and found no bug, and 1 when it found a bug, however it ended. Any other ending exits 5, because it ends before a complete answer: it reached a limit, someone stopped it, the person who started it lost the permission it needs, it could not get into the app, or something failed on our side. If the wait runs out first, it exits 7 and the exploration keeps going.
Give a release check a narrow focus and enough minutes, because an exploration that runs out of time before it has checked everything exits 5, even with no bug found.
A workspace runs one exploration at a time, so Rehearsal refuses a start while another exploration there is queued, running, pausing, paused or stopping. That refusal exits 1 too, but before any wait begins, so with --json a script tells it from a found bug by the answer: a refused start carries an error, while a found bug carries bugs_found in data.wait.outcome. Apart from the timeout and Ctrl+C, only a status read that fails in a way that will not pass ends the wait before the exploration ends, and Waiting for an exploration lists every outcome.
Run it in GitHub Actions Link to Run it in GitHub Actions
The same commands make a release gate in CI. This workflow runs the release suite against staging on every push to main, and deploys only when every run passed. It needs no Rehearsal secret and no sign-in step.
name: Releaseon: push: branches: [main]jobs: check: runs-on: ubuntu-latest permissions: # Lets the CLI sign in with the job's GitHub identity id-token: write env: # The release suite's identifier, from rehearsal suites list SUITE_ID: <suite-id> steps: - uses: actions/setup-node@v7 with: node-version: 24 check-latest: true - run: npm install -g @rehearsal-labs/cli - name: Run the release suite run: | rehearsal run --suite "$SUITE_ID" --environment staging \ --request-key "release-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" --json > start.json for run in $(jq -r '(.data.runs // [.data])[].runId' start.json); do rehearsal run wait "$run" --timeout 30m done deploy: needs: check runs-on: ubuntu-latest steps: # Replace this step with your deployment. - run: echo "Deploying"id-token: writelets the job ask GitHub who it is. The CLI hands that identity to Rehearsal and signs in as the repository, as How a job signs in explains.- The job needs no checkout and no
rehearsal.config.json, because the repository's connection names the workspace and the project. If the job checks out code as well, addcontents: read, because a job that names any permission loses the rest. - The CLI needs Node.js 24.12 or newer.
check-latestmakes sure the runner does not use an older Node 24 it already has. run --jsonprints one JSON object, andjq, which GitHub's Ubuntu runners include, reads the run identifiers from it. A suite set to more than one browser or screen starts a run for each, so the loop waits for every one.- The key names this attempt of the workflow. Re-running the workflow starts new runs, while repeating the command within one attempt returns the runs it already started.
- GitHub stops the step at the first
run waitthat exits with anything but0. Thedeployjob needscheck, so it never starts.
How a job signs in Link to How a job signs in
The job signs in as the repository, with no person behind it. It can do so once the repository is connected to the project, as Connect a repository shows. That connection is the permission, so the job needs nobody's sign-in and nothing to renew.
- The job reaches only the project the repository is connected to. Another workspace or project named by a flag, a variable or
rehearsal.config.jsonstops the command withCONTEXT_CONFLICT. - It can read the project's tests, suites, runs and evidence, and start, repeat and stop runs. Exploring and rewriting a test need a person, so those commands are refused.
- A run it starts reads Started by GitHub and keeps the commit the job ran for. It counts towards your plan like any other run.
- Each sign-in lasts 15 minutes. The CLI asks GitHub again before it ends, so a long
run waitkeeps going. - Disconnecting the repository, or suspending the Rehearsal GitHub App, ends every job's sign-in at once.
Rehearsal signs a job in only for push, pull_request, merge_group, workflow_dispatch and schedule workflows. Only someone who can push to the repository can start one of those, apart from a schedule, which runs by itself. A pull request from a fork is refused, and so are events such as pull_request_target and issue_comment, which anyone who can see a public repository can start.
A job without id-token: write cannot sign in, and its first Rehearsal command exits 3 and says so. A sign-in saved with rehearsal login always wins: when the job finds credentials.json, the CLI uses it and acts as that person.
Results on pull requests Link to Results on pull requests
To see results on each pull request rather than in a job's log, connect GitHub and add a rule. Rehearsal then runs the rule's tests and posts the result as a check on the commit, which you can require before merging. A rule can test each Vercel preview of a pull request, the same address after every push to a branch, or an address your own workflow sends with the Rehearsal GitHub Action. The Action signs in with the job's GitHub identity too. See Send an address from GitHub Actions and Checks on commits.