@radhya/mach 2.6.12 → 2.7.0

package/README.md

@@ -185,29 +185,60 @@ mach web domain add --domain www.customer.com
 ## Local Playwright Web E2E Testing
 
 `mach web test` runs Playwright from the current project on the developer's
-machine or the project's existing CI runner. It never starts a Mach browser
+machine or the project's existing CI runner. It creates a tenant-scoped
+`Playwright · Web · Local` entry in Mach **Test Runs**, where it shares the
+same history and detail screen as Maestro. It never starts a Mach browser
 runner, creates a billable test run, uploads test source or artifacts, or sends
-environment variables to Mach. Browser CPU time, reports, screenshots, and
-traces stay local.
+environment variables to Mach. Browser CPU time, reports, screenshots, traces,
+and browser output stay local.
 
-Install Playwright as a project development dependency once, then install only
-the browser you intend to test first (Chromium is the recommended default):
+The first run automatically adds `@playwright/test` to the project using its
+existing package manager and ensures local Chromium is available. That is a
+one-time local dependency/browser download, not Mach infrastructure. Use a
+different browser when needed:
 
 ```bash
-npm install --save-dev @playwright/test
-npx playwright install chromium
-
-# Mach runs the project's existing Playwright configuration locally.
+# Mach runs the project's Playwright configuration locally and records the
+# safe status/timing outcome in the dashboard.
 mach web test
 mach web test --project chromium --trace on-first-retry
 mach web test --base-url https://staging.example.com
+mach web test --install-browser firefox
 ```
 
 `--base-url` sets `PLAYWRIGHT_BASE_URL`; use that variable in the project's
 `playwright.config.ts`. For local applications, Playwright's own `webServer`
-setting should start and wait for the project server. Use
-`mach web test --install-browser chromium` only when you deliberately want to
-download a browser on that machine.
+setting should start and wait for the project server. The first setup saves
+`@playwright/test` in the project's development dependencies; commit that
+package-manager lockfile. Later local and CI runs use the normal project
+install, rather than adding the dependency again. Mach checks the Chromium
+installation on each run, but Playwright skips the download when it is already
+in its browser cache. On short-lived Linux CI runners, cache
+`~/.cache/ms-playwright` to avoid the initial browser download for every fresh
+worker. Use `--no-setup` only in a pre-provisioned CI image to prevent any
+dependency or browser installation.
+
+### Keep CI web tests fast
+
+- Commit `package.json` and the matching npm, pnpm, or Yarn lockfile after the
+  initial setup. Let the pipeline use its normal frozen dependency install;
+  never add Playwright during every job.
+- Cache both the package-manager store and Playwright's browser directory. On
+  Linux runners the browser cache is `~/.cache/ms-playwright`; key both caches
+  from the dependency lockfile so a Playwright upgrade gets a compatible
+  browser automatically.
+- Run one browser project for the fast validation path, for example
+  `mach web test --project chromium`. Use a separate scheduled or release
+  job for cross-browser coverage.
+- Keep CI headless. Avoid `--headed`, `--ui`, and `--debug` in pipelines;
+  use `--trace on-first-retry` rather than recording traces for every passing
+  test.
+- Match `--workers` to the runner capacity. Start with `--workers 2` on a
+  two-core runner and increase it only when tests remain stable. Use `--grep`
+  or explicit test files for a focused pull-request check, then keep the full
+  suite for the main branch or release gate.
+- Keep `--no-setup` for a deliberately pre-built image. With normal caches,
+  the default setup check is fast and protects a newly provisioned runner.
 
 ## Managed Maestro Testing