Debugging a scene locally

npx midstream runs one of your scenes on your own machine and stops there, so you can see what a reviewer will see without waiting for CI. It is the fastest way to check that a new scene call is in the right place.

Running it

With @midstream/sdk installed in your project, from the directory you would normally run Playwright in:

npx midstream

That lists every scene call it finds in your working tree and lets you pick one. If you already know which:

npx midstream cart-one-item

Either way it finds the test containing that call, runs it headed, and pauses at the scene. Playwright's inspector opens alongside the browser, and the test's timeout is suspended while it is paused — take as long as you like. Resume or stop from the inspector when you are done.

Discovery reads your source

The list comes from scanning your working tree for scene calls, not from asking Midstream what it has. That is the useful behavior: it shows what you can run right now.

• A scene call you added two minutes ago and have not pushed is in the list.
• A scene that exists in the dashboard but whose call is on another branch is not.
• Renaming a slug shows up immediately, because the list is your code.

What a scan can read is limited. It finds midstreamScene() calls with the slug written as a plain string in the call itself:

await midstreamScene(page, "cart-one-item");

A slug held in a variable, one built from a template, and the namespaced midstream.scene() form are all invisible to it. Those scenes still work everywhere else — they just will not be in the list, so run them by hand as shown below.

Slugs also need to be unique across your files. Given two calls with the same slug, the command tells you where both are and stops rather than guessing; that is worth fixing anyway, since two calls with one slug are fighting over one scene.

Piping the output somewhere, or running it where there is no terminal to prompt in, prints the list instead of asking you to choose.

Doing it by hand

The command is a convenience over one environment variable. Set it yourself and you get the same pause:

MIDSTREAM_DEBUG_SCENE=cart-one-item npx playwright test tests/cart.spec.ts --headed

Reach for this when you want to control the Playwright invocation — a specific project, a config file, a different reporter — or if npx midstream picked the wrong test, or reported that it found no tests to run.

What this proves, and what it does not

Pausing locally tells you that the test reaches the scene, and what the app looks like when it gets there. If it does not stop on your laptop, it will not stop in a deploy either, and that covers most of what goes wrong.

It does not tell you whether your app will start inside a deploy. A deploy begins from a fresh container with your repository at one commit and runs your install and start commands, with none of the state your laptop has accumulated. Getting that right is a separate job, covered in the project configuration articles.