Test an app on your computer

Connect an app running on localhost so Rehearsal can explore it and run its tests before you push.

With rehearsal connect web, Rehearsal's browsers can open the app you are running on your computer. You can explore it and run its saved tests before anything is pushed or deployed.

Rehearsal's browsers run on its servers, where localhost is not your computer. connect web opens a connection from your terminal to Rehearsal and holds it while the command runs. Requests from Rehearsal's browsers travel through it to your app. They reach only the local URLs you name.

Before you start Link to Before you start

  • The CLI is installed and signed in. The default sign-in already allows local connections.
  • Your role has Manage projects in the workspace.
  • Your app is running. The examples use Parcel's web app at http://localhost:3000.

Connect your app Link to Connect your app

Terminal
rehearsal connect web

The CLI asks which URL your app answers on. It lists the local URLs that answer right now, so you pick yours with the arrow keys. Choose Another URL to type one it did not find.

You can name the URL yourself and skip that question. It uses localhost, 127.0.0.1 or [::1], with the port and no path.

Terminal
rehearsal connect web http://localhost:3000

Then the CLI works out which app the URL belongs to. Only web apps are offered. If a project already holds this URL, or you have only one web app, it uses that one. Otherwise it asks which project and app to add it to. To skip those questions, name both:

Terminal
rehearsal connect web http://localhost:3000 --project parcel --app web

--project takes the project's slug, name or identifier. --app takes the app's name, as the question lists it, or its identifier. connect web reads only these two flags, never the project that init saved.

After a question, the CLI prints a Same again line. It is the same command with every answer written in, so it asks nothing next time.

rehearsal connect on its own shows everything this computer can connect: a web app, a desktop app, iPhone simulators and Android emulators. It asks which one and starts it. A desktop app built on Electron connects with rehearsal connect electron, as iPhone, Mac and Electron apps explains.

The connection panel Link to The connection panel

While the connection is open, the terminal shows a panel like this one:

Output
  Rehearsal v2.0.0  ● Connected  Project    Parcel  App        web  Local      http://localhost:3000  Local app responded (HTTP 200)  Observed requests   12     Errors   1  Traffic    48.2 KB sent / 1.6 MB received  Active connections   2     Errors   0  Last activity: 2s ago  14s ago    GET     200     63 ms  /cart  9s ago     POST    200     118 ms  /api/cart  3s ago     POST    500     204 ms  /api/orders  2s ago     GET     200     41 ms  /checkout  Ctrl+C to disconnect
  • Every 10 seconds the CLI checks that your app answers at its URL. The line under the URL says what it found. The panel reads "Connected" only once your app has answered as well.
  • If your app stops answering, the panel reads "Needs your attention" and asks you to check that the app is running on that port. The connection stays open, so the panel turns back to "Connected" as soon as the app answers.
  • The most recent requests from Rehearsal's browsers appear at the bottom with their status and time. The CLI shows only the path, without the query string. A path that looks like a sign-in or reset link ends in [redacted].

These lines describe traffic, not results. What an exploration or a run found is in Rehearsal, and in the commands that read it.

Explore or run tests on your computer Link to Explore or run tests on your computer

Leave the connection open and work from a second terminal. --environment local sends the work to the app on your computer:

Terminal
# Explore the apprehearsal explore --app web --environment local --focus "Check the cart and checkout" --account member# Run its saved testsrehearsal run --app web --environment local

Your first connection added a local environment to the app, and that environment is yours. Connecting the same URL again comes back to it, so its runs keep their history. The CLI calls the connection after the app, such as web local, and --name gives it another name.

When teammates connect the same app, the project holds a local environment for each of you, and local alone no longer says which. The CLI then lists them, and you pass yours to --environment by its name or its identifier.

Rehearsal starts an exploration or a run on a local environment only while something is connected to it. Otherwise the CLI says that nothing is connected and prints the rehearsal connect web command that fixes it.

More than one port Link to More than one port

If your app calls another server on your computer, such as an API on port 3001, allow that URL as well:

Terminal
rehearsal connect web http://localhost:3000 --allow http://localhost:3001

Repeat --allow for each one. Rehearsal's browsers reach only the URLs you list. Each follows the same rule as the first: a loopback host with its port and no path.

From a script or a coding agent Link to From a script or a coding agent

Plain rehearsal connect web holds its terminal until you press Ctrl+C. That suits a person but not a script. With --detach, the connection moves to a background process. The command returns once your computer is connected, and you get the terminal back.

Terminal
rehearsal connect web http://localhost:3000 --project parcel --app web --detach# Later, list the connections this computer started, then close onerehearsal connect listrehearsal connect stop <connection-id>

A script is never asked anything. Where the CLI would ask, it stops with exit 4 and names what to add. Without a URL, the error lists the local URLs that answer now.

--detach waits up to 60 seconds for the connection, and --timeout gives it up to 10 minutes. If the time runs out first, the command returns while the background process keeps trying. rehearsal connect list tells you whether it got there. With --json, the answer names the connection, so a script can stop it later.

connect list says three things about each connection: whether its process still runs on this computer, whether Rehearsal holds it open, and whether the tunnel is up. "Tunnel connected" means the tunnel is up, which is not the same as your app answering.

connect stop ends the process, closes the connection and removes its state file. Your local environment stays in Rehearsal for next time. With nothing named, it stops the only connection running in the background, or asks which one.

Without --detach, rehearsal connect web has no JSON form, so --json on its own is refused. connect web lists every flag, and Connecting in the background gives each exit code.

When the connection drops Link to When the connection drops

If the connection drops, the CLI connects again by itself, and the panel counts the attempts. It waits 1, 2, 5 and 10 seconds, then 30 seconds between tries. It gives up after 30 minutes without success.

It stops at once, and says why, when your sign-in has ended, your permission to connect the app was removed or Rehearsal closed the connection. If the sign-in was the reason, run rehearsal login and connect again.

Good to know

Stopping a wait, such as run wait or explore --wait, never stops the work in Rehearsal. Closing the connection does cut your app off from that work, so keep it open until the exploration or the run has ended.

Next steps Link to Next steps