[FAQ] Playwright installed Chromium fine, but my coding agent still can't open a page — why, and what to do instead?

Course

ai-dev-tools-zoomcamp

Question

Module 2's homework (Q6) suggests asking your agent to use the browser to verify
the frontend-backend connection. I did that. It ran npx playwright install, the
download succeeded, and the Chromium binary is confirmed present on disk — but
every attempt to actually navigate to a page fails. Why does an installed browser
fail to launch, and what should I do if my agent's environment can't fix it?

Answer

Root cause: Playwright has two separate install steps, and only the first one
works without root.

1. npx playwright install chromium downloads the browser binaries into a
   user-writable cache directory. No root needed — this is the step that
   succeeded for you.
2. npx playwright install --with-deps chromium additionally invokes the distro
   package manager (apt-get on Debian/Ubuntu) to install the OS-level shared
   libraries Chromium dynamically links against — NSS/crypto, graphics/GBM,
   font, and audio libraries a desktop install has but a slim container generally
   doesn't. Installing system packages needs root. If your agent runs in a
   sandbox without sudo, this step can't complete.

So the binary exists and is executable, but the dynamic loader can't resolve its
dependencies. Playwright's own launch error names the specific missing
libraries directly — read that list from your own error output rather than
copying one from a FAQ, since exact names vary by distro and Playwright
version.

What to do, in order of preference:

1. Check whether your environment can actually install them. If id -u
   returns 0 or sudo -n true succeeds, just run
   npx playwright install --with-deps chromium. If you control the container,
   Playwright's official Docker images ship the browsers and system deps
   preinstalled.
2. Run the browser check outside the agent's sandbox. The homework allows
   manual verification — start both servers, open the frontend yourself, click
   through, watch the Network tab. Least effort, and a genuinely real browser
   check.
3. Otherwise, verify at the HTTP contract level and say so explicitly. The
   thing a browser adds over curl that matters most is CORS enforcement —
   exercise it directly by sending the Origin header the browser would send
   (substitute your own ports/routes):

   curl -i -X OPTIONS http://localhost:8000/api/teams \
     -H "Origin: http://localhost:5173" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: content-type"

   curl -i -X POST http://localhost:8000/api/teams \
     -H "Origin: http://localhost:5173" \
     -H "Content-Type: application/json" \
     -d '{"name": "Example"}'

Check the response carries an access-control-allow-origin header matching
your frontend's origin — a missing one is the most common "works in curl,
breaks in the browser" cause. Pair this with a type-check of your frontend's
API client (npx tsc --noEmit or npx tsc -b) to catch request/response
shape drift.

One caveat: this is weaker than a browser test — it doesn't exercise
rendering or client-side routing. If your agent falls back to it, make sure it
tells you a real browser navigation never happened, rather than reporting it as
a browser verification.

Checklist

• I have searched existing FAQs and this question is not already answered
• The answer provides accurate, helpful information
• I have included any relevant code examples or links

Start by reviewing the existing FAQ structure and nearby entries, then check that this question is not duplicated. Preserve the explanation of browser binaries versus OS dependencies, the installation and curl examples, the TypeScript check, and the caveat that HTTP checks are not browser verification. Done means the FAQ is accurate, actionable, and clearly distinguishes fallback verification from real navigation.