cdk-nextjs 0.7.7 → 0.7.9

package/scripts/e2e-harness/README.md

@@ -6,9 +6,10 @@ write, because the tests were written by the people who define the behavior.
 
 `examples/e2e-tests/` remains the per-commit gate on all four `NextjsType`s. This
 is the scheduled one — every sixth day of the month at 14:00 UTC, so the day of
-the week drifts — on `NextjsGlobalFunctions` only. The other three run by
-`workflow_dispatch` (its `nextjs_type` input) or by hand; see "Running on the
-other `NextjsType`s".
+the week drifts — on all four types in one run, `NextjsGlobalFunctions` first
+(see "Sharding"). A `workflow_dispatch` runs one type (its `nextjs_type` input,
+`NextjsGlobalFunctions` by default) or `all`; see "Running on the other
+`NextjsType`s".
 
 What has actually been run, what failed, and whether each failure is a bug or
 acceptable: [`docs/harness-coverage.md`](../../docs/harness-coverage.md).
@@ -26,7 +27,8 @@ acceptable: [`docs/harness-coverage.md`](../../docs/harness-coverage.md).
 | `scripts/e2e-harness/common.sh`     | Shared file names, stack naming, output reads, and the tag check that gates every delete.                          |
 | `.github/actions/build-nextjs`      | Checks out and builds vercel/next.js. The cache-miss path, shared by the `nextjs` job and a shard's fallback.      |
 | `test/deploy-tests-manifest.json`   | Which next.js test files run (`NEXT_EXTERNAL_TESTS_FILTERS`).                                                      |
-| `.github/workflows/e2e-harness.yml` | Every six days + `workflow_dispatch`. A matrix of `shard_total` jobs, one stack each.                              |
+| `test/harness-smoke-manifest.json`  | One file every type passes, for checking the workflow itself in about an hour (`test_filters`).                    |
+| `.github/workflows/e2e-harness.yml` | Every six days (all four types) + `workflow_dispatch`. A matrix of (type, shard) jobs, one stack each.             |
 
 ## One shared stack, not one per test file
 
@@ -36,8 +38,8 @@ one deployment — every file genuinely has different code to ship. What there i
 way to do is ship it into infrastructure that already exists.
 
 Every test file in a run deploys into the same stack (`hrns-shared` by default,
-`hrns-shard-<n>` under the workflow's matrix — see "Sharding" below) with
-`cdk deploy --hotswap-fallback`. Creating and propagating the CloudFront
+`hrns-shard-<n>`, with the type's infix, under the workflow's matrix — see
+"Sharding" below) with `cdk deploy --hotswap-fallback`. Creating and propagating the CloudFront
 distribution costs ~4 minutes once per stack; every test file reuses it. That is
 the whole saving, and it is most of the cost of a run.
 
@@ -141,9 +143,31 @@ of them at once locally" — and delete it afterwards with
 
 A stack holds one app at a time, so the only way to run two test files at once is
 to give them two stacks. `HARNESS_SHARED_STACK_SUFFIX` is that knob, and
