From 8c51b41d8043da610d0445b2e0eec28246e4d1d9 Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Sun, 10 May 2026 10:22:10 +0000 Subject: [PATCH] docs(agent-runtime): add Playwright/browser system libs known limitation Backfill of molecule-core#275 (infra-lead-agent). The base molecule-ai-workspace-runtime image (python:3.11-slim + Node.js 22) does not include Chromium system libs (libnss3, libatk-bridge2.0-0, etc.) to avoid inflating the image by ~200-250 MB. Documents the user-visible error when running playwright from in-container, the recommended CI-based E2E workflow, and the role-specific adapter template workaround. Closes molecule-core#275. Co-Authored-By: Documentation Specialist --- .../docs/agent-runtime/workspace-runtime.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/content/docs/agent-runtime/workspace-runtime.md b/content/docs/agent-runtime/workspace-runtime.md index fa59694..f8840a6 100644 --- a/content/docs/agent-runtime/workspace-runtime.md +++ b/content/docs/agent-runtime/workspace-runtime.md @@ -274,6 +274,28 @@ Each workspace exposes an A2A server, builds an Agent Card, and registers with t But the long-term collaboration model remains direct workspace-to-workspace communication via A2A. +## Known Limitations + +### Playwright / browser system libs are not installed + +The base `molecule-ai-workspace-runtime` image is built on `python:3.11-slim` with Node.js 22, git, and `gh` — about 500 MB. It deliberately **does not** include the system libraries Chromium needs (`libnss3`, `libatk-bridge2.0-0`, `libxkbcommon0`, `libcups2`, `libdrm2`, `libxcomposite1`, `libxdamage1`, `libxrandr2`, `libgbm1`, `libpango-1.0-0`, `libasound2`, etc.). Adding them would inflate the image by ~200–250 MB (~40%) for every workspace, even though only frontend / QA workspaces ever launch a browser. + +Practical consequences: + +- `npx playwright test` (and any other Chromium-driven E2E tooling) **will fail at browser launch** when run from inside an in-container workspace agent. +- The error surface is missing-shared-object messages such as `error while loading shared libraries: libnss3.so` or `Host system is missing dependencies to run browsers`. +- Unit and integration tests (Vitest, Jest, etc.) that don't spawn a real browser are unaffected. + +Recommended workflow: + +1. **Run E2E in CI**, not in-container. The Gitea Actions self-hosted runner (and GitHub Actions runners used by mirror repos) has the full Playwright dep set installed and is the supported surface for E2E. Push a branch, let CI run the suite. +2. **Local debugging** of a single failing spec is best done on a developer laptop with `npx playwright install-deps` run once. +3. **In-container iteration** on test logic itself is fine — write specs, lint them, type-check them — just don't expect `playwright test` to actually launch a browser. + +If a particular workspace role genuinely needs in-container E2E (a dedicated QA template, for instance), the right place to layer Playwright deps is in a **role-specific adapter template image** that does `FROM molecule-ai-workspace-runtime:` and adds `RUN npx playwright install-deps`. Open a request against `molecule-ai-workspace-runtime` if you need this template stamped. + +Tracking issue: [molecule-ai/molecule-app#7](https://git.moleculesai.app/molecule-ai/molecule-app/issues/7). + ## Related Docs - [Agent Runtime Adapters](./cli-runtime.md) -- 2.52.0