feat(eslint): add a Playwright concern covering specs and their config

README.md

@@ -33,6 +33,7 @@ and append Prettier last; pull individual concerns when you want finer control.
 | `eslint/react`              | React JSX/TSX components + hooks rules + jsx-a11y recommended (curated, anti-slop)                                                   |
 | `eslint/cloudflare-workers` | Workers runtime globals + no-Node-builtin guards                                                                                     |
 | `eslint/testing`            | Spec/fixture relaxations                                                                                                             |
+| `eslint/playwright`         | Playwright specs (recommended + curated matcher/diagnostic rules) and configs (mandatory action/navigation timeouts)                 |
 | `eslint/strict-size`        | Opt-in: promotes `max-lines` + `max-lines-per-function` from `warn` to `error` (append after a preset once the repo is under budget) |
 | `eslint/ignores`            | Shared build-artifact ignores                                                                                                        |
 | `eslint/globals`            | Raw globals maps (Workers + webGUI)                                                                                                  |
@@ -152,6 +153,50 @@ Layer it after the base/core concerns and before prettier.
 > rules are AST-based and React-version-independent, so they run on plain `.jsx`
 > with no type information.
 
+### Playwright
+
+```js
+import playwright from "@unraid/js-standards/eslint/playwright";
+```
+
+Two halves — the specs and the config that runs them.
+
+**Specs** (`**/*.{spec,test}.*`) get `eslint-plugin-playwright`'s recommended set
+(conditional logic in tests, forgotten `await` on assertions,
+`page.waitForTimeout` sleeps, focused/skipped tests left behind) plus a curated
+tier the plugin ships but leaves out of recommended, all at `error`: matcher
+choices that make a failure legible (`prefer-to-be`, `prefer-comparison-matcher`,
+…), `require-to-pass-timeout`, `no-commented-out-tests`, locator quality
+(`no-raw-locators`, `no-nth-methods`, `prefer-native-locators`,
+`no-get-by-title`), and structure (`require-hook`, `require-top-level-describe`,
+`no-slowed-test`).
+
+This states the target rather than the current state of any one suite. A repo
+adopting mid-stream downgrades specific rules in its own config, which keeps the
+exception visible and local instead of hidden in the shared baseline.
+
+Pure convention stays **off** — `prefer-lowercase-title` (style), `require-tags`
+and `no-restricted-*` (need a project vocabulary), `require-soft-assertions`
+(changes failure semantics), `max-expects` (an arbitrary budget), and `no-hooks`
+(contradicts `require-hook`).
+
+> The plugin's rules key off bare `test`/`expect` identifiers. In a repo that
+> also runs Vitest or Jest under that glob, re-scope `files` on the spec entry to
+> where Playwright actually owns — otherwise the rules give Playwright advice
+> about a unit test.
+
+**Configs** (`playwright*.config.*`) must set `use.actionTimeout` and
+`use.navigationTimeout` explicitly.
+
+Playwright defaults both to `0`, which means _no timeout_ rather than a sensible
+one. `expect()` has its own default, so a config that sets `expect.timeout` looks
+bounded — but that ceiling only covers assertions. A bare `.click()` or `.goto()`
+on an element that never becomes actionable waits for the entire test timeout.
+
+On a suite with a generous per-test budget that is a silent blackout: no output,
+no failing assertion, and a final error naming the test rather than the call that
+hung. Setting both turns it into a fast failure that names the locator.
+
 ## CSS conventions
 
 Prefer framework-native styles first: Vue/Nuxt component CSS belongs in

package.json

@@ -26,6 +26,7 @@
     "./eslint/react": "./src/eslint/react.js",
     "./eslint/cloudflare-workers": "./src/eslint/cloudflare-workers.js",
     "./eslint/testing": "./src/eslint/testing.js",
+    "./eslint/playwright": "./src/eslint/playwright.js",
     "./eslint/oxlint": "./src/eslint/oxlint.js",
     "./eslint/ignores": "./src/eslint/ignores.js",
     "./eslint/globals": "./src/eslint/globals.js",
@@ -57,6 +58,7 @@
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-oxlint": "^1.72.0",
+    "eslint-plugin-playwright": "^2.11.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-sonarjs": "^4.1.0",
     "eslint-plugin-unicorn": "^72.0.0",

src/eslint/globs.js

@@ -22,3 +22,18 @@ export const TOOLING_FILES = [
   "**/scripts/**",
   "eslint.config.*",
 ];
