Skip to content

docs: document running the end-to-end suite without root - #1311

Merged
mrbobbytables merged 1 commit into
mainfrom
docs/playwright-non-root-setup
Oct 11, 2026
Merged

mrbobbytables merged 1 commit into
mainfrom
docs/playwright-non-root-setup

Conversation

@mrbobbytables

Copy link
Copy Markdown
Member

Finding (#1277)

CONTRIBUTING.md documented one way to get Playwright's OS packages, npx playwright install --with-deps chromium, which runs apt-get install and so needs root. Without root the recipe cannot be followed, and the failure it leaves (browserType.launch: Target page, context or browser has been closed) names neither the missing library nor the install step. Three earlier findings (#1232, #1253, #1256) each had to note the browser suite could not be run locally for exactly this reason.

What changes

  • CONTRIBUTING.md ("End-to-end tests"): adds the non-root recipe beside the existing one. Install the browser bundle alone, apt-get download the packages into a private sysroot (private APT state dir so no root is touched), dpkg-deb -x them, and point LD_LIBRARY_PATH at the result. The package list is the corrected one from the issue thread: the 28 chrome-headless-shell needs plus the 17 more the full chrome binary loads, so headed and channel: 'chromium' runs work too. The ldd check loops over both binaries. Notes cover the harmless rm: cannot remove .../partial noise, the per-shell export, not setting XDG_CACHE_HOME, and the arm64 loader path. The package block is fenced with cspell:disable/enable rather than adding 40 package names to the dictionary.
  • tests/contributing-e2e-setup.test.mjs: the contract treated any npx playwright install without --with-deps as incomplete unless the doc also named install-deps (which needs root just the same). It now also accepts a doc that unpacks the packages into a sysroot and hands the loader that directory (documentsSystemPackages), with a fixture test pinning that neither half alone passes. Without this change the test rejects the new section (CONTRIBUTING.md: npx playwright install chromium), so it is a genuine contract update rather than a loophole.

Verification

Ran the recipe as an unprivileged user on Ubuntu 26.04 (the issue verified Debian trixie):

  • all 45 packages download; both chrome and chrome-headless-shell report 0 missing under ldd (from 5 and 4 before);
  • npm run build:production && npm run test:e2e with the sysroot on LD_LIBRARY_PATH: 312 passed, 30 skipped (1.2m).
  • tests/contributing-e2e-setup.test.mjs + tests/dev-environment.test.mjs: 20 pass. check:format, check:spelling, markdownlint on CONTRIBUTING.md: clean.

Closes #1277

CONTRIBUTING.md gave one way to get Playwright's OS packages,
npx playwright install --with-deps chromium, which shells out to apt-get
install and so needs root. On an unprivileged container or shared dev host
the documented recipe cannot be followed, and the failure it leaves behind
(browserType.launch: Target page, context or browser has been closed) names
neither the missing library nor the install step.

Add the non-root path beside it: install the browser bundle alone, apt-get
download the same packages into a private sysroot with a private APT state
dir, dpkg-deb -x them, and point LD_LIBRARY_PATH at the result. The package
list covers both binaries Playwright unpacks (the 28 chrome-headless-shell
needs and the 17 more the full chrome binary loads), with an ldd loop over
both as the check, and notes for the two things that look like failures but
are not.

tests/contributing-e2e-setup.test.mjs treated any npx playwright install
without --with-deps as incomplete unless the doc also named install-deps,
which needs root just the same. It now also accepts a doc that unpacks the
packages into a sysroot and hands the loader that directory, and a fixture
test pins that neither half alone is enough.

Verified on Ubuntu 26.04 as an unprivileged user: all 45 packages download,
both binaries report 0 not found under ldd, and npm run test:e2e against a
production build passes (312 passed, 30 skipped).

Closes #1277

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Bob Killen <bkillen@linuxfoundation.org>
@mrbobbytables
mrbobbytables added this pull request to the merge queue Oct 11, 2026
Merged via the queue into main with commit 8470015 Oct 11, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[quality] the documented Playwright setup needs root, so the required e2e suite cannot be run locally without it

1 participant