How to Run TestCafe in CI Without Browser Launch Errors

TestCafe does not bundle a browser - it launches whatever Chrome/Chromium or Firefox is installed. CI fails when no browser is present or it cannot run headless/sandboxed.

TestCafe is a Node end-to-end test runner that drives real system browsers via a proxy, rather than bundling its own. In CI you must install a browser (commonly Chrome/Chromium), run it headless, and pass --no-sandbox in containers - otherwise launches fail.

Why it fails in CI

TestCafe resolves an installed browser by alias (e.g. chrome, chromium). On a slim runner no browser exists, so it errors with "unable to find the browser". In a container, Chrome refuses to start without --no-sandbox, and a slim image lacks the Chromium shared libraries.

Unable to find the browser - no Chrome/Chromium installed.
No usable sandbox! - containerized Chrome needs --no-sandbox.
error while loading shared libraries: libnss3.so - missing Chromium system libs.

Install & run it reliably

Install Chrome/Chromium and its libraries, then run TestCafe against the headless browser with the sandbox disabled in containers.

.github/workflows/e2e.yml

# install a browser + its libraries (Debian/Ubuntu)
apt-get update && apt-get install -y chromium-browser
# or install Google Chrome stable

npm ci
# headless + no-sandbox for containers
npx testcafe "chromium:headless --no-sandbox" tests/

Cache & speed

There is no TestCafe-managed browser cache - the browser is a system install, so bake it into a custom image. Cache ~/.npm for the Node dependencies. Run only the browsers you need to cut time.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Common errors

Unable to find the browser → install Chrome/Chromium and reference the right alias.
No usable sandbox! → append --no-sandbox to the browser string in containers.
libnss3.so / shared-library errors → install the Chromium system library set.
Browser opens then hangs → use the :headless modifier on a runner with no display.

Key takeaways

TestCafe drives system browsers - install Chrome/Chromium yourself.
Use :headless and append --no-sandbox in containers.
Bake the browser into the image; cache ~/.npm.