playwright ECONNREFUSED on YOUR_HOST in CI

TL;DR

The test tried to reach the app server and nothing was listening. Start the server before the tests in CI (webServer config or start-server-and-test), bind it to all interfaces if the browser runs in a separate container, and verify with curl before the test step.

Error

Error: page.goto: net::ERR_CONNECTION_REFUSED at YOUR_HOST/

Steps

1. Add a webServer block to playwright.config.ts with the dev command, URL, and reuseExistingServer: !process.env.CI. Expected: Playwright starts the server and waits for the URL.
2. If the browser runs in a separate container, bind the server to the all-interfaces address and point tests at the service name, not YOUR_HOST. Expected: cross-container networking works.
3. Add a pre-test curl check in CI: curl --retry 10 --retry-delay 2 YOUR_HOST/health. Expected: the pipeline fails fast with a clear message instead of 50 test timeouts.
4. Check the port: CI services sometimes claim different ports than local. Print the actual listening port in the server logs. Expected: config port matches reality.
5. Re-run the CI job. Expected: goto succeeds because the server is provably up.

When to use

• ERR_CONNECTION_REFUSED in CI, green locally.
• The app server is started by the pipeline, not already running.

When not to use

• DNS failures (ERR_NAME_NOT_RESOLVED).
• The server is up but returns 500s (app bug).

Tool compatibility

• Playwright 1.30 through latest; webServer config; any CI provider.

Variant phrasings

Playwright could not connect to YOUR_HOST:3000 in CI

Same root cause; the server lifecycle is the fix.

webServer timeout waiting for URL

The server took too long to boot; raise the webServer timeout, not the test timeout.

Why it happens

Locally the dev server is already running from your terminal. In CI nothing is running unless the pipeline starts it, and tests race the boot.

Edge cases

• reuseExistingServer: true in CI hides the problem locally but breaks CI; gate it on !process.env.CI.
• Databases also need to be up; a refusing DB looks like an app failure one layer down.
• IPv6 YOUR_HOST (the loopback address) vs IPv4 (the loopback address) mismatches cause refuses that curl with the other family would catch.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst5yQTGW-kae-ZRamllnhcQ