-`.github/workflows/e2e-harness.yml` turns it into a matrix: `shard_total` jobs
-(10 by default), each with a shared stack named `hrns-shard-<n>` and each running
-its own slice of the file list.
+`.github/workflows/e2e-harness.yml` turns it into a matrix of (type, shard) jobs:
+`shard_total` per type (by default 15 for Global Containers, whose ~4.3 minutes a
+file do not fit 10 shards into the run step's cap, and 10 for the others), each
+with a shared stack named `hrns-shard-<n>` (with the type's infix) and each
+running its own slice of that type's file list.
+
+A run of one type starts all its shards at once. A run of `all` (the schedule)
+lists 45 jobs, Global Functions first, then Regional Functions, Regional
+Containers and Global Containers, and runs at most 10 at a time, which is about 11
+hours end to end (about 95 shard-hours: Global Containers' 15 shards take about
+2.5 hours each, the others about 2; the shards of one type end together, so the
+last five Global Containers shards run with half the slots idle). Ten is the peak
+a single-type run of the other three already reaches: no more CloudFront
+distributions at once than a Global Functions run, under the CloudFront
+response-headers-policy quota (3 per distribution), no more ECR pulls than a
+Regional Containers run, and no more of the org's concurrent jobs than the
+schedule has always taken. A slot goes to the next job as soon as one frees, so
+types overlap where one ends and the next begins; that is safe, because no two
+entries share a stack name. Results arrive in that order: a Global Functions
+regression shows up first, about 2 hours in.
+
+To check the workflow itself rather than compatibility, dispatch `all` with
+`shard_total: 1` and `test_filters: ../test/harness-smoke-manifest.json`: one
+file on each type, four jobs, about an hour (Global Containers' ~15-minute warm-up
+and its delete are most of it).
 
 The slice comes from next.js's own `run-tests.js -g <n>/<N>`, which splits
 **after** `NEXT_EXTERNAL_TESTS_FILTERS` has been applied — `run-tests.js` filters
@@ -158,9 +182,10 @@ prints per-file durations to build one from.
 
 Each shard is self-contained, which is what makes this safe:
 
-- `e2e-warm.sh` warms _its_ stack, so the ~4-minute distribution create is paid
-  once per shard but in parallel — the same ~4 minutes of wall clock however many
-  shards there are.
+- `e2e-warm.sh` warms _its_ stack, so the ~4-minute distribution create (Global
+  types only) is paid once per shard but in parallel — the same ~4 minutes of
+  wall clock however many shards start together (in an `all` run, once per wave
+  of 10 Global shards).
 - `e2e-sweep.sh --apply --shared` in an `always()` step deletes _its_ stack, since
   `--shared` resolves the same suffix. Nothing lowers the age floor account-wide,
   so one shard finishing early cannot delete another's stack out from under it.
@@ -179,9 +204,10 @@ workflow's `concurrency` group is what guarantees that, and it queues rather tha
 cancels. It is one group for every type, not one per type: each run's
 account-wide sweep could otherwise delete another type's idle-looking shard stack
 as that run warms into it. GitHub keeps only one _pending_ run per group, so
-dispatch a second type once the first has started, not while one is queued. A
-pending run that gets cancelled that way, the scheduled one included, loses no
-sweep: every run sweeps, not just the scheduled one.
+dispatch a second type once the first has started, not while one is queued, or
+dispatch `all`. A dispatch on a schedule day waits behind the schedule's ~11
+hours. A pending run that gets cancelled that way, the scheduled one included,
+loses no sweep: every run sweeps, not just the scheduled one.
 
 ## Caching the next.js build
 
@@ -239,8 +265,9 @@ the `v1` in it to discard every entry). Two things to know:
   comparing against is whatever the other workflows are using at the time.
 - **The Playwright _browser_ is cached; its system libraries are not.** Those are
   apt packages outside any cacheable path, so
-  `playwright install --with-deps chromium` still runs in each shard. It is a
-  no-op for the download on a hit.
+  `scripts/playwright-install-deps.sh` (`playwright install-deps chromium`)
+  still runs in each shard. It caps and retries each attempt, because apt on its
+  own can hang on a stalled mirror until the job times out.
 
 A `workflow_dispatch` from a branch writes to that branch's own cache scope, so
 the first dispatched run on a new branch pays the build once. It can still _read_
@@ -275,16 +302,16 @@ last. A session that must have its own working tree wants a `git worktree` _and_
 its own next.js checkout _and_ its own stack suffix; three of those is usually the
 point at which running one at a time is the cheaper answer.
 
-## Why the schedule runs `NextjsGlobalFunctions`
+## Why `NextjsGlobalFunctions` is the default
 
-All four types run (see "Running on the other `NextjsType`s"); the schedule picks
-one. The harness builds every request URL as `new URL(path, deploymentUrl)` —
-`getFullUrl` in `test/lib/next-test-utils.ts` assigns `pathname` outright — so any
-prefix in the deployment URL is dropped. `NextjsRegionalFunctions`'s API Gateway
-REST URL always ends in `/<stage>`, so it runs behind `stage-proxy.mjs`, a local
-proxy that puts the stage back (see "Running on `NextjsRegionalFunctions`") — a
-second front door, not the one users deploy. A CloudFront distribution is served
-at the origin root.
+All four types run on the schedule (see "Sharding"); this one runs first, and is
+what a dispatch runs unless told otherwise. The harness builds every request URL
+as `new URL(path, deploymentUrl)` — `getFullUrl` in `test/lib/next-test-utils.ts`
+assigns `pathname` outright — so any prefix in the deployment URL is dropped.
+`NextjsRegionalFunctions`'s API Gateway REST URL always ends in `/<stage>`, so it
+runs behind `stage-proxy.mjs`, a local proxy that puts the stage back (see
+"Running on `NextjsRegionalFunctions`") — a second front door, not the one users
+deploy. A CloudFront distribution is served at the origin root.
 
 It is also the front door the suite was written for. `NEXT_TEST_MODE=deploy` is
 the mode Vercel validates edge-fronted deployments with, so its tests tolerate a
@@ -308,17 +335,18 @@ Two caveats worth knowing before reading a failure as a regression:
   limitation documented at `src/nextjs-distribution.ts`. A test that varies on a
   header outside that list can be served a wrong cached response. That is a real
   product limitation, not a harness artifact — and not a regression either.
-- The other three types are not on the schedule; see "Running on the other
-  `NextjsType`s". `examples/e2e-tests` is the per-commit gate on all three.
+- The schedule runs the other three types too, after this one, so their results
+  land hours later in the same run; see "Sharding".
 
 ## Running on the other `NextjsType`s
 
 `HARNESS_NEXTJS_TYPE` picks the root construct: `global-functions` (the default),
 `regional-functions`, `global-containers` or `regional-containers`. Each type but
 the default gets a stack infix of its own — `hrns-rf-*`, `hrns-gc-*`,
-`hrns-rc-*` — so no run can deploy into another type's stack. In CI, runs of two
-types still queue behind each other (see "Sharding"). The workflow's
-`nextjs_type` input sets it for every shard.
+`hrns-rc-*` — so no run can deploy into another type's stack, and shards of all
+four types can share one run. In CI, two *runs* still queue behind each other
+(see "Sharding"). The workflow's `nextjs_type` input sets the type, or `all`
+runs every type, as the schedule does.
 
 ```bash
 ADAPTER_DIR=$PWD HARNESS_NEXTJS_TYPE=global-containers ./scripts/e2e-warm.sh
@@ -396,7 +424,7 @@ reason alone.
 
 `HARNESS_NEXTJS_TYPE=regional-functions` deploys `NextjsRegionalFunctions`
 instead, into `hrns-rf-<suffix>` stacks so it can never land in a Global run's.
-By hand or `workflow_dispatch`; the schedule runs `NextjsGlobalFunctions` only.
+By hand, by `workflow_dispatch`, or on the schedule with the other three types.
 
 The stage is the whole problem, and `stage-proxy.mjs` is the whole answer. The
 suite discards any path in the deployment URL (above), and a REST API's is always
@@ -464,7 +492,8 @@ To check one candidate by hand instead:
 ```bash
 # in the next.js checkout, against the fixture root (usually the test file's dir
 # or its parent)
-find <fixture> -name "middleware.*"
+# a middleware.* is edge unless it sets `runtime: "nodejs"` in its config
+find <fixture> -name "middleware.*" -exec grep -LE "runtime\s*:\s*.nodejs." {} +
 grep -rlE "runtime\s*[:=]\s*.(experimental-)?edge." <fixture>
 ```
 
@@ -476,7 +505,7 @@ Mind the "or its parent": for a `test/e2e/<name>/test/index.test.ts` the fixture
 lives a directory _above_ the test file, and screening only the test file's own
 directory quietly misses its `middleware.js`.
 
-Six more screens are worth running before spending a deploy on a candidate, all
+Seven more screens are worth running before spending a deploy on a candidate, all
 against the test file rather than the fixture:
 
 - `skipDeployment: true` in the `nextTestSetup` call — next.js replaces the whole
@@ -484,6 +513,13 @@ against the test file rather than the fixture:
   early-returns (`test/lib/e2e-utils/index.ts`). The costliest screen to have been
   missing: it accounts for a third of what was previously counted as the candidate
   pool, and two files reached `rules.include` on the strength of a 4s "pass".
+- `// @force-gate <expr>` on every top-level `describe`, where `<expr>` is false
+  in deploy mode — next.js 16.4's spelling of the same exclusion, which replaced
+  most `skipDeployment: true` calls. A gated-out suite is skipped, so a file whose
+  every suite is gated out "passes" having deployed nothing. `screen.mjs`
+  evaluates the expression with the harness's own conditions (`deploy`,
+  `adapter`, `turbopack`); one it cannot know up front (`cacheComponents`) never
+  disqualifies, and a file with one suite left still deploys it.
 - `describe.skip` / `(isNextDev ? describe : describe.skip)` — a file skipped
   upstream reports as passing in a few seconds without deploying anything, and
   adding it to `rules.include` claims coverage that does not exist. This screen
@@ -521,7 +557,8 @@ pass.
 each screen, and how many are already included. Regenerate it with `--write`
 whenever `next` is upgraded; `--check` exits nonzero if it has drifted, which is
 the only thing that keeps those numbers worth quoting. The workflow runs it in
-shard 1 of every run against the default next.js ref.
+the first job of every run against the default next.js ref (Global Functions
+shard 1 in an `all` run).
 
 Passing every screen makes a file a _candidate_, not a pass. It still has to
 be deployed and watched, and anything that fails gets root-caused and given a

package/scripts/e2e-harness/screen.mjs

@@ -17,7 +17,8 @@
  *
  * - **edge / middleware** — cdk-nextjs throws during `next build` for any
  *   non-`nodejs` runtime (`assertNodeRuntimes`), so the fixture is unbuildable
- *   and no per-case `failed` entry can rescue it.
+ *   and no per-case `failed` entry can rescue it. A `middleware.*` counts as
+ *   edge, its default, unless it opts into `runtime: "nodejs"`.
  * - **skipped-upstream** — `describe.skip`, so the file reports "passing" in
  *   seconds without deploying anything. Adding it claims coverage that does not
  *   exist. This one over-reports, because the match is textual and some skips are
@@ -30,6 +31,10 @@
  *   The costliest screen to have been missing — it covers 236 of what were
  *   otherwise counted as candidates, and two files had already been added to
  *   `rules.include` on the strength of a 4s "pass".
+ * - **force-gate** — next.js 16.4's spelling of `skipDeployment`:
+ *   `// @force-gate !deploy` on a `describe`, which skips the suite. Only a file
+ *   whose every top-level suite is gated out in deploy mode is disqualified,
+ *   since one that keeps a suite still deploys it.
  * - **mode-gated** — the third spelling of the same trap, and the one that cost a
  *   deploy slot to find: the file's real cases sit inside `if (isNextStart)` or
  *   `if (isNextDev)`, and every other mode gets an empty
@@ -75,6 +80,11 @@ const TEST_RE = /\.test\.[tj]sx?$/;
  * first undercounts by ~17 files.
  */
 const EDGE_RUNTIME_RE = /runtime\s*[:=]\s*['"](experimental-)?edge['"]/;
+/** A middleware file's opt-in to the Node runtime: `config = { runtime: "nodejs" }`. */
+const NODE_RUNTIME_RE = /runtime\s*:\s*['"]nodejs['"]/;
+/** `source` less its comments, so a commented-out opt-in doesn't count. */
+// A block comment only where a line starts one: `/*` is common inside a matcher.
+const withoutComments = (source) => source.replace(/^\s*\/\*[\s\S]*?\*\/|(^|[^:])\/\/.*$/gm, "$1");
 /**
  * An empty `it('should skip …', () => {})` — next.js's stub for the modes a
  * mode-gated file does not cover. `dev` in the title means dev is the excluded
@@ -83,6 +93,124 @@ const EDGE_RUNTIME_RE = /runtime\s*[:=]\s*['"](experimental-)?edge['"]/;
 const MODE_GATED_STUB_RE =
   /it\(\s*(['"`])should skip (?!.*\bdev\b)[^'"`]*\1\s*,\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)/;
 
+/**
+ * The `test/lib/gate/conditions.ts` values the harness runs under:
+ * `NEXT_TEST_MODE=deploy`, `IS_TURBOPACK_TEST=1` and `NEXT_ENABLE_ADAPTER=1`
+ * (`.github/workflows/e2e-harness.yml`), and none of the other env flags. A
+ * condition missing here (`cacheComponents`, read off the fixture's config) is
+ * unknown, which never disqualifies.
+ */
+const DEPLOY_GATE_CONDITIONS = {
+  mode: "deploy",
+  dev: false,
+  start: false,
+  deploy: true,
+  prod: true,
+  prefetching: true,
+  bundler: "turbopack",
+  turbopack: true,
+  rspack: false,
+  webpack: false,
+  adapter: true,
+  nodeMiddleware: false,
+  standaloneOutput: false,
+  turbopackDev: false,
+  turbopackBuild: false,
+  react18: false,
+  wasm: false,
+  FIXME: false,
+  TODO: false,
+};
+
+/**
+ * A `@force-gate` expression (`test/lib/gate/expr.ts`'s grammar: `!`, `&&`,
+ * `||`, `==`/`!=`/`===`/`!==`, parentheses, names, quoted strings, booleans)
+ * under {@link DEPLOY_GATE_CONDITIONS}: `true`, `false`, or `undefined` when it
+ * turns on a condition that isn't known up front.
+ */
+function evaluateGate(source) {
+  const tokens = source.match(/&&|\|\||[!=]==?|[!()]|'[^']*'|"[^"]*"|[A-Za-z_$][\w$]*/g) ?? [];
+  let i = 0;
+  // Condition values are coerced by truthiness, as next.js does (`mode` is a string).
+  const truth = (value) => (value === undefined ? undefined : Boolean(value));
+  const and = (a, b) => {
+    const [x, y] = [truth(a), truth(b)];
+    return x === false || y === false ? false : x && y ? true : undefined;
+  };
+  const or = (a, b) => {
+    const [x, y] = [truth(a), truth(b)];
+    return x === true || y === true ? true : x === false && y === false ? false : undefined;
+  };
+  const primary = () => {
+    const token = tokens[i++];
+    if (token === "(") {
+      const value = expression();
+      i++; // ")"
+      return value;
+    }
+    if (token === "!") {
+      const value = primary();
+      return value === undefined ? undefined : !value;
+    }
+    if (token === "true" || token === "false") return token === "true";
+    if (/^['"]/.test(token)) return token.slice(1, -1);
+    return Object.hasOwn(DEPLOY_GATE_CONDITIONS, token) ? DEPLOY_GATE_CONDITIONS[token] : undefined;
+  };
+  const binary = () => {
+    let left = primary();
+    while (/^[!=]==?$/.test(tokens[i] ?? "")) {
+      const negate = tokens[i++].startsWith("!");
+      const right = primary();
+      left = left === undefined || right === undefined ? undefined : (left === right) !== negate;
+    }
+    return left;
+  };
+  // `&&` and `||` share one precedence level, left to right, as in expr.ts.
+  const expression = () => {
+    let left = binary();
+    while (tokens[i] === "&&" || tokens[i] === "||") {
+      const op = tokens[i++];
+      const right = binary();
+      left = op === "&&" ? and(left, right) : or(left, right);
+    }
+    return left;
+  };
+  return truth(expression());
+}
+
+/**
+ * Whether `@force-gate` pragmas skip every top-level suite in `text` under
+ * deploy mode. next.js 16.4 moved deploy exclusions from
+ * `nextTestSetup({ skipDeployment: true })` to `// @force-gate !deploy` on the
+ * suite, and a gated-out suite is skipped rather than failed: a file whose every
+ * suite is gated out reports a pass having deployed nothing, the
+ * `skipDeployment` trap again. A file with one suite left still deploys it, so
+ * it stays a candidate.
+ */
+function forceGatedOutOfDeploy(text) {
+  const lines = text.split("\n");
+  // The outermost suites, a top-level `it`/`test` among them: column 0 usually,
+  // but some files declare theirs inside a loop (`filesystem-cache` does, in a
+  // `for (const cacheEnabled of …)`). A `.skip` or `.todo` never runs, so it is
+  // no suite left to deploy.
+  const indentOf = (line) => /^(\s*)(?:describe|it|test)\b(?!\.(?:skip|todo)\b)/.exec(line)?.[1].length;
+  const outer = Math.min(...lines.flatMap((line) => indentOf(line) ?? []));
+  let suites = 0;
+  let gatedOut = 0;
+  for (let index = 0; index < lines.length; index++) {
+    if (indentOf(lines[index]) !== outer) continue;
+    suites++;
+    for (let above = index - 1; above >= 0 && /^\s*\/\//.test(lines[above]); above--) {
+      const pragma = /^\s*\/\/\s*@force-gate\s+(.+?)\s*$/.exec(lines[above]);
+      if (pragma && evaluateGate(pragma[1]) === false) {
+        gatedOut++;
+        break;
+      }
+    }
+  }
+  return suites > 0 && gatedOut === suites;
+}
+
 const args = process.argv.slice(2);
 const flag = (name) => args.includes(`--${name}`);
 const value = (name) => {
@@ -175,7 +303,15 @@ function screen(testFile, decided = []) {
   const fixture = walk(fixtureRoot(testFile));
   const sources = fixture.filter((p) => SOURCE_RE.test(p));
 
-  if (fixture.some((p) => /\/middleware\.[tj]sx?$/.test(p))) {
+  // `middleware.*` builds for the edge runtime unless it exports
+  // `config = { runtime: "nodejs" }`, which cdk-nextjs deploys like `proxy.*`.
+  if (
+    fixture.some(
+      (p) =>
+        /\/middleware\.[tj]sx?$/.test(p) &&
+        !NODE_RUNTIME_RE.test(withoutComments(read(p))),
+    )
+  ) {
     reasons.push("middleware");
   }
   if (sources.some((p) => EDGE_RUNTIME_RE.test(read(p)))) reasons.push("edge");
@@ -189,13 +325,18 @@ function screen(testFile, decided = []) {
   // early-returns, and jest reports it as passing in ~4s having deployed
   // nothing. next.js declaring a file out of scope for deploy mode is the same
   // signal as `isNextDeploy`, just spelled in the setup call.
-  // Read through relative imports for this one screen only. `skipDeployment: true`
-  // in a shared helper replaces every file that calls it, so following the import
-  // cannot over-report; the mode gates above can, since a helper's `isNextDev`
-  // branch may cover only some of a file's cases.
-  if (/skipDeployment:\s*true/.test(testSourceText(testFile))) {
+  // Read through relative imports for this screen and the `@force-gate` one.
+  // `skipDeployment: true` in a shared helper replaces every file that calls it,
+  // so following the import cannot over-report; the mode gates above can, since a
+  // helper's `isNextDev` branch may cover only some of a file's cases. A helper's
+  // suites are the file's suites, so `@force-gate` counts them too.
+  const sourceText = testSourceText(testFile);
+  if (/skipDeployment:\s*true/.test(sourceText)) {
     reasons.push("skipDeployment");
   }
+  if (forceGatedOutOfDeploy(sourceText)) {
+    reasons.push("force-gate");
+  }
   // `test/e2e/**/test-template/{{ toFileName name }}/…` is a scaffold for
   // `pnpm new-test`, not a test.
   if (testFile.includes("{{")) reasons.push("scaffold");

package/scripts/playwright-install-deps.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+#
+# Installs Playwright's system packages (`playwright install-deps chromium`)
+# with apt network timeouts and bounded retries. CI only: it runs apt as root
+# and writes to /etc/apt/apt.conf.d. Run it from the directory whose
+# node_modules has Playwright, then install the browser itself unprivileged
+# with `playwright install chromium`.
+#
+# apt has no overall deadline: a mirror that stops answering partway through a
+# fetch can hang `apt-get update` indefinitely. On 2026-10-07 two harness
+# shards hung right after fetching noble-security InRelease, one for two hours.
+# Each attempt is capped and retried instead.
+#
+# The cap runs inside sudo, not around it. sudo starts its command in a new
+# session, so a `timeout` outside it kills sudo but not the apt-get under it,
+# which keeps holding /var/lib/apt/lists/lock and fails every retry on it.
+#
+# Usage: scripts/playwright-install-deps.sh
+
+set -euo pipefail
+
+ATTEMPTS="${PLAYWRIGHT_INSTALL_ATTEMPTS:-3}"
+# Normal runs take 15 s to 4 min (2026-10-07).
+ATTEMPT_TIMEOUT="${PLAYWRIGHT_INSTALL_TIMEOUT:-420}"
+
+sudo tee /etc/apt/apt.conf.d/99cdk-nextjs-timeouts > /dev/null << 'EOF'
+Acquire::Retries "3";
+Acquire::http::Timeout "30";
+Acquire::https::Timeout "30";
+EOF
+
+for attempt in $(seq 1 "$ATTEMPTS"); do
+  # sudo resets PATH; playwright's shim needs node.
+  if sudo env "PATH=$PATH" timeout --kill-after=30 "$ATTEMPT_TIMEOUT" \
+    ./node_modules/.bin/playwright install-deps chromium; then
+    exit 0
+  fi
+  echo "playwright-install-deps: attempt $attempt/$ATTEMPTS failed or exceeded ${ATTEMPT_TIMEOUT}s" >&2
+done
+exit 1