+
+/** Playwright config files, which carry their own timeout obligations. */
+export const PLAYWRIGHT_CONFIG_FILES = [
+  "**/playwright*.config.{ts,mts,cts,js,mjs,cjs}",
+];
+
+/**
+ * Playwright specs — mirrors Playwright's own default `testMatch`.
+ *
+ * The plugin's rules key off bare `test`/`expect` identifiers, so in a repo that
+ * also runs Vitest or Jest under this pattern, re-scope `files` on the spec entry
+ * to wherever Playwright actually owns (`e2e/**`, `**\/*.e2e.spec.ts`, …).
+ * Otherwise the rules give Playwright advice about a unit test.
+ */
+export const PLAYWRIGHT_SPEC_FILES = ["**/*.{spec,test}.{ts,tsx,js,mjs,cjs}"];

src/eslint/playwright.js

@@ -0,0 +1,167 @@
+/**
+ * Concern: Playwright. Two halves — the specs and the config that runs them.
+ *
+ * Specs get `eslint-plugin-playwright`'s recommended set (conditional logic in
+ * tests, forgotten `await` on assertions, `page.waitForTimeout` sleeps, skipped
+ * or focused tests left behind) plus a curated tier the plugin ships but leaves
+ * out of recommended.
+ *
+ * The config half exists because Playwright defaults `actionTimeout` and
+ * `navigationTimeout` to 0, meaning "no timeout" rather than a sensible one.
+ * `expect()` has its own default, so a config that sets `expect.timeout` looks
+ * bounded — but that ceiling only covers assertions. A bare `.click()` or
+ * `.goto()` on an element that never becomes actionable waits out the whole test
+ * budget, which on a long-running suite is a silent blackout: no output, no
+ * failing assertion, and a final error naming the test rather than the call that
+ * hung.
+ */
+import playwright from "eslint-plugin-playwright";
+
+import { PLAYWRIGHT_CONFIG_FILES, PLAYWRIGHT_SPEC_FILES } from "./globs.js";
+
+const REQUIRED_TIMEOUTS = ["actionTimeout", "navigationTimeout"];
+
+/** Reads a static property name, ignoring spreads and computed keys. */
+function propertyName(node) {
+  if (node.type !== "Property" || node.computed) return null;
+  if (node.key.type === "Identifier") return node.key.name;
+  if (node.key.type === "Literal") return String(node.key.value);
+  return null;
+}
+
+/** Finds a direct property of an object expression by name. */
+function findProperty(objectExpression, name) {
+  return objectExpression.properties.find(
+    (property) => propertyName(property) === name,
+  );
+}
+
+/**
+ * Unwraps the config object from `defineConfig({...})`, `export default {...}`,
+ * or a `satisfies`/`as` wrapper, so the rule reads the same shape either way.
+ */
+function configObject(node) {
+  let current = node;
+  while (current) {
+    if (
+      current.type === "TSSatisfiesExpression" ||
+      current.type === "TSAsExpression"
+    ) {
+      current = current.expression;
+      continue;
+    }
+    if (
+      current.type === "CallExpression" &&
+      current.callee.type === "Identifier" &&
+      current.callee.name === "defineConfig" &&
+      current.arguments.length > 0
+    ) {
+      current = current.arguments[0];
+      continue;
+    }
+    return current.type === "ObjectExpression" ? current : null;
+  }
+  return null;
+}
+
+const requireActionTimeouts = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require explicit actionTimeout and navigationTimeout in a Playwright config",
+    },
+    schema: [],
+    messages: {
+      missing:
+        "Playwright config does not set `{{name}}` in `use`. It defaults to 0 (no timeout), so a locator action on an element that never appears hangs for the entire test timeout instead of failing fast and naming the locator.",
+    },
+  },
+  create(context) {
+    return {
+      ExportDefaultDeclaration(node) {
+        const config = configObject(node.declaration);
+        if (!config) return;
+
+        const useProperty = findProperty(config, "use");
+        // A config with no `use` block at all still inherits both defaults, so
+        // report against the config object rather than skipping it.
+        const target =
+          useProperty && useProperty.value.type === "ObjectExpression"
+            ? useProperty.value
+            : null;
+
+        for (const name of REQUIRED_TIMEOUTS) {
+          if (target && findProperty(target, name)) continue;
+          context.report({
+            node: target ?? config,
+            messageId: "missing",
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};
+
+const configPlugin = {
+  meta: { name: "playwright-config" },
+  rules: { "require-action-timeouts": requireActionTimeouts },
+};
+
+const recommended = playwright.configs["flat/recommended"];
+
+/**
+ * Rules the plugin ships but leaves out of recommended.
+ *
+ * These are `error` on purpose. This package is the bar new work is written
+ * against, so the standard states the target rather than the current state of
+ * any one suite; a repo adopting mid-stream downgrades specific rules in its own
+ * config, which keeps the exception visible and local instead of hidden in the
+ * shared baseline.
+ *
+ * Left off deliberately, as pure convention rather than correctness:
+ * `prefer-lowercase-title` (style), `require-tags` and `no-restricted-*` (need a
+ * project-specific vocabulary), `require-soft-assertions` (changes failure
+ * semantics), `max-expects` (an arbitrary budget), and `no-hooks` (directly
+ * contradicts `require-hook` below).
+ */
+const CURATED_SPEC_RULES = {
+  // Matcher choice is diagnostic quality: `toBe(true)` reports "expected true,
+  // received false", while `toBeTruthy()` reports almost nothing useful.
+  "playwright/prefer-to-be": "error",
+  "playwright/prefer-to-contain": "error",
+  "playwright/prefer-comparison-matcher": "error",
+  "playwright/prefer-equality-matcher": "error",
+  "playwright/prefer-strict-equal": "error",
+  "playwright/require-to-throw-message": "error",
+  // An unbounded `toPass` is the same silent-blackout shape as an unbounded
+  // action: it retries until the test budget runs out.
+  "playwright/require-to-pass-timeout": "error",
+  "playwright/no-commented-out-tests": "error",
+  // Locator quality. A CSS or nth-based selector binds the test to markup
+  // structure, so it breaks on a refactor that changed nothing a user can see,
+  // and it reports "element not found" rather than naming the control.
+  "playwright/prefer-native-locators": "error",
+  "playwright/no-nth-methods": "error",
+  "playwright/no-raw-locators": "error",
+  "playwright/no-get-by-title": "error",
+  // Structure: shared setup belongs in a hook, and a spec should declare what it
+  // covers. `test.slow()` triples a budget instead of fixing what is slow.
+  "playwright/require-hook": "error",
+  "playwright/require-top-level-describe": "error",
+  "playwright/no-slowed-test": "error",
+};
+
+export default [
+  {
+    ...recommended,
+    files: PLAYWRIGHT_SPEC_FILES,
+    rules: { ...recommended.rules, ...CURATED_SPEC_RULES },
+  },
+  {
+    files: PLAYWRIGHT_CONFIG_FILES,
+    plugins: { "playwright-config": configPlugin },
+    rules: { "playwright-config/require-action-timeouts": "error" },
+  },
+];

test/playwright-action-timeouts.test.mjs

@@ -0,0 +1,80 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Linter } from "eslint";
+import playwrightConfigConcern from "../src/eslint/playwright.js";
+
+const linter = new Linter();
+// Select by rule identity, not position — the concern also ships a spec-file
+// entry, and which one comes first is not part of its contract.
+const concern = playwrightConfigConcern.find(
+  (entry) => entry.rules?.["playwright-config/require-action-timeouts"],
+);
+
+/** Lint a Playwright config body under the shipped concern's plugin and rules. */
+const lintConfig = (source) =>
+  linter.verify(source, {
+    plugins: concern.plugins,
+    rules: concern.rules,
+    languageOptions: { ecmaVersion: "latest", sourceType: "module" },
+  });
+
+const missingNames = (source) =>
+  lintConfig(source)
+    .map((message) => /`(\w+)`/.exec(message.message)?.[1])
+    .filter(Boolean);
+
+test("flags a config that sets neither timeout", () => {
+  // The exact shape that motivated this rule: expect() carries a ceiling, so the
+  // config looks bounded, while every bare .click() and .goto() is not.
+  const source = `
+    import { defineConfig } from "@playwright/test";
+    export default defineConfig({
+      timeout: 600000,
+      expect: { timeout: 60000 },
+      use: { baseURL: "http://localhost", viewport: { width: 1440, height: 900 } },
+    });
+  `;
+  assert.deepEqual(
+    missingNames(source).toSorted((left, right) => left.localeCompare(right)),
+    ["actionTimeout", "navigationTimeout"],
+  );
+});
+
+test("flags only the timeout that is absent", () => {
+  const source = `
+    import { defineConfig } from "@playwright/test";
+    export default defineConfig({
+      use: { actionTimeout: 15000 },
+    });
+  `;
+  assert.deepEqual(missingNames(source), ["navigationTimeout"]);
+});
+
+test("accepts a config that sets both timeouts", () => {
+  const source = `
+    import { defineConfig } from "@playwright/test";
+    export default defineConfig({
+      use: { actionTimeout: 15000, navigationTimeout: 30000 },
+    });
+  `;
+  assert.deepEqual(lintConfig(source), []);
+});
+
+test("flags a config with no use block, which still inherits both defaults", () => {
+  const source = `
+    import { defineConfig } from "@playwright/test";
+    export default defineConfig({ timeout: 600000 });
+  `;
+  assert.equal(lintConfig(source).length, 2);
+});
+
+test("reads a plain default-exported object, not just defineConfig", () => {
+  const source = `
+    export default { use: { actionTimeout: 15000, navigationTimeout: 30000 } };
+  `;
+  assert.deepEqual(lintConfig(source), []);
+});
+
+test("ignores a module that exports something other than a config object", () => {
+  assert.deepEqual(lintConfig(`export default function build() {}`), []);
+});