feather-testing-core 0.2.0 → 0.4.0

package/README.md

@@ -169,8 +169,26 @@ Every method returns `this` for chaining. A single `await` at the start of the c
 | `check(label)` / `uncheck(label)` | Toggle checkbox by label |
 | `choose(label)` | Select radio button by label |
 | `submit()` | Submit the most recently interacted form (see below) |
-| `upload(label, path)` | Set a file input (found by label) to the file at `path` |
+| `attachFile(label, path)` | Set a file input (found by label) to the file at `path` |
 | `dropFile(selector, path)` | Dispatch a `DataTransfer` drop of the file onto a drop area |
+| `pressKey(key)` | Press a key on the focused control — `'Enter'`, `'Escape'`, `'Control+A'` |
+| `hover(text)` | Hover the element with this text |
+
+`upload(label, path)` is the former name of `attachFile` and still works, deprecated.
+
+#### Interactions address controls **exactly**
+
+Every interaction above names the control it wants, and that name is matched in full: `clickButton("Check")` clicks the button named *Check*, never the sidebar chip named *"Checklist Run — checklist"*. Whitespace is still normalized, so multi-line markup and padded labels keep working.
+
+This matters because Playwright's bare-string matchers are case-insensitive *substring* matchers. Left as-is, a verb aimed at one control silently widens to any other control whose name merely contains the same text — and the run dies on a strict-mode violation that only appears when both are on screen at once, which turns a naming collision into an ordering-dependent flake. RTL matches whole strings by default, so with this both adapters answer the same question.
+
+Assertions are the deliberate exception: `assertText` / `refuteText` / `assertHas` ask *"does this text appear"*, so they stay substring matches. An exact `refuteText("Check")` would pass while *Checklist Run* is plainly on the page.
+
+To act on a control whose name is genuinely a prefix of another's, scope the lookup rather than loosening it:
+
+```ts
+await session.within("main", (s) => s.clickButton("Check"));
+```
 
 #### How `submit()` finds the submit button
 
@@ -186,7 +204,7 @@ If no form was previously interacted with, `submit()` throws an error.
 
 ```ts
 // Standard file input, found by its label
-await session.upload("Avatar", "fixtures/avatar.png");
+await session.attachFile("Avatar", "fixtures/avatar.png");
 
 // Custom drop area (drag-and-drop upload zones)
 await session.dropFile("#dropzone", "fixtures/report.pdf");
@@ -194,6 +212,10 @@ await session.dropFile("#dropzone", "fixtures/report.pdf");
 
 In Playwright, `dropFile` reads the real file and dispatches a `drop` event with a `DataTransfer`. In RTL (JSDOM has no filesystem), both verbs synthesize an empty `File` named after the path's basename — assert on the file name, not its contents.
 
+#### Keys
+
+`pressKey` names keys the Playwright way on both adapters: a single character types itself, a named key is `'Enter'` / `'Escape'` / `'ArrowDown'`, and modifiers combine with `+` (`'Control+A'`, `'Meta+Enter'`). The RTL adapter translates that to user-event's keyboard syntax, so one spec reads the same in both places. A prefix that is not `Control`, `Shift`, `Alt`, or `Meta` is rejected rather than typed as text.
+
 ### Assertions
 
 | Method | Description |
@@ -205,6 +227,7 @@ In Playwright, `dropFile` reads the real file and dispatches a `drop` event with
 | `assertOptions(label, [labels])` | Assert a select offers exactly these options, in order |
 | `assertHas(selector, opts?)` / `refuteHas(...)` | Assert element exists (Playwright only, see options below) |
 | `assertPath(path, opts?)` / `refutePath(path)` | Assert URL path (Playwright only, see options below) |
+| `assertDownload(filename, trigger, opts?)` | Assert `trigger` starts a download with this filename (Playwright only) |
 
 #### Form-state assertions
 
@@ -279,6 +302,47 @@ await session.assertPath("/search", { queryParams: { q: "hello", page: "1" } });
 await session.refutePath("/login");
 ```
 
