@radhya/mach 2.6.11 → 2.7.0

package/README.md

@@ -67,7 +67,7 @@ mach build --platform web # Flutter projects
 | `mach audit`               | Check project health, delivery impact, and security locally         |
 | `mach agent`               | Manage the local device discovery agent for Install Hub            |
 | `mach host`                | Set up S3 static hosting and CloudFront                            |
-| `mach web`                 | Deploy and manage static web releases through Mach Web Hosting     |
+| `mach web`                 | Deploy, test, and manage static web releases through Mach Web Hosting |
 | `mach sitemap`             | Generate sitemap.xml from Expo Router app routes                   |
 | `mach deeplink`            | Configure and verify universal links and Android App Links         |
 
@@ -182,6 +182,64 @@ always point to Production for now:
 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 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, traces,
+and browser output stay local.
+
+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
+# 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. 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
 
 Mach's E2E testing layer is being implemented to run Maestro without requiring Maestro Cloud: