Connect a local app

Rehearsal's browsers run on Rehearsal's servers, so they cannot open localhost on your computer by themselves. The CLI connects your app to Rehearsal while the command runs.

Before you start #Link to Before you start

• The CLI is installed and signed in with the tunnel scope. rehearsal login asks for it by default.
• Your role has Manage projects for the workspace.
• Your app is running on your computer.

Connect #Link to Connect

$ rehearsal connect http://localhost:3000

Use your app's own address and port. If you have more than one project or app, the CLI lists them and asks for a number. Name them to skip the questions:

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

--project takes the project's slug, name or identifier. --app takes the app's name or identifier.

The app prints these commands with your project's names already in them. Open the project menu in the top bar and choose Terminal and coding agents.

The connection panel #Link to The connection panel

While it runs, the terminal shows a panel like this one:

  Rehearsal v1.0.1  ● Connected  Project    Parcel  App        web  Local      http://localhost:3000  Local app responded (HTTP 200)  Observed requests   14     Errors   1  Traffic    61.4 KB sent / 1.8 MB received  Active connections   2     Errors   0  Last activity: 2s ago  12s ago    GET     200     63 ms  /cart  9s ago     POST    200     118 ms  /api/cart  8s ago     GET     200     52 ms  /checkout  3s ago     POST    500     204 ms  /api/orders  2s ago     GET     200     41 ms  /checkout/confirmation  Ctrl+C to disconnect

• Every 10 seconds, the CLI checks that your app answers at its address. The line below the address says what it found.
• The last five requests from Rehearsal's browser appear at the bottom, with their status and time.
• Only the path of a request is shown. Query strings are dropped, and paths that look like sign-in or reset links end in [redacted].

These lines describe traffic, not test results. A run's result is in Rehearsal.

More than one port #Link to More than one port

If your app calls another local server, such as an API on port 3001, allow it too:

$ rehearsal connect http://localhost:3000 --allow http://localhost:3001

The CLI reaches only the addresses you list. Each one uses localhost, 127.0.0.1 or [::1], with a port and no path.

Your local address in Rehearsal #Link to Your local address in Rehearsal

The first connection adds a local address to the app, and that address is yours. Connecting again with the same address comes back to it, so your tests and runs keep their history.

The CLI names your computer after the app, such as web local. Choose another name with --name. You can then pick this address by name when you start a run.

While nothing is connected, a run at this address does not start. The CLI answers ENVIRONMENT_OFFLINE and names the rehearsal connect command that fixes it.

Stay connected #Link to Stay connected

Keep the terminal open while tests run. Press Ctrl+C to disconnect. Your local address stays in Rehearsal for next time.

If the connection drops, the CLI tries again and the panel counts the attempts. It waits 1, 2, 5 and 10 seconds, then 30 seconds between tries. After 30 minutes without success, it stops.

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

rehearsal connect has no JSON form, because it holds the terminal open. Give it a terminal of its own, then run tests from another one.

A coding agent can start it too. See Use Rehearsal from your coding agent.

Next steps #Link to Next steps

• Run tests from the terminal against your local address.
• Read the Command reference for every flag of rehearsal connect.