+#### Downloads
+
+The wait has to be armed before the click that starts the download, so the triggering steps go in a callback — the same shape as `within()`:
+
+```ts
+await session
+  .visit("/exports")
+  .assertDownload("report.csv", (s) => s.clickButton("Export"))
+  .assertText("Export complete");
+```
+
+`filename` is matched against the browser's suggested filename, exactly for a string or by `test()` for a `RegExp`. `opts.timeout` bounds the wait for the download to start. This is browser-only: the RTL adapter throws a `BrowserOnlyVerbError`, wrapped by the chain into a `StepError` that names the step.
+
+### Waiting: `until(description, fn)`
+
+| Method | Description |
+|--------|-------------|
+| `until(description, fn, opts?)` | Poll `fn` until it returns something truthy, then continue |
+
+Tests wait for conditions, not for clocks. `until()` is the honest alternative to a sleep: it polls a predicate you write, and the **mandatory** description is what the trace prints, so a timeout names the thing you were waiting for instead of the mechanism you waited with.
+
+```ts
+await session
+  .visit("/exports")
+  .clickButton("Export")
+  .until("the export job reports done", ({ page }) =>
+    page.evaluate(() => window.__exportDone),
+  )
+  .assertText("Download ready");
+```
+
+The predicate receives the adapter context — `{ page, scope }` for Playwright, `{ user, container }` for RTL — and may be sync or async. `opts` takes `{ timeout, interval }` in ms; omit them to inherit the adapter's own budget (Playwright's `expect.poll`, RTL's `waitFor`).
+
+When the budget runs out, the chain trace says what you were waiting for:
+
+```
+>>> [FAILED] until: the export job reports done
+```
+
+The description is required at the call site, before the chain runs — a blank one throws immediately, because a step named `until: ` teaches a reader nothing. The `feather-testing/no-wait-for-timeout` lint rule (see [Lint plugin](#lint-plugin)) points at this verb, so "no sleeps" stops being a review convention and becomes a check.
+
 ### Scoping
 
 | Method | Description |
@@ -295,7 +359,7 @@ await session
   .assertText("Dashboard"); // back to full-page scope after within()
 ```
 
-### Escape hatch: `step(name, fn)`
+### Escape hatches: `step(name, fn)` and `raw(label, fn)`
 
 When you need something the DSL doesn't cover, queue a named custom step instead of abandoning the chain. The callback receives the adapter's context — `{ page, scope }` for Playwright, `{ user, container }` for RTL — and the name shows up in `StepError` output like any built-in step:
 
@@ -308,6 +372,26 @@ await session
   .assertText("Done (1)");
 ```
 
+`raw(label, fn)` goes one level lower: it hands over the driver itself — Playwright's `page`, RTL's scoped query object — with no context wrapper. Use it when you want the native API and nothing else:
+
+```ts
+await session
+  .visit("/board")
+  .raw("stub the clipboard", (page) =>
+    page.evaluate(() => navigator.clipboard.writeText("copied")),
+  )
+  .clickButton("Paste")
+  .assertText("copied");
+```
+
+Both hatches take a **mandatory** label and register as named steps, so a failure inside one still names intent:
+
+```
+>>> [FAILED] raw('stub the clipboard')
+```
+
+That is the whole point of having them: an untraced raw tail ends the trace at the last DSL verb, and no hatch at all pushes teams to abandon the DSL mid-spec. In Playwright, `raw` always hands over the page, not the `within()` scope — re-scoping is the caller's job once you have left the DSL.
+
 ### Debug
 
 | Method | Description |
@@ -391,18 +475,59 @@ The RTL adapter runs in JSDOM, which has no real browser. These methods are not
 - `visit()` — render the component directly instead
 - `assertPath()` / `refutePath()` — no URL in JSDOM
 - `assertHas()` / `refuteHas()` — RTL discourages CSS selectors; use `assertText()` instead
+- `assertDownload()` — JSDOM has no download machinery; it throws `BrowserOnlyVerbError` naming the verb and pointing at a Playwright spec
+
+The verbs JSDOM *can* honestly do, it does: `attachFile` synthesizes a `File` from the path's basename, `pressKey` translates to user-event's keyboard syntax, `hover` fires real pointer events, and `raw` hands over the scoped query object.
+
+### Extending the RTL adapter
+
+`RTLDriver` is meant to be subclassed when an app's markup needs a different lookup, so that a host harness binds *this* DSL rather than reimplementing it. Everything worth specializing is `protected`:
+
+| Member | Why you'd override it |
+|--------|----------------------|
+| `findField(label)` | The single label-addressed lookup. Every labelled verb — `fillIn`, `selectOption`, `check`, `uncheck`, `upload`, `assertValue`, `assertChecked`, `assertSelected`, `assertOptions` — goes through it, so one override retargets them all |
+| `scoped(element)` | Factory used by `within()`, so a scoped session keeps your driver's behaviour |
+| `user`, `root`, `container`, `lastFormElement`, `timeout` | Shared state the built-in verbs read and write |
+
+```ts
+class WrapperLabelDriver extends RTLDriver {
+  // Labels with no htmlFor, control is a sibling inside a wrapper div
+  protected override async findField(label: string): Promise<HTMLElement> {
+    for (const l of this.rootElement().querySelectorAll("label")) {
+      if (l.textContent?.trim() !== label) continue;
+      const control = l.parentElement?.querySelector("input, textarea, select");
+      if (control) return control as HTMLElement;
+    }
+    throw new Error(`no field labelled '${label}'`);
+  }
+
+  protected override scoped(element: HTMLElement) {
+    return new WrapperLabelDriver(this.user, element, this.timeout);
+  }
+}
+```
+
+The third constructor argument is a per-lookup timeout in ms; omit it to keep RTL's own default.
 
 ## Exports
 
 ```ts
 // Core (Session class + types)
-import { Session, StepError, type TestDriver } from "feather-testing-core";
+import {
+  Session,
+  StepError,
+  BrowserOnlyVerbError,
+  type TestDriver,
+} from "feather-testing-core";
 
 // Playwright adapter
 import { test, createSession, expect } from "feather-testing-core/playwright";
 
 // RTL adapter
 import { createSession } from "feather-testing-core/rtl";
+
+// ESLint plugin (see below)
+import featherTesting from "feather-testing-core/eslint-plugin";
 ```
 
 Both adapter subpaths also re-export `Session` and `StepError`, so you can import everything from a single path:
@@ -412,6 +537,54 @@ import { test, Session, StepError } from "feather-testing-core/playwright";
 import { createSession, Session, StepError } from "feather-testing-core/rtl";
 ```
 
+## Lint plugin
+
+The DSL can only offer good habits; a linter can insist on them. This package ships an ESLint plugin whose rules are the defect classes a real suite audit found by expensive reading — each one now a check that runs in a second, with a message that names the fix so whoever hits it (person or agent) learns the alternative from the error alone.
+
+```js
+// eslint.config.js — flat config
+import featherTesting from "feather-testing-core/eslint-plugin";
+
+export default [
+  {
+    files: ["tests/**/*.ts", "e2e/**/*.spec.ts"],
+    ...featherTesting.configs.recommended,
+  },
+];
+```
+
+Or wire the rules yourself:
+
+```js
+import featherTesting from "feather-testing-core/eslint-plugin";
+
+export default [
+  {
+    files: ["tests/**/*.ts"],
+    plugins: { "feather-testing": featherTesting },
+    rules: {
+      "feather-testing/no-weak-assertions": ["error", { matchers: ["toBeTruthy", "toBeDefined", "toBeFalsy"] }],
+    },
+  },
+];
+```
+
+| Rule | Catches | Points at |
+|------|---------|-----------|
+| `no-wait-for-timeout` | `page.waitForTimeout(...)`, and the `new Promise(r => setTimeout(r, n))` sleep idiom | `session.until(description, fn)`, `expect.poll`, web-first assertions |
+| `no-conditional-skip` | `test.skip(cond)`, `test.skip()`, `this.skip()` — a spec that un-tests itself at runtime | making the precondition part of the test, or `test.fixme` so the report names it |
+| `no-weak-assertions` | `expect(x).toBeTruthy()` / `.toBeDefined()` (configurable) | asserting the shape you mean |
+| `no-swallowed-cleanup-catch` | `.catch(() => {})` and empty `catch {}` blocks | asserting on the error, rethrowing with context, or annotating the deliberate ignore |
+| `warn-serial-mode` | `test.describe.serial(...)`, `configure({ mode: "serial" })` — warning, not error | independent tests, or an `eslint-disable` line saying why serial is required |
+
+Deliberate exceptions stay possible and stay visible: an `eslint-disable-next-line` comment with a reason is exactly the annotation these rules are trying to force.
+
+**Why these five.** They are not style preferences. Each one is a way a suite goes green while proving nothing: a sleep passes on a slow machine and fails on a fast one, a conditional skip silently un-tests a spec for its entire life, `toBeTruthy()` accepts almost any value, a swallowed cleanup error surfaces three tests later as something else, and serial mode turns one failure into a wall of red that hides its own cause. `session.until()` exists so the first rule has an honest alternative to point at — see [the document set](docs/document-set.md) for why conventions belong in executable form rather than in a style guide nobody re-reads.
+
+## Documentation
+
+- [The document set](docs/document-set.md) — the minimal set of documents a project needs, what each one answers, and why hand-maintained cross-reference matrices lose to generated reports plus CI checks.
+
 ## License
 
 MIT

package/dist/errors.d.ts

@@ -2,4 +2,12 @@ import type { QueuedStep } from "./types.js";
 export declare class StepError extends Error {
     constructor(failedStep: QueuedStep, allSteps: QueuedStep[], cause: unknown);
 }
+/**
+ * Thrown by an adapter asked for something only a real browser can do.
+ * A session wraps it in a StepError, so the chain trace names the verb that
+ * could not run and this message says why and what to do instead.
+ */
+export declare class BrowserOnlyVerbError extends Error {
+    constructor(verb: string, alternative: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,qBAAa,SAAU,SAAQ,KAAK;gBAEhC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,OAAO;CA4BjB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,qBAAa,SAAU,SAAQ,KAAK;gBAEhC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,OAAO;CA4BjB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAO9C"}

package/dist/errors.js

@@ -19,3 +19,15 @@ export class StepError extends Error {
         this.name = "StepError";
     }
 }
+/**
+ * Thrown by an adapter asked for something only a real browser can do.
+ * A session wraps it in a StepError, so the chain trace names the verb that
+ * could not run and this message says why and what to do instead.
+ */
+export class BrowserOnlyVerbError extends Error {
+    constructor(verb, alternative) {
+        super(`feather-testing-core: ${verb} is a browser-only verb — this adapter runs ` +
+            `in JSDOM, which has no browser to do it. ${alternative}`);
+        this.name = "BrowserOnlyVerbError";
+    }
+}

package/dist/eslint-plugin/index.d.ts

@@ -0,0 +1,18 @@
+import type { Linter, Rule } from "eslint";
+/**
+ * The defect classes an expensive suite audit found by reading, turned into
+ * checks. Every message names the fix, so an agent or a reviewer mid-task
+ * learns what to do from the error alone.
+ */
+export declare const rules: Record<string, Rule.RuleModule>;
+export declare const recommendedRules: Linter.RulesRecord;
+export interface FeatherTestingPlugin {
+    meta: {
+        name: string;
+    };
+    rules: Record<string, Rule.RuleModule>;
+    configs: Record<string, Linter.Config>;
+}
+declare const plugin: FeatherTestingPlugin;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/eslint-plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/eslint-plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAO3C;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,CAMjD,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,WAQrC,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,QAAA,MAAM,MAAM,EAAE,oBAIb,CAAC;AAQF,eAAe,MAAM,CAAC"}

package/dist/eslint-plugin/index.js

@@ -0,0 +1,37 @@
+import noWaitForTimeout from "./rules/no-wait-for-timeout.js";
+import noConditionalSkip from "./rules/no-conditional-skip.js";
+import noWeakAssertions from "./rules/no-weak-assertions.js";
+import noSwallowedCleanupCatch from "./rules/no-swallowed-cleanup-catch.js";
+import warnSerialMode from "./rules/warn-serial-mode.js";
+/**
+ * The defect classes an expensive suite audit found by reading, turned into
+ * checks. Every message names the fix, so an agent or a reviewer mid-task
+ * learns what to do from the error alone.
+ */
+export const rules = {
+    "no-wait-for-timeout": noWaitForTimeout,
+    "no-conditional-skip": noConditionalSkip,
+    "no-weak-assertions": noWeakAssertions,
+    "no-swallowed-cleanup-catch": noSwallowedCleanupCatch,
+    "warn-serial-mode": warnSerialMode,
+};
+export const recommendedRules = {
+    "feather-testing/no-wait-for-timeout": "error",
+    "feather-testing/no-conditional-skip": "error",
+    "feather-testing/no-weak-assertions": "error",
+    "feather-testing/no-swallowed-cleanup-catch": "error",
+    // Serial mode is sometimes genuinely required; a warning asks for the
+    // annotation rather than forbidding the choice.
+    "feather-testing/warn-serial-mode": "warn",
+};
+const plugin = {
+    meta: { name: "feather-testing" },
+    rules,
+    configs: {},
+};
+plugin.configs.recommended = {
+    name: "feather-testing/recommended",
+    plugins: { "feather-testing": plugin },
+    rules: recommendedRules,
+};
+export default plugin;

package/dist/eslint-plugin/rules/no-conditional-skip.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=no-conditional-skip.d.ts.map

package/dist/eslint-plugin/rules/no-conditional-skip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-conditional-skip.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/rules/no-conditional-skip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAqBnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UA6ChB,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/eslint-plugin/rules/no-conditional-skip.js

@@ -0,0 +1,56 @@
+const RUNNERS = new Set(["test", "it", "describe", "suite"]);
+/** The identifier a member chain like `test.describe.skip` starts from. */
+function rootIdentifier(node) {
+    let current = node;
+    while (current.type === "MemberExpression")
+        current = current.object;
+    return current.type === "Identifier" ? current.name : null;
+}
+/** `test.skip("name", fn)` is declarative — the report still lists it. */
+function isDeclarativeSkip(args) {
+    const [first] = args;
+    return (first !== undefined &&
+        (first.type === "Literal" || first.type === "TemplateLiteral"));
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Do not skip tests at runtime — a self-skipping spec is green while proving nothing",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            conditionalSkip: "A runtime skip un-tests this spec silently: the run stays green while " +
+                "nothing is checked, sometimes for the life of the file. Make the " +
+                "precondition part of the test (set it up, or fail with a message that " +
+                "says what is missing), or mark the spec test.fixme(...) so the report " +
+                "names it as not running.",
+        },
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== "MemberExpression" ||
+                    callee.computed ||
+                    callee.property.type !== "Identifier" ||
+                    callee.property.name !== "skip") {
+                    return;
+                }
+                // this.skip() — Mocha's runtime skip.
+                if (callee.object.type === "ThisExpression") {
+                    context.report({ node, messageId: "conditionalSkip" });
+                    return;
+                }
+                const root = rootIdentifier(callee.object);
+                if (root === null || !RUNNERS.has(root))
+                    return;
+                if (isDeclarativeSkip(node.arguments))
+                    return;
+                context.report({ node, messageId: "conditionalSkip" });
+            },
+        };
+    },
+};
+export default rule;

package/dist/eslint-plugin/rules/no-swallowed-cleanup-catch.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=no-swallowed-cleanup-catch.d.ts.map

package/dist/eslint-plugin/rules/no-swallowed-cleanup-catch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-swallowed-cleanup-catch.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/rules/no-swallowed-cleanup-catch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAmBnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAgDhB,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/eslint-plugin/rules/no-swallowed-cleanup-catch.js

@@ -0,0 +1,63 @@
+/** `() => {}`, `() => undefined`, `function () {}` — a handler that does nothing. */
+function isEmptyHandler(node) {
+    if (node.type !== "ArrowFunctionExpression" &&
+        node.type !== "FunctionExpression") {
+        return false;
+    }
+    const body = node.body;
+    if (body.type === "BlockStatement")
+        return body.body.length === 0;
+    if (body.type === "Identifier")
+        return body.name === "undefined";
+    if (body.type === "Literal")
+        return body.value === null;
+    if (body.type === "ObjectExpression")
+        return body.properties.length === 0;
+    return false;
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Do not swallow errors from setup or cleanup — a discarded failure reads as a pass",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            swallowedCatch: "An empty .catch() turns a failed setup or cleanup into a green run, " +
+                "and the test that follows fails somewhere else entirely. Assert on the " +
+                "error, rethrow it with context, or narrow the catch to the one error " +
+                "you expect and say why.",
+            emptyCatchBlock: "This catch block discards the error, so a failure here is invisible. " +
+                "Assert on it, rethrow it, or leave a comment saying which error is " +
+                "expected and why ignoring it is safe.",
+        },
+    },
+    create(context) {
+        const sourceCode = context.sourceCode;
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== "MemberExpression" ||
+                    callee.computed ||
+                    callee.property.type !== "Identifier" ||
+                    callee.property.name !== "catch") {
+                    return;
+                }
+                const [handler] = node.arguments;
+                if (handler && isEmptyHandler(handler)) {
+                    context.report({ node, messageId: "swallowedCatch" });
+                }
+            },
+            CatchClause(node) {
+                if (node.body.body.length > 0)
+                    return;
+                // A comment inside is the author annotating a deliberate ignore.
+                if (sourceCode.getCommentsInside(node.body).length > 0)
+                    return;
+                context.report({ node, messageId: "emptyCatchBlock" });
+            },
+        };
+    },
+};
+export default rule;

package/dist/eslint-plugin/rules/no-wait-for-timeout.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=no-wait-for-timeout.d.ts.map

package/dist/eslint-plugin/rules/no-wait-for-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-wait-for-timeout.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/rules/no-wait-for-timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AA4CnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAqChB,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/eslint-plugin/rules/no-wait-for-timeout.js

@@ -0,0 +1,69 @@
+const SLEEP_MESSAGE = "This sleeps for a fixed time instead of waiting for a condition, so it is " +
+    "slow when it passes and lying when it fails. Use " +
+    "session.until('<what you are waiting for>', fn) — or expect.poll / findBy* " +
+    "— so the wait names the thing it is waiting for.";
+function isGlobalSetTimeout(callee) {
+    if (callee.type === "Identifier")
+        return callee.name === "setTimeout";
+    return (callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier" &&
+        callee.property.name === "setTimeout" &&
+        callee.object.type === "Identifier" &&
+        ["window", "globalThis", "global"].includes(callee.object.name));
+}
+/**
+ * Only sleeps, not every timer. `setTimeout(resolve, 100)` and a setTimeout
+ * inside a `new Promise(...)` executor are the sleep idiom; a timer whose
+ * callback does real work (a fixture component, a debounce test) is not.
+ */
+function isSleep(node) {
+    const [first] = node.arguments;
+    if (first && first.type === "Identifier")
+        return true;
+    let current = node.parent ?? null;
+    for (let depth = 0; current && depth < 4; depth += 1) {
+        if (current.type === "NewExpression" &&
+            current.callee.type === "Identifier" &&
+            current.callee.name === "Promise") {
+            return true;
+        }
+        current = current.parent ?? null;
+    }
+    return false;
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Wait for a condition instead of sleeping for a fixed duration",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            waitForTimeout: "page.waitForTimeout() sleeps for a fixed time. Use " +
+                "session.until('<what you are waiting for>', fn) — or expect.poll / a " +
+                "web-first assertion — so the wait names its condition and ends as " +
+                "soon as it holds.",
+            sleep: SLEEP_MESSAGE,
+        },
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type === "MemberExpression" &&
+                    !callee.computed &&
+                    callee.property.type === "Identifier" &&
+                    callee.property.name === "waitForTimeout") {
+                    context.report({ node, messageId: "waitForTimeout" });
+                    return;
+                }
+                if (isGlobalSetTimeout(callee) && isSleep(node)) {
+                    context.report({ node, messageId: "sleep" });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/eslint-plugin/rules/no-weak-assertions.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=no-weak-assertions.d.ts.map

package/dist/eslint-plugin/rules/no-weak-assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-weak-assertions.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/rules/no-weak-assertions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AA2BnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UA4DhB,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/eslint-plugin/rules/no-weak-assertions.js

@@ -0,0 +1,73 @@
+const DEFAULT_MATCHERS = ["toBeTruthy", "toBeDefined"];
+const ALTERNATIVES = {
+    toBeTruthy: "assert the value you mean — toBe/toEqual, toHaveLength, toHaveText, or a " +
+        "DSL assertion like assertText()",
+    toBeDefined: "assert the value you mean — toBe/toEqual, or toBeInstanceOf when the type " +
+        "is the point",
+    toBeFalsy: "assert the exact falsy value — toBe(false), toBe(0), toBeNull()",
+    toBeNull: "assert the value you mean, or pair it with a positive assertion",
+};
+/** Does this member chain hang off an `expect(...)` call? */
+function rootsAtExpect(node) {
+    let current = node;
+    while (current.type === "MemberExpression")
+        current = current.object;
+    return (current.type === "CallExpression" &&
+        current.callee.type === "Identifier" &&
+        current.callee.name === "expect");
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Assert the shape you mean instead of truthiness or definedness",
+            recommended: true,
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    matchers: {
+                        type: "array",
+                        items: { type: "string" },
+                        minItems: 1,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            weak: "{{matcher}}() passes for almost any value, so it proves little more " +
+                "than that the line ran. Assert the shape you mean with toBe/toEqual " +
+                "and friends: {{alternative}}.",
+        },
+    },
+    create(context) {
+        const configured = context.options[0];
+        const matchers = new Set(configured?.matchers ?? DEFAULT_MATCHERS);
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== "MemberExpression" ||
+                    callee.computed ||
+                    callee.property.type !== "Identifier") {
+                    return;
+                }
+                const matcher = callee.property.name;
+                if (!matchers.has(matcher))
+                    return;
+                if (!rootsAtExpect(callee.object))
+                    return;
+                context.report({
+                    node,
+                    messageId: "weak",
+                    data: {
+                        matcher,
+                        alternative: ALTERNATIVES[matcher] ?? "assert the shape you actually expect",
+                    },
+                });
+            },
+        };
+    },
+};
+export default rule;

package/dist/eslint-plugin/rules/warn-serial-mode.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=warn-serial-mode.d.ts.map