test-inventory 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # test-inventory
 
+## 0.4.1
+
+### Patch Changes
+
+- [#48](https://github.com/Huldoser/test-inventory/pull/48) [`6549682`](https://github.com/Huldoser/test-inventory/commit/65496820548c0980cef2f290f6d54bd89160236b) - A hook given a function the file declares, as in `test.beforeEach(skipOnCI)` or `beforeEach(requireBroker)`, is read
+  like one written in place: the skips, timeouts and other settings it sets apply to the tests it runs before, and its
+  fixtures are in their `fixtures`. Before, they were missed. A test or hook function passed by name no longer gets a
+  `state-in-helper` warning saying no test, hook or describe in the file calls it.
+
+- [#47](https://github.com/Huldoser/test-inventory/pull/47) [`a603623`](https://github.com/Huldoser/test-inventory/commit/a603623b2431e51c3e48ae0413964d5a7125de59) - A `#` import or workspace package export whose target repeats the `*` of its pattern, as in
+  `"#desks/*": "./desks/*/*-fixtures.ts"`, is followed to the file Node.js loads, with every `*` filled in. Only the
+  first was filled in before, so the import wasn't followed and its tests were missing, with an `unresolved-test-import`
+  error. A folder given as the pattern with a long run of slashes, as in `tests////unit`, no longer slows the scan down
+  while the hint for it is written.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#42](https://github.com/Huldoser/test-inventory/pull/42) [`6849f55`](https://github.com/Huldoser/test-inventory/commit/6849f555d8b214ebbc8fdb9aa9cbac8cfe0913db) - Tests say what their body does: `fixtures` (the names the test and the `beforeEach`, `afterEach` and `aroundEach` hooks around it take from the context, without Vitest's own keys), `expectCount` (`expect()`, `expect.soft()` and `expect.poll()` calls in the body), Vitest's `expect.assertions(n)` and `expect.hasAssertions()` as `expectedAssertions` and `expectsAssertions`, `hasEmptyBody`, and Playwright's `test.step()` titles in `steps`. Vitest's `annotate()` from the test context adds annotations. Vitest 5 benchmarks, in `*.bench.ts` files or using the `bench` fixture, have `isBenchmark` and a `benchmarkCount` in the summary. New warnings: `empty-title` for a test or describe titled `''`, and `bench-outside-benchmark-file`.
+
+- [#40](https://github.com/Huldoser/test-inventory/pull/40) [`f462ee0`](https://github.com/Huldoser/test-inventory/commit/f462ee015fea8ee802f567a26dbaa4db94ada1d5) - The output has a record for each scanned file in `files`, and counts hooks: `hooks` on a file holds the hooks at its top level, on a describe the hooks registered in it, and on a test every hook that runs around it, by kind (`beforeAll`, `beforeEach`, `afterEach`, `afterAll`, and Vitest's `aroundEach` and `aroundAll`). Hooks a helper function registers count where it is called. JSON Lines output has a `file` line for each file, and a filtered inventory keeps the files of the matched tests and the files without tests.
+
+- [#41](https://github.com/Huldoser/test-inventory/pull/41) [`1ab9cb4`](https://github.com/Huldoser/test-inventory/commit/1ab9cb4002dd971ddb62570dc55ac564504e3a83) - Tests and describes have their run settings: `timeout`, `isSlow` and `slowCondition`, `retries`, `retryDelay`, `retryCondition` and `repeats`. Playwright's come from `test.describe.configure({ timeout, retries })`, `test.setTimeout()` and `test.slow()` in a describe, a `beforeEach` or the test body; Vitest's from the `timeout`, `retry` and `repeats` options, the timeout after the body, and the options a describe passes down. A test gets the value from the nearest place that sets it, and `null` when the file sets none, so the config decides. A timeout that can't be worked out, or that is set only under a condition, gets an `unresolved-option` warning.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -86,6 +86,12 @@ const todo = inventory.tests.filter((test) => test.isTodo).map((test) => test.fu
 `scanSource()` scans the code of one file without touching the disk. The JSON Schema of the output is exported as
 `test-inventory/schema/v1.json`, so a reader can pin the version of the format it understands.
 
+## AI agents
+
+[test-inventory-mcp](https://github.com/Huldoser/test-inventory-mcp) is an MCP server built on test-inventory: agents
+in Claude Code, Cursor, VS Code and other MCP clients ask it which tests a project has without running them. The
+[AI agents](https://huldoser.github.io/test-inventory/guide/agents) page has the setup and the other ways in.
+
 ## Limits
 
 - Config files are not read, so `grep`, projects and Vitest tag options in them do not change the output.

package/dist/diagnostics.js

@@ -34,6 +34,8 @@ export const LEVELS = {
     'no-files-matched': 'warning',
     'unsupported-file': 'warning',
     'approximate-framework-version': 'warning',
+    'empty-title': 'warning',
+    'bench-outside-benchmark-file': 'warning',
     'test-in-function': 'warning',
 };
 /**

package/dist/extract.d.ts

@@ -1,8 +1,8 @@
 import type { CallExpression } from 'oxc-parser';
-import type { Adapter, Details, Mode, ModuleReader, ModuleSource, Problem, Span, StateSetting, SuiteDeclaration, TestDeclaration } from './model.ts';
+import type { Adapter, Details, Mode, ModuleReader, ModuleSource, Problem, RunSettings, Span, StateSetting, SuiteDeclaration, TestDeclaration } from './model.ts';
 import type { ParsedFile } from './parse.ts';
 import { type SourceText } from './source.ts';
-import type { Annotation } from './types.ts';
+import type { Annotation, HookCounts, Step } from './types.ts';
 import { type Values } from './values.ts';
 /** The file or a describe, with what is set on it. Tests inherit from every scope around them. */
 export interface Scope {
@@ -12,6 +12,12 @@ export interface Scope {
     mode: Mode | null;
     isOnly: boolean;
     details: Details;
+    /** Hooks registered directly in the scope. */
+    hooks: HookCounts;
+    /** Run settings from `beforeEach` hooks in the scope, which run before each test in it and win over the scope's own. */
+    hookRun: RunSettings;
+    /** Fixtures of the hooks in the scope that run around each test. */
+    hookFixtures: string[];
     suite: PendingSuite | null;
 }
 /** Where a test or describe registered through an imported helper is written, in the helper's module. */
@@ -48,6 +54,12 @@ export interface PendingTest {
     isInCondition: boolean;
     isInFunction: boolean;
     comments: string[];
+    /** Run settings from calls in the body, which win over everything around the test. */
+    run: RunSettings;
+    expectCount: number;
+    expectedAssertions: number | null;
+    expectsAssertions: boolean;
+    steps: Step[];
     problems: Problem[];
 }
 /** A file the walk reads code from: the scanned file, or a module a helper function is imported from. */
@@ -65,7 +77,19 @@ export interface Extraction {
     tests: PendingTest[];
     /** Problems not tied to one test. */
     problems: Problem[];
+    /** Hooks at the top level of the file. */
+    hooks: HookCounts;
     usesGlobals: boolean;
 }
+/**
+ * Applies settings written later in the same place: the last value of each wins, and a test is slow when any
+ * `test.slow()` applies.
+ */
+export declare function mergeRun(target: RunSettings, later: RunSettings): void;
+/** Any of several `test.slow()` calls: always when one always applies, otherwise under any of their conditions. */
+export declare function anySlow(slows: NonNullable<RunSettings['slow']>[]): NonNullable<RunSettings['slow']>;
+/** Conditions joined with `||`, adding parentheses where a part could otherwise be read differently. */
+export declare function eitherCondition(parts: string[]): string;
+export declare function noHooks(): HookCounts;
 /** Walks the scanned file; `openModule` reads the modules of imported helpers that the file calls. */
 export declare function extract(main: Frame, openModule: OpenModule): Extraction;

package/dist/extract.js

@@ -1,6 +1,6 @@
 import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, returnValues, unwrap, } from "./ast.js";
 import { exportName } from "./frameworks/bindings.js";
-import { problem } from "./frameworks/common.js";
+import { problem, readCount } from "./frameworks/common.js";
 import { snippet, splitLines } from "./source.js";
 import { isScopeNode } from "./values.js";
 /** How many helpers deep a call is followed into the functions it calls, far more than real suites nest. */
@@ -20,11 +20,49 @@ function calledWhereWritten(call, written) {
         !call.inBody);
 }
 const LOOP_METHODS = new Set(['forEach', 'map']);
-/** What `test.describe.configure()` sets on the describe or file it is called in: the last mode wins, locks add up. */
+/**
+ * What `test.describe.configure()` sets on the describe or file it is called in: the last mode, timeout and retries
+ * win, locks add up.
+ */
 function configure(scope, settings) {
     if (settings.mode)
         scope.mode = settings.mode;
     scope.details.locks.push(...settings.locks);
+    mergeRun(scope.details.run, settings.run);
+}
+/**
+ * Applies settings written later in the same place: the last value of each wins, and a test is slow when any
+ * `test.slow()` applies.
+ */
+export function mergeRun(target, later) {
+    const { slow, ...rest } = later;
+    Object.assign(target, rest);
+    if (slow)
+        target.slow = target.slow ? anySlow([target.slow, slow]) : slow;
+}
+/** Any of several `test.slow()` calls: always when one always applies, otherwise under any of their conditions. */
+export function anySlow(slows) {
+    const lists = slows.map((slow) => slow.conditions);
+    if (lists.includes(null))
+        return { conditions: null };
+    return { conditions: [...new Set(lists.flat())] };
+}
+/** Conditions joined with `||`, adding parentheses where a part could otherwise be read differently. */
+export function eitherCondition(parts) {
+    return parts.map((part) => (parts.length > 1 && /\?|,/.test(part) ? `(${part})` : part)).join(' || ');
+}
+/** A warning for a test or describe titled with an empty string, which reports can't tell apart. */
+function emptyTitle(declaration, call) {
+    const { title } = declaration;
+    if (title?.text !== '' || title.isDynamic)
+        return [];
+    const what = declaration.kind === 'test' ? 'test' : 'describe';
+    return [problem('empty-title', call, `The ${what} has an empty title, so reports and filters can't tell it apart.`)];
+}
+/** Hooks that run around each test, whose fixtures the test uses too. */
+const EACH_HOOKS = new Set(['beforeEach', 'afterEach', 'aroundEach']);
+export function noHooks() {
+    return { beforeAll: 0, beforeEach: 0, afterEach: 0, afterAll: 0, aroundEach: 0, aroundAll: 0 };
 }
 /** Joins conditions with `&&`, adding parentheses where a part could otherwise be read differently. */
 function joinConditions(parts) {
@@ -72,7 +110,10 @@ class Walker {
     declaredIn = new Map();
     deferred = [];
     isDeferred = new Set();
-    /** Functions walked at one of their calls, so that their tests are recorded where they are registered. */
+    /**
+     * Functions walked at one of their calls, or as a test or hook body passed by name, so that their tests are recorded
+     * where they are registered and what they set isn't reported as unapplied.
+     */
     walkedAtCall = new Set();
     /** The functions being walked at their calls, innermost last, to stop recursion. */
     callStack = [];
@@ -95,7 +136,10 @@ class Walker {
             states: [],
             mode: null,
             isOnly: false,
-            details: { tags: adapter.fileTags, annotations: [], locks: [], meta: null },
+            details: { tags: adapter.fileTags, annotations: [], locks: [], meta: null, run: {} },
+            hooks: noHooks(),
+            hookRun: {},
+            hookFixtures: [],
             suite: null,
         };
     }
@@ -104,6 +148,8 @@ class Walker {
             scope: this.fileScope,
             test: null,
             hookScope: null,
+            hookName: null,
+            stepDepth: 0,
             testContext: null,
             guards: [],
             isInLoop: false,
@@ -127,6 +173,7 @@ class Walker {
             suites: this.suites,
             tests: this.tests,
             problems: [...this.main.adapter.problems, ...this.problems],
+            hooks: this.fileScope.hooks,
             usesGlobals: this.main.adapter.usesGlobals,
         };
     }
@@ -147,6 +194,8 @@ class Walker {
     visitNode(node, context) {
         switch (node.type) {
             case 'CallExpression': {
+                if (context.test && !context.quiet)
+                    this.expectCall(node, context.test);
                 const helper = this.helperCall(node, context);
                 if (this.call(node, context) || this.loopCall(node, context))
                     return;
@@ -342,13 +391,37 @@ class Walker {
                     configure(context.scope, api);
                 }
                 return true;
+            case 'run':
+                this.runSetting(call, api, context);
+                return true;
+            case 'step':
+                // The adapters only return steps from test bodies.
+                context.test.steps.push({
+                    title: api.title.text,
+                    hasDynamicTitle: api.title.isDynamic,
+                    lineStart: this.lineOf(call),
+                    depth: context.stepDepth,
+                    isSkipped: api.isSkipped,
+                });
+                if (api.fn)
+                    this.visitCallback(api.fn, { ...context, stepDepth: context.stepDepth + 1 });
+                return true;
             case 'hook':
                 if (context.test)
                     return false;
+                // A function with a name registers its hooks where it is called, not where it is written.
+                if (!context.hookScope && context.declaredIn === null) {
+                    context.scope.hooks[api.name] += 1;
+                    if (EACH_HOOKS.has(api.name))
+                        context.scope.hookFixtures.push(...api.fixtures);
+                }
                 if (api.fn) {
+                    if (!call.arguments.includes(api.fn))
+                        this.walkedAtCall.add(api.fn);
                     this.visitCallback(api.fn, {
                         ...context,
                         hookScope: context.scope,
+                        hookName: api.name,
                         testContext: api.testContext,
                         guards: [],
                         helper: null,
@@ -411,6 +484,7 @@ class Walker {
                 call,
                 fn,
                 target: context.test ?? context.hookScope,
+                hookName: context.test ? null : context.hookName,
                 guards: context.guards,
             });
         }
@@ -607,6 +681,89 @@ class Walker {
         }
         return chains.get(fn);
     }
+    /**
+     * Applies `test.setTimeout()` or `test.slow()` where it is called: in a test body to the test, in a `beforeEach` to
+     * the tests of its scope, at file or describe level to the scope. A function with a name applies them where it is
+     * called instead.
+     */
+    runSetting(call, api, context) {
+        if (context.declaredIn !== null && !context.test) {
+            for (const item of api.problems)
+                this.report(item);
+            if (context.helper)
+                this.effectsOf(context.helper).push({ kind: 'run', settings: api.settings, argument: api.argument, call });
+            return;
+        }
+        const { settings, problems } = this.guardedRun(call, api.settings, api.argument, context.guards);
+        problems.unshift(...api.problems);
+        if (context.test) {
+            context.test.problems.push(...problems.map((item) => this.here(item)));
+            mergeRun(context.test.run, settings);
+            return;
+        }
+        for (const item of problems)
+            this.report(item);
+        if (context.hookScope) {
+            // `beforeAll` and `afterAll` set the hook's own timeout, and an `afterEach` runs after the test body.
+            if (context.hookName === 'beforeEach')
+                mergeRun(context.hookScope.hookRun, settings);
+            return;
+        }
+        mergeRun(context.scope.details.run, settings);
+    }
+    /**
+     * Run settings under the conditions around a call: a slow test keeps them as its condition, while a timeout set only
+     * sometimes is left out with a warning.
+     */
+    guardedRun(call, written, argument, guards) {
+        const settings = { ...written };
+        const problems = [];
+        const guard = joinConditions(guards);
+        if (settings.slow && guards.length > 0) {
+            const own = settings.slow.conditions ?? [null];
+            settings.slow = {
+                conditions: own.map((condition) => joinConditions([...guards, ...(condition === null ? [] : [condition])])),
+            };
+        }
+        if (settings.timeout !== undefined && guard !== null) {
+            const message = `Option timeout: ${argument} is set only when ${guard}; it is not applied.`;
+            problems.push(problem('unresolved-option', call, message, snippet(this.text(call))));
+            delete settings.timeout;
+        }
+        return { settings, problems };
+    }
+    /** Run settings a helper sets when a test body or a `beforeEach` calls it, under the conditions around the call. */
+    applyHelperRun(call, effect) {
+        const { settings, problems } = this.guardedRun(call.call, effect.settings, effect.argument, effect.guards);
+        if (call.hookName === null) {
+            const test = call.target;
+            test.problems.push(...problems);
+            mergeRun(test.run, settings);
+        }
+        else if (call.hookName === 'beforeEach') {
+            this.problems.push(...problems);
+            mergeRun(call.target.hookRun, settings);
+        }
+    }
+    /** Counts `expect()`, `expect.soft()` and `expect.poll()`, and reads `expect.assertions(n)` and `expect.hasAssertions()`. */
+    expectCall(call, test) {
+        const callee = unwrap(call.callee);
+        const [root, member] = callee.type === 'MemberExpression' ? [unwrap(callee.object), propertyName(callee)] : [callee, 'call'];
+        if (root.type !== 'Identifier' || root.name !== 'expect')
+            return;
+        if (member === 'call' || member === 'soft' || member === 'poll')
+            test.expectCount += 1;
+        if (member === 'hasAssertions')
+            test.expectsAssertions = true;
+        const count = call.arguments.at(0);
+        if (member === 'assertions' && count && count.type !== 'SpreadElement') {
+            const file = { source: this.frame.parsed.source, values: this.frame.values, version: null };
+            const option = { node: count, resolved: this.frame.values.resolve(count, this.scopes) };
+            const problems = [];
+            test.expectedAssertions = readCount(file, 'expect.assertions', option, problems);
+            test.problems.push(...problems.map((item) => this.here(item)));
+        }
+    }
     /** Reports a problem not tied to a test, once, however many times a function with it is walked. */
     report(found) {
         const item = this.here(found);
@@ -688,6 +845,8 @@ class Walker {
                     return expand(effect.fn, [...guards, ...effect.guards], new Set([...path, fn]));
                 if (effect.kind === 'configure')
                     return [effect];
+                if (effect.kind === 'run')
+                    return [{ ...effect, guards }];
                 const condition = joinConditions([...guards, ...(effect.setting.condition ? [effect.setting.condition] : [])]);
                 // Helpers are expanded here only for calls from tests and hooks.
                 return [{ ...effect, setting: { ...effect.setting, condition, afterLoad: true } }];
@@ -700,6 +859,8 @@ class Walker {
                 // `describe.configure()` does nothing in a test or hook body.
                 if (effect.kind === 'state')
                     call.target.states.push(effect.setting);
+                if (effect.kind === 'run')
+                    this.applyHelperRun(call, effect);
             }
             if (steps > MAX_CALLS) {
                 const callee = snippet(this.frame.parsed.source.slice(call.call.callee.start, call.call.callee.end));
@@ -754,6 +915,7 @@ class Walker {
         if (context.quiet || this.nested(call, context))
             return;
         const statement = this.statement(call);
+        const empty = emptyTitle(declaration, call);
         const test = {
             scope: context.scope,
             declaration,
@@ -767,17 +929,28 @@ class Walker {
             isInCondition: context.isInCondition,
             isInFunction: context.isInFunction,
             comments: this.commentsAbove(statement.start),
-            problems: declaration.problems.map((item) => this.here(item)),
+            run: {},
+            expectCount: 0,
+            expectedAssertions: null,
+            expectsAssertions: false,
+            steps: [],
+            problems: [...declaration.problems, ...empty].map((item) => this.here(item)),
         };
         this.tests.push(test);
         if (context.declaredIn)
             this.declaredIn.set(test, context.declaredIn);
         this.cut(context.scope, call);
-        if (declaration.fn) {
-            this.visitCallback(declaration.fn, {
+        // A function declared in the file and passed by name runs as the test body too.
+        const body = declaration.fn ?? declaration.hashed;
+        if (body) {
+            if (!declaration.fn)
+                this.walkedAtCall.add(body);
+            this.visitCallback(body, {
                 ...context,
                 test,
                 hookScope: null,
+                hookName: null,
+                stepDepth: 0,
                 testContext: declaration.testContext,
                 guards: [],
                 helper: null,
@@ -787,7 +960,7 @@ class Walker {
     declareSuite(call, declaration, context) {
         if (context.quiet || this.nested(call, context))
             return;
-        for (const item of declaration.problems)
+        for (const item of [...declaration.problems, ...emptyTitle(declaration, call)])
             this.report(item);
         const scope = {
             kind: 'describe',
@@ -796,6 +969,9 @@ class Walker {
             mode: declaration.mode,
             isOnly: declaration.isOnly,
             details: declaration.details,
+            hooks: noHooks(),
+            hookRun: {},
+            hookFixtures: [],
             suite: null,
         };
         const suite = {
@@ -817,6 +993,8 @@ class Walker {
                 scope,
                 test: null,
                 hookScope: null,
+                hookName: null,
+                stepDepth: 0,
                 testContext: null,
                 guards: [],
                 helper: null,

package/dist/filter.d.ts

@@ -20,7 +20,8 @@ export type PickedInventory<K extends keyof TestRecord> = Omit<Inventory, 'tests
 export declare function matcher(filter: InventoryFilter): (test: TestRecord) => boolean;
 /**
  * Keeps the tests that pass every condition of the filter; a list keeps a test that has any of its values. The
- * result describes only those tests: the describes around them, their diagnostics, and a summary counted over them.
+ * result describes only those tests: their files, the describes around them, their diagnostics, and a summary
+ * counted over them. Files without any tests stay, with their diagnostics, since tests may be missing from them.
  * `summary.fileCount` stays the number of files scanned.
  *
  * Throws a `TypeError` for an invalid filter.

package/dist/filter.js

@@ -47,6 +47,21 @@ const TEST_KEYS = Object.keys({
     comments: true,
     locks: true,
     meta: true,
+    hooks: true,
+    timeout: true,
+    isSlow: true,
+    slowCondition: true,
+    retries: true,
+    retryDelay: true,
+    retryCondition: true,
+    repeats: true,
+    fixtures: true,
+    expectCount: true,
+    expectedAssertions: true,
+    expectsAssertions: true,
+    hasEmptyBody: true,
+    steps: true,
+    isBenchmark: true,
     isParameterized: true,
     caseCount: true,
     isInLoop: true,
@@ -103,7 +118,8 @@ export function matcher(filter) {
 }
 /**
  * Keeps the tests that pass every condition of the filter; a list keeps a test that has any of its values. The
- * result describes only those tests: the describes around them, their diagnostics, and a summary counted over them.
+ * result describes only those tests: their files, the describes around them, their diagnostics, and a summary
+ * counted over them. Files without any tests stay, with their diagnostics, since tests may be missing from them.
  * `summary.fileCount` stays the number of files scanned.
  *
  * Throws a `TypeError` for an invalid filter.
@@ -121,13 +137,13 @@ export function filterInventory(inventory, filter) {
     const suites = inventory.suites.filter((suite) => suiteIds.has(suite.id));
     const filesWithTests = new Set(inventory.tests.map((test) => test.relativeFilePath));
     const filesWithMatches = new Set(tests.map((test) => test.relativeFilePath));
-    // A problem that is not about one test stays, unless every test of its file was left out: an error in a file
-    // with no tests, or in package.json, may mean tests are missing from the answer.
-    const diagnostics = inventory.diagnostics.filter((diagnostic) => diagnostic.testId === null
-        ? !filesWithTests.has(diagnostic.relativeFilePath) || filesWithMatches.has(diagnostic.relativeFilePath)
-        : testIds.has(diagnostic.testId));
+    // A file, and a problem that is not about one test, stay unless every test of the file was left out: an error in
+    // a file with no tests, or in package.json, may mean tests are missing from the answer.
+    const keepsFile = (relativeFilePath) => !filesWithTests.has(relativeFilePath) || filesWithMatches.has(relativeFilePath);
+    const diagnostics = inventory.diagnostics.filter((diagnostic) => diagnostic.testId === null ? keepsFile(diagnostic.relativeFilePath) : testIds.has(diagnostic.testId));
     const summary = summarize(inventory.summary.fileCount, suites, tests, diagnostics);
-    return { ...inventory, summary, suites, tests, diagnostics };
+    const files = inventory.files.filter((file) => keepsFile(file.relativeFilePath));
+    return { ...inventory, summary, files, suites, tests, diagnostics };
 }
 /** Checks the keys to pick and returns them after `id`, each once. */
 export function checkFields(fields) {

package/dist/frameworks/common.d.ts

@@ -75,6 +75,8 @@ export declare function mayDeclareTests(name: string, links: Link[]): boolean;
 /** A function declared in the file and passed by name, as in `test('fills an order', checkFill)`; null otherwise. */
 export declare function namedFunction(file: FileContext, scopes: readonly Node[], node: Argument | undefined): FunctionNode | null;
 export declare function findFunction(args: readonly Argument[], from?: number): FunctionNode | null;
+/** A hook's function: written in the call, or declared in the file and passed by name, as in `beforeEach(signIn)`. */
+export declare function hookFunction(file: FileContext, scopes: readonly Node[], args: readonly Argument[]): FunctionNode | null;
 /** Reads a title. A title that cannot be worked out keeps its source text and gets a `dynamic-title` warning. */
 export declare function readTitle(file: FileContext, scopes: readonly Node[], node: Argument, options: {
     stripTags: boolean;
@@ -112,6 +114,10 @@ export interface Options {
 export declare function readOptions(file: FileContext, scopes: readonly Node[], node: Argument): Options;
 /** Warnings for the parts of an options object that could not be worked out, with what is missing as a result. */
 export declare function unresolvedOptions(file: FileContext, options: Options, result: string): Problem[];
+/** The names a function takes from the object pattern of one of its parameters, in source order. */
+export declare function destructuredNames(fn: FunctionNode | null, index: number | null): string[];
+/** A whole number, such as a timeout in milliseconds; null, with a warning, when it can't be worked out. */
+export declare function readCount(file: FileContext, name: string, option: OptionValue, problems: Problem[]): number | null;
 /** A warning for one option whose value could not be worked out. */
 export declare function unresolvedOption(file: FileContext, name: string, node: Node, importedFrom: string | null, result: string): Problem;
 export interface Strings {

package/dist/frameworks/common.js

@@ -1,4 +1,4 @@
-import { isFunctionNode, isStringLiteral, propertyName, unwrap } from "../ast.js";
+import { isFunctionNode, isStringLiteral, propertyKey, propertyName, unwrap } from "../ast.js";
 import { snippet } from "../source.js";
 import { isKey } from "../values.js";
 export function readChain(callee) {
@@ -166,6 +166,10 @@ export function findFunction(args, from = 0) {
     }
     return null;
 }
+/** A hook's function: written in the call, or declared in the file and passed by name, as in `beforeEach(signIn)`. */
+export function hookFunction(file, scopes, args) {
+    return findFunction(args) ?? args.map((arg) => namedFunction(file, scopes, arg)).find((fn) => fn !== null) ?? null;
+}
 /** Reads a title. A title that cannot be worked out keeps its source text and gets a `dynamic-title` warning. */
 export function readTitle(file, scopes, node, options) {
     const expression = node.type === 'SpreadElement' ? null : node;
@@ -275,6 +279,27 @@ export function unresolvedOptions(file, options, result) {
         return problem('unresolved-option', node, `Options object ${source}${origin(importedFrom)} could not be worked out; ${result}.`, source);
     });
 }
+/** The names a function takes from the object pattern of one of its parameters, in source order. */
+export function destructuredNames(fn, index) {
+    const parameter = index === null ? undefined : fn?.params[index];
+    if (parameter?.type !== 'ObjectPattern')
+        return [];
+    const names = parameter.properties.map((property) => (property.type === 'Property' ? propertyKey(property) : null));
+    return names.filter((name) => name !== null);
+}
+/** A whole number, such as a timeout in milliseconds; null, with a warning, when it can't be worked out. */
+export function readCount(file, name, option, problems) {
+    const { node, resolved } = option;
+    if (!resolved.ok) {
+        problems.push(unresolvedOption(file, name, node, resolved.importedFrom, 'it is not applied'));
+        return null;
+    }
+    if (Number.isInteger(resolved.value) && resolved.value >= 0)
+        return resolved.value;
+    const source = snippet(text(file, node));
+    problems.push(problem('unresolved-option', node, `Option ${name}: ${source} is not a whole number; it is not applied.`, source));
+    return null;
+}
 /** A warning for one option whose value could not be worked out. */
 export function unresolvedOption(file, name, node, importedFrom, result) {
     const source = snippet(text(file, node));

package/dist/frameworks/playwright.d.ts

@@ -52,9 +52,13 @@ export declare class PlaywrightAdapter implements Adapter {
     /** A chain Playwright refuses; one that starts like a declaration also declares a plain test or describe. */
     private invalid;
     private testCall;
+    /** `test.step(title, body)` in a test body; a title that can't be worked out is kept as source text. */
+    private step;
     private modifier;
     private describeCall;
     private configure;
+    /** `test.setTimeout(ms)` or `test.slow(condition?, description?)`, which apply where they are called. */
+    private runSetting;
     /** `test.info().annotations.push(...)` inside a test body. */
     private annotationsPush;
     private option;