The image with “browsers” in the name ships no browser

Prove it in three commands

You do not have to take my word for it. Pull the image and look. Node is the version on the tin. The browser is absent. The only new binary the layer drops into /usr/local/bin is the Selenium jar.

That empty result from which google-chrome is the whole story. The image is named for what it is built to host, not what it contains.

What the -browsers layer actually adds

Read line by line from the published Dockerfile, here is everything the browsers variant stacks on top of the base Node image, and why each piece is there.

The Selenium jar, the JRE, and Xvfb are all artifacts of a WebDriver-era testing model. If you are not running Selenium, almost none of this layer earns its place in your job.

Two ways to get a real browser into the job

There are two correct configs depending on what your tests run on. The first uses the image as CircleCI intends, with the orb installing Chrome. The second admits you probably do not need the -browsers image at all.

Path A — Selenium / WebDriver: install the browser with the orb

The -browsers tag and the browser-tools orb are a matched pair: the image carries the dependency libs, the orb drops in a pinned Chrome and ChromeDriver at runtime.

version: 2.1

orbs:
  browser-tools: circleci/browser-tools@1

jobs:
  e2e:
    docker:
      - image: cimg/node:20.11-browsers   # amd64 only
    steps:
      - checkout
      - browser-tools/install-browser-tools   # <- installs the actual Chrome
      - run: npm ci
      - run: npm test                         # Selenium / WebDriver suite

workflows:
  test:
    jobs:
      - e2e

Path B — Playwright: skip the image, bring your own browsers

Playwright ships its own browser builds, pinned to the Playwright version in your package.json. It never looks for a system Chrome, so the Selenium jar and Xvfb in the browsers layer are dead weight. Run on the plain cimg/node:20.11 image and install browsers in one step.

version: 2.1

jobs:
  e2e:
    docker:
      - image: cimg/node:20.11             # NOT -browsers; you don't need it
    steps:
      - checkout
      - run: npm ci
      - run: npx playwright install --with-deps   # Playwright brings its own browsers
      - run: npx playwright test

workflows:
  test:
    jobs:
      - e2e

If you want zero install steps, you can also run directly on Microsoft's official Playwright image (mcr.microsoft.com/playwright), which already contains the browsers and OS dependencies matched to a Playwright release. The Playwright CI docs show the executor config for that route.

From red to green on the Playwright path

If you came here because of a failing job, this is the shortest route to a passing one without fighting the image.

If you are on Selenium and genuinely want the orb route, the same shape applies: keep the -browsers image and add browser-tools/install-browser-tools before your test step.

Where the tests themselves come from

Getting a browser into the job is the easy half. The harder half is writing and maintaining the tests that run in it. This is the part of the pipeline Assrt sits in. Assrt is an open-source tool that crawls your app, proposes the flows worth testing, and produces real Playwright tests, not a proprietary YAML format and not a closed cloud you have to keep paying. Because the output is standard Playwright, it runs in exactly the CircleCI job above with npx playwright test.

And it inherits the same browser story: since Assrt rides the Playwright engine, it leans on Playwright's own browser management, so you keep the lean cimg/node:20.11 executor and the single playwright install step rather than dragging the Selenium-era -browsers layer along. The tests live in your repo and your CI, with zero vendor lock-in. The source is open on GitHub and shipped as the @m13v/assrt package.

For the deeper version of the runner-versus-artifact decision, see the e2e testing framework guide, and for why CI environments drift away from local, see CI config drift.

When -browsers is still the right call

None of this means the tag is useless. If your suite is built on Selenium or raw WebDriver, you genuinely want the JRE, the Selenium jar, the Xvfb display, and the dependency libs already in place so the orb only has to drop in the browser. For those teams, cimg/node:20.11-browsers plus circleci/browser-tools is the canonical, well-trodden setup. The mistake is only assuming the word “browsers” means a browser is baked in, and reaching for this image on a Playwright project where a leaner base and one install step do the same job with less surface area. One caveat to plan around either way: the browsers variants are published for amd64 only, so an arm resource class will not match the image (tracked here).

Frequently asked questions