test-inventory 0.6.0 → 0.7.0

package/dist/extract.js

@@ -2,6 +2,7 @@ import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, returnVal
 import { exportName } from "./frameworks/bindings.js";
 import { problem, readCount } from "./frameworks/common.js";
 import { snippet, splitLines } from "./source.js";
+import { vitestCaseTitle } from "./case-titles.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. */
 const MAX_DEPTH = 16;
@@ -11,6 +12,11 @@ const MAX_DEPTH = 16;
  * of six levels are a million.
  */
 const MAX_CALLS = 10_000;
+/**
+ * How many loop passes and describe cases `expandCases` walks one by one in a file, far more than real suites expand;
+ * past it, loops and describe tables are one record, so that a long loop over test data can't use up the walk.
+ */
+const MAX_EXPANDED = 1000;
 /** Whether a function is called where it is written, so that its tests are registered there. */
 function calledWhereWritten(call, written) {
     return (call.scope === written.scope &&
@@ -20,6 +26,70 @@ function calledWhereWritten(call, written) {
         !call.inBody);
 }
 const LOOP_METHODS = new Set(['forEach', 'map']);
+/**
+ * Whether a statement leaves on every path through it, with `return` or `throw`, or with `break` or `continue` aimed
+ * at a loop or label outside it, so that what follows it in its block doesn't run. `labels` are those declared inside.
+ */
+function alwaysLeaves(statement, labels = new Set()) {
+    switch (statement.type) {
+        case 'ReturnStatement':
+        case 'ThrowStatement':
+            return true;
+        case 'BreakStatement':
+        case 'ContinueStatement':
+            return statement.label === null || !labels.has(statement.label.name);
+        case 'BlockStatement':
+            return statement.body.some((item) => alwaysLeaves(item, labels));
+        case 'IfStatement':
+            return (statement.alternate !== null &&
+                alwaysLeaves(statement.consequent, labels) &&
+                alwaysLeaves(statement.alternate, labels));
+        case 'LabeledStatement':
+            return alwaysLeaves(statement.body, new Set([...labels, statement.label.name]));
+        case 'TryStatement':
+            return ((statement.finalizer !== null && alwaysLeaves(statement.finalizer, labels)) ||
+                (alwaysLeaves(statement.block, labels) &&
+                    (statement.handler === null || alwaysLeaves(statement.handler.body, labels))));
+        default:
+            // A loop or switch takes the `break` and `continue` inside it, and may run its body not at all.
+            return false;
+    }
+}
+/**
+ * The names a condition reads, as in `side === 'buy'` or `!strategy.enabled`; null when it has a function, which the
+ * scan doesn't look into.
+ */
+function referencedNames(node) {
+    if (isFunctionNode(node))
+        return null;
+    if (node.type === 'Identifier')
+        return [node.name];
+    const parts = node.type === 'MemberExpression' && !node.computed ? [node.object] : childNodes(node);
+    const names = [];
+    for (const part of parts) {
+        const found = referencedNames(part);
+        if (!found)
+            return null;
+        names.push(...found);
+    }
+    return names;
+}
+/**
+ * Whether a loop body can end a pass before its end or stop the loop, with `break`, `continue`, `return` or `throw`,
+ * so that a test in it may not be registered on every pass. Functions inside run later, and don't count.
+ */
+function leavesEarly(body) {
+    if (body.type === 'FunctionDeclaration' || isFunctionNode(body))
+        return false;
+    switch (body.type) {
+        case 'BreakStatement':
+        case 'ContinueStatement':
+        case 'ReturnStatement':
+        case 'ThrowStatement':
+            return true;
+    }
+    return childNodes(body).some(leavesEarly);
+}
 /**
  * What `test.describe.configure()` sets on the describe or file it is called in: the last mode, timeout and retries
  * win, locks add up.
@@ -119,13 +189,17 @@ class Walker {
     callStack = [];
     /** Helper calls walked in the file so far, up to MAX_CALLS. */
     callsWalked = 0;
+    /** Loop passes and describe cases walked one by one so far, up to MAX_EXPANDED. */
+    expandedPasses = 0;
     /** Problems already reported, since a function walked at several calls finds the same ones each time. */
     reported = new Set();
     /** What the functions named in calls such as `onNode(22)('title', fn)` return, by the declaration of each name. */
     returns = new Map();
     /** For each file's program, the scopes around each function in it. */
     scopeChains = new Map();
-    constructor(main, openModule) {
+    options;
+    constructor(main, openModule, options) {
+        this.options = options;
         this.main = main;
         this.frame = main;
         this.openModule = openModule;
@@ -155,6 +229,11 @@ class Walker {
             testContext: null,
             guards: [],
             isInLoop: false,
+            loops: [],
+            loopConditions: [],
+            caseIndex: null,
+            isExpanding: false,
+            expandedAt: null,
             isInCondition: false,
             isInFunction: false,
             helper: null,
@@ -216,6 +295,13 @@ class Walker {
                     break;
                 const condition = this.text(node.test);
                 this.visit(node.test, context);
+                const known = this.known(node.test, context);
+                if (known) {
+                    const taken = known.value ? node.consequent : node.alternate;
+                    if (taken)
+                        this.visit(taken, context);
+                    return;
+                }
                 this.visit(node.consequent, this.guarded(context, condition));
                 if (node.alternate)
                     this.visit(node.alternate, this.guarded(context, `!(${condition})`));
@@ -224,6 +310,11 @@ class Walker {
             case 'ConditionalExpression': {
                 const condition = this.text(node.test);
                 this.visit(node.test, context);
+                const known = this.known(node.test, context);
+                if (known) {
+                    this.visit(known.value ? node.consequent : node.alternate, context);
+                    return;
+                }
                 this.visit(node.consequent, this.guarded(context, condition));
                 this.visit(node.alternate, this.guarded(context, `!(${condition})`));
                 return;
@@ -232,6 +323,18 @@ class Walker {
                 const left = this.text(node.left);
                 const guard = node.operator === '&&' ? left : node.operator === '||' ? `!(${left})` : `(${left}) == null`;
                 this.visit(node.left, context);
+                const known = this.known(node.left, context);
+                if (known) {
+                    const { value } = known;
+                    const right = node.operator === '&&'
+                        ? Boolean(value)
+                        : node.operator === '||'
+                            ? !value
+                            : value === null || value === undefined;
+                    if (right)
+                        this.visit(node.right, context);
+                    return;
+                }
                 this.visit(node.right, this.guarded(context, guard));
                 return;
             }
@@ -255,12 +358,26 @@ class Walker {
                 }
                 return;
             }
-            case 'ForStatement':
+            case 'BlockStatement':
+                this.visitStatements(node.body, context);
+                return;
             case 'ForInStatement':
-            case 'ForOfStatement':
+            case 'ForOfStatement': {
+                const values = leavesEarly(node.body) ? null : this.loopValues(node);
+                const expands = values ? this.expands(node, values, context) : 'no';
+                if (values && expands === 'yes') {
+                    this.expandLoop(node, values, context);
+                    return;
+                }
+                this.walkUnexpanded(node, expands === 'limit', () => {
+                    this.visitChildren(node, this.inLoop(context, values?.length ?? null));
+                });
+                return;
+            }
+            case 'ForStatement':
             case 'WhileStatement':
             case 'DoWhileStatement':
-                this.visitChildren(node, { ...context, isInLoop: true });
+                this.visitChildren(node, this.inLoop(context, null));
                 return;
             case 'FunctionDeclaration':
             case 'FunctionExpression':
@@ -297,6 +414,47 @@ class Walker {
         return ((fn.type === 'FunctionDeclaration' && fn.id !== null) ||
             (parent?.type === 'VariableDeclarator' && parent.id.type === 'Identifier' && parent.init === fn));
     }
+    /**
+     * With `expandCases`, the value of a condition outside test and hook bodies when the scan can work it out, as with
+     * the values of a case or pass; null otherwise, and then both branches are walked under the condition.
+     */
+    known(test, context) {
+        if (!this.options.expandCases || context.test || context.hookScope)
+            return null;
+        // Only the values of the case, pass or helper call decide: a constant of the module may be changed in ways the scan
+        // doesn't see, and taking a branch away would drop a test the runner registers.
+        const names = referencedNames(test);
+        if (!names?.every((name) => this.frame.values.isBound(name, this.scopes)))
+            return null;
+        const resolved = this.frame.values.resolve(test, this.scopes);
+        return resolved.ok ? { value: resolved.value } : null;
+    }
+    /**
+     * Walks the statements of a block. After an `if` whose branch always leaves the function or loop, as in
+     * `if (!strategy.enabled) return;`, what follows runs only when that branch isn't taken, so it is under the opposite
+     * condition; a branch taken for certain, or both branches leaving, ends the walk. A branch that leaves on only some
+     * of its paths leaves what follows as it is.
+     */
+    visitStatements(statements, context) {
+        let current = context;
+        for (const statement of statements) {
+            this.visit(statement, current);
+            if (statement.type !== 'IfStatement' || isImportMetaVitest(statement.test))
+                continue;
+            const thenLeaves = alwaysLeaves(statement.consequent);
+            const elseLeaves = statement.alternate !== null && alwaysLeaves(statement.alternate);
+            if (!thenLeaves && !elseLeaves)
+                continue;
+            const known = this.known(statement.test, current);
+            const taken = known && (known.value ? thenLeaves : elseLeaves);
+            if (taken || (thenLeaves && elseLeaves))
+                return;
+            if (known)
+                continue;
+            const condition = this.text(statement.test);
+            current = this.guarded(current, thenLeaves ? `!(${condition})` : condition);
+        }
+    }
     placement(context) {
         return {
             scope: context.scope,
@@ -327,15 +485,108 @@ class Walker {
     text(node) {
         return snippet(this.frame.parsed.source.slice(node.start, node.end));
     }
+    /** `pass` is the pass of an expanded loop, and where the loop starts. */
+    inLoop(context, passes, pass = null) {
+        return {
+            ...context,
+            isInLoop: true,
+            loops: [...context.loops, passes],
+            loopConditions: [...context.loopConditions, context.isInCondition || pass !== null],
+            caseIndex: pass?.index ?? context.caseIndex,
+            isExpanding: context.isExpanding || pass !== null,
+            expandedAt: this.expandedAt(context, pass?.at ?? null),
+        };
+    }
+    /**
+     * Where what an expansion registers is ordered: the outermost expansion in the scanned file. In a helper walked at a
+     * call, the call already orders what it registers, and the helper may be in another file.
+     */
+    expandedAt(context, at) {
+        return context.expandedAt ?? (context.registeredBy === null ? at : null);
+    }
+    /**
+     * Whether to walk a loop or describe table once per value: with `expandCases`, outside test and hook bodies, which
+     * the runner walks once for each test, for a loop that declares its variable with `let` or `const`. An expansion
+     * outside any other starts only while the file has expanded fewer than MAX_EXPANDED passes and cases, so that a long
+     * loop over test data can't use up the walk; inside one, loops expand up to ten times that, so that an expansion
+     * is whole. `limit` means the limit is why it doesn't.
+     */
+    expands(loop, values, context) {
+        if (!this.options.expandCases || context.test || context.hookScope)
+            return 'no';
+        // Vitest runs describe callbacks after the loop, when a `var` holds its last value.
+        if (loop && !(loop.left.type === 'VariableDeclaration' && loop.left.kind !== 'var'))
+            return 'no';
+        const limit = context.isExpanding ? 10 * MAX_EXPANDED : MAX_EXPANDED;
+        if (this.expandedPasses + values.length > limit)
+            return 'limit';
+        this.expandedPasses += values.length;
+        return 'yes';
+    }
+    /**
+     * Walks a loop as one record, and says why it isn't expanded when it was asked to be and registers tests or
+     * describes.
+     */
+    walkUnexpanded(node, limited, walk) {
+        const before = this.tests.length + this.suites.length;
+        walk();
+        if (!limited || this.tests.length + this.suites.length === before)
+            return;
+        this.report(problem('cases-not-expanded', node, `The passes of the loop are listed as one record, since expanding it would take the file past ${MAX_EXPANDED.toLocaleString('en-US')} loop passes and describe cases.`));
+    }
+    /**
+     * Walks the body of `for...of` or `for...in` once per value, with the loop variable bound to it, as the runner runs
+     * it; false when the loop doesn't declare its variable, as in `for (symbol of SYMBOLS)`.
+     */
+    expandLoop(loop, values, context) {
+        const declarator = loop.left.declarations[0];
+        this.visit(loop.right, context);
+        for (const [index, value] of values.entries()) {
+            this.frame.values.withLoopValue(declarator, declarator.id, { ok: true, value }, loop.body, this.scopes, () => {
+                this.visit(loop.body, this.inLoop(context, 1, { index, at: loop.start }));
+            });
+        }
+        return true;
+    }
+    /**
+     * What `for...of` or `for...in` goes over, when the scan can work it out: an array's elements, or the keys of any
+     * value, as `for...in` takes them; null when the value is unknown or `for...of` can't go over it.
+     */
+    loopValues(loop) {
+        // The loop's own scope declares the loop variable, which the value it goes over can't refer to.
+        const resolved = this.frame.values.resolve(loop.right, this.scopes.slice(0, -1));
+        if (!resolved.ok)
+            return null;
+        if (loop.type === 'ForInStatement')
+            return Object.keys(Object(resolved.value ?? {}));
+        return Array.isArray(resolved.value) ? resolved.value : null;
+    }
     /** `symbols.forEach((symbol) => test(...))` declares its tests in a loop. */
     loopCall(call, context) {
         const callee = unwrap(call.callee);
         if (callee.type !== 'MemberExpression' || !LOOP_METHODS.has(propertyName(callee) ?? ''))
             return false;
         this.visit(call.callee, context);
+        const resolved = this.frame.values.resolve(callee.object, this.scopes);
+        const list = resolved.ok && Array.isArray(resolved.value) ? resolved.value : null;
         for (const arg of call.arguments) {
             if (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression') {
-                this.visitCallback(arg, { ...context, isInLoop: true });
+                const values = leavesEarly(arg.body) ? null : list;
+                const expands = values ? this.expands(null, values, context) : 'no';
+                if (values && expands === 'yes') {
+                    // The callback gets each element, its index and the array.
+                    for (const [index, value] of values.entries()) {
+                        const args = [value, index, values].map((item) => ({ ok: true, value: item }));
+                        this.frame.values.withArguments(arg, args, this.scopes, () => {
+                            this.visitCallback(arg, this.inLoop(context, 1, { index, at: call.start }));
+                        });
+                    }
+                }
+                else {
+                    this.walkUnexpanded(call, expands === 'limit', () => {
+                        this.visitCallback(arg, this.inLoop(context, values?.length ?? null));
+                    });
+                }
             }
             else {
                 this.visit(arg, context);
@@ -753,13 +1004,16 @@ class Walker {
             mergeRun(call.target.hookRun, settings);
         }
     }
-    /** Counts `expect()`, `expect.soft()` and `expect.poll()`, and reads `expect.assertions(n)` and `expect.hasAssertions()`. */
+    /**
+     * Counts `expect()`, `expect.soft()`, `expect.poll()` and `expect.element()`, 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')
+        if (member === 'call' || member === 'soft' || member === 'poll' || member === 'element')
             test.expectCount += 1;
         if (member === 'hasAssertions')
             test.expectsAssertions = true;
@@ -922,6 +1176,46 @@ class Walker {
     declareTest(call, declaration, context) {
         if (context.quiet || this.nested(call, context))
             return;
+        for (const item of this.cases(declaration, call, context))
+            this.declareCase(call, item, context);
+    }
+    /**
+     * With `expandCases`, a declaration for each case of its table, with the case's title and the arguments its callback
+     * gets; otherwise, or when the scan can't give each case its title, the declaration alone, with a problem that says
+     * why.
+     */
+    cases(declaration, call, context) {
+        const single = (reason) => {
+            if (reason === null)
+                return [{ declaration, index: null, args: null }];
+            const item = problem('cases-not-expanded', call, `The cases of the table are listed as one record, since ${reason}.`);
+            return [{ declaration: { ...declaration, problems: [...declaration.problems, item] }, index: null, args: null }];
+        };
+        if (!this.options.expandCases || !declaration.isParameterized || declaration.caseCount === null)
+            return single(null);
+        if (!declaration.cases)
+            return single("the scan can't work out every value in it");
+        const title = declaration.title;
+        if (!title || title.isDynamic)
+            return single("the scan can't work out the title");
+        const titles = declaration.cases.map((item, index) => vitestCaseTitle(title.text, item.items, index, this.options.version));
+        if (titles.some((text) => text === null)) {
+            return single("the title shows an array or object, which the scan doesn't format the way Vitest does");
+        }
+        if (declaration.kind === 'describe' && this.expands(null, declaration.cases, context) === 'limit') {
+            return single(`expanding it would take the file past ${MAX_EXPANDED.toLocaleString('en-US')} loop passes and describe cases`);
+        }
+        return declaration.cases.map((item, index) => ({
+            declaration: {
+                ...declaration,
+                title: { text: titles[index], withoutTags: titles[index], isDynamic: false },
+                caseCount: 1,
+            },
+            index,
+            args: item.args.map((value) => ({ ok: true, value })),
+        }));
+    }
+    declareCase(call, { declaration, index, args }, context) {
         const statement = this.statement(call);
         const empty = emptyTitle(declaration, call);
         const test = {
@@ -932,12 +1226,16 @@ class Walker {
             declaredAt: this.declaredAt(call),
             frame: this.frame,
             registeredBy: context.registeredBy,
-            order: (context.registeredBy ?? call).start,
+            order: context.expandedAt ?? context.registeredBy?.start ?? call.start,
             states: [...declaration.states],
             annotations: [...declaration.details.annotations],
             isInLoop: context.isInLoop,
+            // A condition inside a loop decides on each pass whether the test is registered.
+            passes: context.loops,
+            loops: context.loops.map((passes, index) => context.isInCondition && !context.loopConditions[index] ? null : passes),
             isInCondition: context.isInCondition,
             isInFunction: context.isInFunction,
+            caseIndex: index ?? context.caseIndex,
             comments: this.commentsAbove(statement.start),
             run: {},
             expectCount: 0,
@@ -955,21 +1253,34 @@ class Walker {
         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,
+            this.withCase(body, args, () => {
+                this.visitCallback(body, {
+                    ...context,
+                    test,
+                    hookScope: null,
+                    hookName: null,
+                    stepDepth: 0,
+                    testContext: declaration.testContext,
+                    guards: [],
+                    helper: null,
+                });
             });
         }
     }
+    /** Runs `walk` with a case's arguments bound to the parameters of its callback, as the runner calls it. */
+    withCase(fn, args, walk) {
+        if (args)
+            this.frame.values.withArguments(fn, args, this.scopes, walk);
+        else
+            walk();
+    }
     declareSuite(call, declaration, context) {
         if (context.quiet || this.nested(call, context))
             return;
+        for (const item of this.cases(declaration, call, context))
+            this.declareSuiteCase(call, item, context);
+    }
+    declareSuiteCase(call, { declaration, index, args }, context) {
         for (const item of [...declaration.problems, ...emptyTitle(declaration, call)])
             this.report(item);
         const scope = {
@@ -994,26 +1305,34 @@ class Walker {
             declaredAt: this.declaredAt(call),
             frame: this.frame,
             registeredBy: context.registeredBy,
-            order: (context.registeredBy ?? call).start,
+            order: context.expandedAt ?? context.registeredBy?.start ?? call.start,
             cuts: [],
             isInCondition: context.isInCondition,
             isInFunction: context.isInFunction,
+            caseIndex: index ?? context.caseIndex,
         };
         scope.suite = suite;
         this.suites.push(suite);
         this.cut(context.scope, call);
         this.suiteFrames.set(suite, this.frame);
-        if (declaration.fn) {
-            this.visitCallback(declaration.fn, {
-                ...context,
-                scope,
-                test: null,
-                hookScope: null,
-                hookName: null,
-                stepDepth: 0,
-                testContext: null,
-                guards: [],
-                helper: null,
+        const { fn } = declaration;
+        if (fn) {
+            this.withCase(fn, args, () => {
+                this.visitCallback(fn, {
+                    ...context,
+                    scope,
+                    test: null,
+                    hookScope: null,
+                    hookName: null,
+                    stepDepth: 0,
+                    testContext: null,
+                    guards: [],
+                    helper: null,
+                    // The pass of a loop around the describe is the describe's, not that of each test in it.
+                    caseIndex: null,
+                    isExpanding: context.isExpanding || index !== null,
+                    expandedAt: this.expandedAt(context, index === null ? null : call.start),
+                });
             });
         }
     }
@@ -1048,6 +1367,6 @@ class Walker {
     }
 }
 /** Walks the scanned file; `openModule` reads the modules of imported helpers that the file calls. */
-export function extract(main, openModule) {
-    return new Walker(main, openModule).run();
+export function extract(main, openModule, options = { expandCases: false, version: null }) {
+    return new Walker(main, openModule, options).run();
 }

package/dist/filter.js

@@ -75,6 +75,7 @@ const TEST_KEYS = Object.keys({
     isBenchmark: true,
     isParameterized: true,
     caseCount: true,
+    caseIndex: true,
     isInLoop: true,
     isInCondition: true,
     isInFunction: true,

package/dist/framework-version.d.ts

@@ -11,6 +11,8 @@ export interface DetectedVersion {
 }
 /**
  * The framework version from the installed package, then a lockfile, then package.json, each looked for in the root
- * and the folders above it. A version range, as in `^4.0.0`, is used only when nothing else is found.
+ * and the folders above it. A version range, as in `^4.0.0`, is used only when nothing else is found. When none of
+ * those has the framework, as in a monorepo whose root leaves it to a package such as `code/`, the shallowest package
+ * below the root that declares it and holds one of the scanned `files` is read the same way, from its own folder up.
  */
-export declare function detectFrameworkVersion(root: string, framework: Framework): DetectedVersion | null;
+export declare function detectFrameworkVersion(root: string, framework: Framework, files: readonly string[]): DetectedVersion | null;

package/dist/framework-version.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { globSync } from 'tinyglobby';
 const PACKAGES = { playwright: '@playwright/test', vitest: 'vitest' };
 /** Oldest supported version of each framework. */
 export const OLDEST = { playwright: [1, 42], vitest: [3, 0] };
@@ -71,12 +72,25 @@ function declaredVersion(folder, name) {
 }
 /**
  * The framework version from the installed package, then a lockfile, then package.json, each looked for in the root
- * and the folders above it. A version range, as in `^4.0.0`, is used only when nothing else is found.
+ * and the folders above it. A version range, as in `^4.0.0`, is used only when nothing else is found. When none of
+ * those has the framework, as in a monorepo whose root leaves it to a package such as `code/`, the shallowest package
+ * below the root that declares it and holds one of the scanned `files` is read the same way, from its own folder up.
  */
-export function detectFrameworkVersion(root, framework) {
+export function detectFrameworkVersion(root, framework, files) {
     const name = PACKAGES[framework];
+    const found = detectIn(root, folders(root), name);
+    if (found)
+        return found;
+    // In path order, then shallowest first; the sort is stable, so packages as deep stay in path order.
+    const nested = globSync('**/package.json', { cwd: root, ignore: ['**/node_modules/**'] })
+        .sort()
+        .sort((a, b) => a.split('/').length - b.split('/').length)
+        .map((file) => path.dirname(file))
+        .find((folder) => files.some((file) => file.startsWith(`${folder}/`)) && declaredVersion(path.join(root, folder), name) !== null);
+    return nested === undefined ? null : detectIn(root, folders(path.join(root, nested)), name);
+}
+function detectIn(root, all, name) {
     const source = (folder, file) => path.relative(root, path.join(folder, file)).replaceAll('\\', '/');
-    const all = folders(root);
     for (const folder of all) {
         const version = installedVersion(folder, name);
         if (version)

package/dist/frameworks/common.d.ts

@@ -116,6 +116,12 @@ export declare function readOptions(file: FileContext, scopes: readonly Node[],
 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[];
+/**
+ * The members of a declared value that `name` gets: none in `const name = test`, `['describe', 'serial']` in
+ * `const { describe: { serial: name } } = test`, and none for the rest of an object, which keeps the other members.
+ * Null when it gets something else: a default, an array element, or a member under a computed key.
+ */
+export declare function boundMembers(pattern: Node, name: string): string[] | null;
 /**
  * Whether a function takes one of its parameters whole, as in `(fixtures) => ...`, or keeps the rest of its object
  * pattern, so that any key of it may be used.

package/dist/frameworks/common.js

@@ -287,6 +287,26 @@ export function destructuredNames(fn, index) {
     const names = parameter.properties.map((property) => (property.type === 'Property' ? propertyKey(property) : null));
     return names.filter((name) => name !== null);
 }
+/**
+ * The members of a declared value that `name` gets: none in `const name = test`, `['describe', 'serial']` in
+ * `const { describe: { serial: name } } = test`, and none for the rest of an object, which keeps the other members.
+ * Null when it gets something else: a default, an array element, or a member under a computed key.
+ */
+export function boundMembers(pattern, name) {
+    if (pattern.type === 'Identifier')
+        return pattern.name === name ? [] : null;
+    if (pattern.type !== 'ObjectPattern')
+        return null;
+    for (const property of pattern.properties) {
+        if (property.type === 'RestElement')
+            return boundMembers(property.argument, name);
+        const members = boundMembers(property.value, name);
+        const key = propertyKey(property);
+        if (members)
+            return key === null ? null : [key, ...members];
+    }
+    return null;
+}
 /**
  * Whether a function takes one of its parameters whole, as in `(fixtures) => ...`, or keeps the rest of its object
  * pattern, so that any key of it may be used.

package/dist/frameworks/playwright.d.ts

@@ -41,7 +41,9 @@ export declare class PlaywrightAdapter implements Adapter {
     private worthFollowing;
     /**
      * The members of `test` a variable holds: those of a describe function, as in `const serialDescribe =
-     * test.describe.serial`, or none for a test object a function returns.
+     * test.describe.serial`, none for a test object a function returns, and the member `name` takes when it is
+     * destructured, as in `const { beforeEach } = test`. Playwright binds every member to its test object, so a
+     * destructured one works as it does on the object; a test object built with a destructured `extend` is not followed.
      */
     private alias;
     /** The members of `test` a value holds: none for a test object, or those of a describe function. */