test-inventory 0.2.0 → 0.3.0

package/dist/frameworks/playwright.js

@@ -1,7 +1,7 @@
 import { childNodes, isFunctionNode, propertyKey, propertyName, unwrap } from "../ast.js";
 import { snippet } from "../source.js";
-import { allDeclarators, bindAll, exportName, followImport, followModule, moduleImports, requiredModule, } from "./bindings.js";
-import { atLeast, findFunction, isTestName, isTitleLiteral, localTestObject, looksLikeDeclaration, mayDeclareTests, mayHoldTestObject, namedFunction, origin, problem, readChain, readCondition, readOptions, readReason, readStrings, readTitle, text, unresolvedOption, unresolvedOptions, } from "./common.js";
+import { allDeclarators, bindAll, exportName, followImport, followModule, moduleImports, ModuleFunctions, requiredModule, } from "./bindings.js";
+import { atLeast, findFunction, isTestName, isTitleLiteral, localTestObject, looksLikeDeclaration, mayDeclareTests, mayHoldTestObject, namedFunction, origin, problem, readChain, readCondition, readOptions, readReason, readStrings, readTitle, refused, returnedFunction, returnedTestObject, text, unresolvedOption, unresolvedOptions, } from "./common.js";
 const MISMATCHED_SOURCES = new Set(['vitest', '@jest/globals']);
 // Maps rather than object literals, so names such as `constructor` don't match inherited properties.
 const DESCRIBES = new Map([
@@ -24,8 +24,17 @@ const STATES = new Map([
 ]);
 /** Members of `test` that are known but don't declare or modify tests. */
 const OTHER_MEMBERS = new Set(['use', 'slow', 'setTimeout', 'extend']);
+/** First members of chains that never declare a test, even when Playwright refuses the rest of the chain. */
+const NOT_DECLARING = new Set(['step', 'abort', ...HOOKS, ...OTHER_MEMBERS]);
 /** First members that show a name imported from a local file is used as Playwright's `test`. */
 const TEST_MEMBERS = new Set(['describe', 'only', 'skip', 'fixme', 'fail', 'step', ...HOOKS]);
+/** The members of `test` a value chosen at run time holds either way: those both have, if both are the same kind. */
+function sharedMembers(a, b) {
+    if (!a || !b || (a[0] === 'describe') !== (b[0] === 'describe'))
+        return null;
+    const differs = a.findIndex((name, index) => b[index] !== name);
+    return differs === -1 ? a : a.slice(0, differs);
+}
 /** Calls that need a newer Playwright than the oldest supported one. */
 const ADDED_IN = new Map([
     ['fail.only', [1, 49]],
@@ -50,9 +59,12 @@ class PlaywrightBindings {
     /** Names imported from other modules, which may be test objects there. */
     imported;
     follow;
+    /** The module's functions and the variables they may build test objects in; see `ModuleFunctions`. */
+    functions;
     constructor(program, follow) {
         this.imported = moduleImports(program, (source) => isPlaywrightSource(source) || MISMATCHED_SOURCES.has(source));
         this.follow = follow;
+        this.functions = new ModuleFunctions(program, this.imported, follow);
         for (const statement of program.body) {
             if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type')
                 continue;
@@ -78,41 +90,59 @@ class PlaywrightBindings {
                 }
             }
         }
-        bindAll(allDeclarators(program), (declarator) => {
+        const declarators = allDeclarators(program);
+        bindAll(declarators, (declarator) => {
             const bound = this.bind(declarator);
             if (bound)
                 this.declarations.add(declarator);
             return bound;
         });
+        this.functions.keep(declarators.filter((declarator) => !this.declarations.has(declarator)));
     }
     isTestName(name) {
-        return this.testNames.has(name) || this.importsTestObject(name);
+        return this.testNames.has(name) || this.importsTestObject(name) || this.holdsTestObject(name);
     }
-    isTestObject(expression) {
+    /**
+     * `followsCalls` is cleared where a call is not followed to what it returns: while the names are bound, so that only
+     * a value asked about is followed, as following reads other modules, and in the scanned file, whose calls the walk
+     * follows in their scopes.
+     */
+    isTestObject(expression, followsCalls = true) {
         const node = unwrap(expression);
         switch (node.type) {
             case 'Identifier':
-                return this.testNames.has(node.name) || this.importsTestObject(node.name);
+                return (this.testNames.has(node.name) ||
+                    this.importsTestObject(node.name) ||
+                    (followsCalls && this.holdsTestObject(node.name)));
             case 'MemberExpression':
                 return propertyName(node) === 'test' && this.isModule(node.object);
             case 'ConditionalExpression':
                 // `process.env.CI ? ciTest : test` is a test object either way.
-                return this.isTestObject(node.consequent) || this.isTestObject(node.alternate);
+                return this.isTestObject(node.consequent, followsCalls) || this.isTestObject(node.alternate, followsCalls);
             case 'CallExpression': {
                 const callee = unwrap(node.callee);
                 if (callee.type === 'MemberExpression' && propertyName(callee) === 'extend') {
-                    return this.isTestObject(callee.object);
+                    return this.isTestObject(callee.object, followsCalls);
                 }
+                // `mergeTests(a, b)`, or `defineBrokerTest()`, a function that returns a test object.
                 return callee.type === 'Identifier'
-                    ? this.mergeTestsNames.has(callee.name)
+                    ? this.mergeTestsNames.has(callee.name) || (followsCalls && this.returnsTestObject(callee.name))
                     : callee.type === 'MemberExpression' && propertyName(callee) === 'mergeTests' && this.isModule(callee.object);
             }
             default:
                 return false;
         }
     }
-    reexports(source, imported) {
-        return isPlaywrightSource(source) ? imported === 'test' || imported === 'default' : this.follow(source, imported);
+    returnsTestObject(name) {
+        return this.functions.returnsTestObject(name, (expression) => this.isTestObject(expression));
+    }
+    holdsTestObject(name) {
+        return this.functions.holdsTestObject(name, (expression) => this.isTestObject(expression));
+    }
+    reexports(source, imported, exported) {
+        if (!isPlaywrightSource(source))
+            return this.follow(source, imported, exported);
+        return exported === 'test object' && (imported === 'test' || imported === 'default');
     }
     /** Whether a name is imported from another module that exports it as a test object, as `base` from './base'. */
     importsTestObject(name) {
@@ -141,7 +171,7 @@ class PlaywrightBindings {
                 }
                 return true;
             }
-            if (this.isTestObject(init)) {
+            if (this.isTestObject(init, false)) {
                 this.testNames.add(id.name);
                 return true;
             }
@@ -176,6 +206,7 @@ export class PlaywrightAdapter {
     imports;
     followed = new Map();
     reported = new Set();
+    /** Variables and names of functions read as test objects on trust, each reported once. */
     assumed = new Set();
     aliases = new Map();
     constructor(program, file, readModule) {
@@ -184,10 +215,11 @@ export class PlaywrightAdapter {
         // A test object the file builds from an imported one, as in `const test = base.extend({...})`, is followed
         // quietly: a call through the import itself is what reports an import that can't be followed.
         const followed = new Map();
-        this.bindings = new PlaywrightBindings(program, (source, imported) => {
-            const key = `${source}\0${imported}`;
-            if (!followed.has(key))
-                followed.set(key, followModule(source, imported, readModule, PLAYWRIGHT).exported);
+        this.bindings = new PlaywrightBindings(program, (source, imported, exported = 'test object') => {
+            const key = `${source}\0${exported}\0${imported}`;
+            if (!followed.has(key)) {
+                followed.set(key, followModule(source, imported, readModule, PLAYWRIGHT, exported).exported);
+            }
             return followed.get(key) === true;
         });
         this.problems = [...this.bindings.mismatches];
@@ -195,21 +227,22 @@ export class PlaywrightAdapter {
     }
     classify(call, context) {
         const chain = readChain(call.callee);
-        const links = chain ? this.testLinks(chain, call.arguments, context.scopes, context.inBody) : null;
+        const links = chain ? this.testLinks(chain, call.arguments, context) : null;
         if (!links)
             return null;
         const names = links.map((link) => link.name);
         const key = names.join('.');
         const addedIn = ADDED_IN.get(key);
         if (addedIn && !atLeast(this.file.version, ...addedIn)) {
-            return this.invalid(call, `needs Playwright ${addedIn.join('.')} or newer`);
+            return this.invalid(call, names, `needs Playwright ${addedIn.join('.')} or newer`, context);
         }
         if (names[0] === 'info')
             return this.annotationsPush(call, links, context);
         if (names[0] === 'expect' || names[0] === 'step' || key === 'abort')
             return { kind: 'other' };
-        if (links.some((link) => link.args ?? link.template))
-            return this.invalid(call, "is not part of Playwright's API");
+        if (links.some((link) => link.args ?? link.template)) {
+            return this.invalid(call, names, "is not part of Playwright's API", context);
+        }
         if (key === '' || key === 'only' || key === 'skip' || key === 'fixme' || key === 'fail' || key === 'fail.only') {
             return this.testCall(call, key, context);
         }
@@ -222,54 +255,74 @@ export class PlaywrightAdapter {
             return { kind: 'hook', fn: findFunction(call.arguments), testContext: null };
         if (OTHER_MEMBERS.has(key))
             return { kind: 'other' };
-        return this.invalid(call, "is not part of Playwright's API");
+        return this.invalid(call, names, "is not part of Playwright's API", context);
     }
     /**
      * The links after the `test` object, or null when the chain doesn't start from Playwright's `test`. An import that
      * can't be followed is reported only outside test and hook bodies, where a call can declare tests.
      */
-    testLinks(chain, args, scopes, inBody) {
+    testLinks(chain, args, lookup) {
+        const links = this.linksFromTest(chain, args, lookup);
+        if (!links)
+            return null;
+        // A test object derived inline, as in `base.extend({ ... }).describe(...)`.
+        return links.slice(links.findLastIndex((link) => link.name === 'extend' && link.args) + 1);
+    }
+    linksFromTest(chain, args, lookup) {
         const { base, links } = chain;
-        let start;
+        const { scopes, inBody } = lookup;
+        const withMembers = (members) => [
+            ...members.map((name) => ({ name, args: null, template: null })),
+            ...links,
+        ];
         if (base.type === 'Identifier') {
             // A local variable or parameter with the same name, such as `(test) => test.result()`, is not Playwright's.
             const declaration = this.file.values.declarationOf(base.name, scopes);
             const bound = declaration !== null && this.bindings.declarations.has(declaration);
             const local = declaration !== null && this.imports.get(base.name)?.node === declaration;
-            const alias = declaration?.type === 'VariableDeclarator' && !bound && !local
-                ? this.describeAlias(declaration, scopes, inBody)
-                : null;
+            const alias = declaration?.type === 'VariableDeclarator' && !bound && !local ? this.alias(declaration, lookup) : null;
             // The module from `require()` is both the namespace and `test`, so `pw.test(...)` reads as the namespace.
             if (bound && this.bindings.namespaces.has(base.name) && links[0]?.name === 'test' && !links[0].args) {
-                start = 1;
-            }
-            else if (bound && this.bindings.testNames.has(base.name)) {
-                start = 0;
+                return links.slice(1);
             }
-            else if (alias) {
-                return [...alias.map((name) => ({ name, args: null, template: null })), ...links];
-            }
-            else if (local &&
-                this.looksLikeTest(links, args) &&
+            if (bound && this.bindings.testNames.has(base.name))
+                return links;
+            if (alias)
+                return withMembers(alias);
+            if (local &&
+                this.worthFollowing(base.name, links, args) &&
                 this.follow(base.name, !inBody && mayDeclareTests(base.name, links))) {
-                start = 0;
-            }
-            else if (declaration !== null && !bound && this.assumeLocal(declaration, base.name, links, args)) {
-                start = 0;
-            }
-            else {
-                return null;
+                return links;
             }
+            return declaration !== null && !bound && this.assumeLocal(declaration, base.name, links, args) ? links : null;
         }
-        else if (this.bindings.isModule(base) && links[0]?.name === 'test' && !links[0].args) {
-            start = 1;
-        }
-        else {
+        if (this.bindings.isModule(base) && links[0]?.name === 'test' && !links[0].args)
+            return links.slice(1);
+        const members = base.type === 'CallExpression' ? this.returned(base, links, args, lookup) : null;
+        return members && withMembers(members);
+    }
+    /**
+     * The members of `test` a call returns: none for a test object, as `conditionalTest({ min: 22 })` may return, or
+     * those of a describe function. As for a variable chosen by a condition, only the members all its values have apply.
+     * When the function can't be found, a call named like a test object is read as one on trust, with a warning.
+     */
+    returned(call, links, args, lookup) {
+        const callee = unwrap(call.callee);
+        if (callee.type !== 'Identifier')
             return null;
+        const returns = lookup.returnsOf(callee.name, lookup.scopes);
+        if (returns)
+            return returnedFunction(returns, sharedMembers);
+        if (!isTestName(callee.name) || !this.looksLikeTest(links, args))
+            return null;
+        if (!this.assumed.has(callee.name)) {
+            this.assumed.add(callee.name);
+            this.problems.push(returnedTestObject(this.file, call));
         }
-        // A test object derived inline, as in `base.extend({ ... }).describe(...)`.
-        const derived = links.findLastIndex((link) => link.name === 'extend' && link.args);
-        return links.slice(Math.max(start, derived + 1));
+        return [];
+    }
+    testFunction(expression, scopes, returnsOf) {
+        return this.members(expression, { scopes, inBody: false, returnsOf });
     }
     /** Whether a local variable is read as a test object it could be; see `localTestObject`. */
     assumeLocal(declaration, name, links, args) {
@@ -286,33 +339,42 @@ export class PlaywrightAdapter {
     looksLikeTest(links, args) {
         return links.length === 0 ? looksLikeDeclaration(args) : TEST_MEMBERS.has(links[0].name);
     }
-    /** The members of `test` a variable holds a describe function from, as in `const serialDescribe = test.describe.serial`. */
-    describeAlias(declarator, scopes, inBody) {
+    /**
+     * Whether a call through an imported name is worth following to the module: shaped like a test, or any call with a
+     * title and a body through a name that reads like a test function, as `it.effect('title', fn)` on a test object that
+     * a package extends.
+     */
+    worthFollowing(name, links, args) {
+        return this.looksLikeTest(links, args) || (isTestName(name) && looksLikeDeclaration(args));
+    }
+    /**
+     * 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.
+     */
+    alias(declarator, lookup) {
         let members = this.aliases.get(declarator);
         if (members === undefined) {
             // Set first, so a variable defined through itself ends the lookup.
             this.aliases.set(declarator, null);
-            members = declarator.init ? this.describeMembers(declarator.init, scopes, inBody) : null;
+            members = declarator.init ? this.members(declarator.init, lookup) : null;
             this.aliases.set(declarator, members);
         }
         return members;
     }
-    describeMembers(expression, scopes, inBody) {
+    /** The members of `test` a value holds: none for a test object, or those of a describe function. */
+    members(expression, lookup) {
         const node = unwrap(expression);
         if (node.type === 'ConditionalExpression') {
             // `IS_PLATFORM ? test.describe.serial : test.describe`: only the members both branches have apply.
-            const consequent = this.describeMembers(node.consequent, scopes, inBody);
-            const alternate = this.describeMembers(node.alternate, scopes, inBody);
-            if (!consequent || !alternate)
-                return null;
-            const shared = consequent.findIndex((name, index) => alternate[index] !== name);
-            return shared === -1 ? consequent : consequent.slice(0, shared);
+            return sharedMembers(this.members(node.consequent, lookup), this.members(node.alternate, lookup));
         }
+        if (this.bindings.isTestObject(node, false))
+            return [];
         const chain = readChain(node);
         if (!chain || chain.links.some((link) => link.args ?? link.template))
             return null;
-        const members = this.testLinks(chain, [], scopes, inBody)?.map((link) => link.name);
-        return members && DESCRIBES.has(members.join('.')) ? members : null;
+        const members = this.testLinks(chain, [], lookup)?.map((link) => link.name);
+        return members && (members.length === 0 || DESCRIBES.has(members.join('.'))) ? members : null;
     }
     /** Follows the import of `name` once, and reports it once when it can't be followed and `report` is set. */
     follow(name, report) {
@@ -339,9 +401,15 @@ export class PlaywrightAdapter {
         const resolved = this.file.values.resolve(node, context.scopes);
         return resolved.ok && typeof resolved.value === 'string';
     }
-    invalid(call, reason) {
+    /** A chain Playwright refuses; one that starts like a declaration also declares a plain test or describe. */
+    invalid(call, names, reason, context) {
         const callee = snippet(text(this.file, call.callee));
-        return { kind: 'invalid', problem: problem('invalid-chain', call, `${callee} ${reason}.`, callee) };
+        const refusal = problem('invalid-chain', call, `${callee} ${reason}.`, callee);
+        return refused(call, refusal, context, () => {
+            if (NOT_DECLARING.has(names[0]))
+                return { kind: 'other' };
+            return names.includes('describe') ? this.describeCall(call, {}, context) : this.testCall(call, '', context);
+        });
     }
     testCall(call, key, context) {
         const args = call.arguments;
@@ -442,6 +510,7 @@ export class PlaywrightAdapter {
             isOnly: kind.only === true,
             mode: kind.mode ?? null,
             isShuffled: false,
+            passesDown: null,
             details: this.details(!anonymous && args.length === 3 ? args[1] : undefined, context, problems, title?.text ?? ''),
             fn,
             hashed: fn,

package/dist/frameworks/vitest.d.ts

@@ -1,7 +1,13 @@
-import type { CallExpression } from 'oxc-parser';
+import type { CallExpression, Expression, Node } from 'oxc-parser';
 import type { Adapter, ApiCall, CallContext, ModuleReader, Problem } from '../model.ts';
 import type { ParsedFile } from '../parse.ts';
-import { type FileContext } from './common.ts';
+import { type FileContext, type Link } from './common.ts';
+type Kind = 'test' | 'describe';
+/** A test or describe function and the links after it, as in `test.skipIf(isCI)`. */
+interface TestFunction {
+    kind: Kind;
+    links: Link[];
+}
 export declare class VitestAdapter implements Adapter {
     readonly problems: Problem[];
     readonly fileTags: string[];
@@ -12,6 +18,7 @@ export declare class VitestAdapter implements Adapter {
     private readonly imports;
     private readonly followed;
     private readonly reported;
+    /** Variables and names of functions read as test objects on trust, each reported once. */
     private readonly assumed;
     private readonly aliases;
     /** Describe callbacks and the name of their first parameter, which Vitest calls with its `test`. */
@@ -19,6 +26,7 @@ export declare class VitestAdapter implements Adapter {
     private warnedAboutTags;
     constructor(parsed: ParsedFile, file: FileContext, readModule: ModuleReader | null);
     classify(call: CallExpression, context: CallContext): ApiCall | null;
+    testFunction(expression: Expression, scopes: readonly Node[], returnsOf: CallContext['returnsOf']): TestFunction | null;
     /** A call to `bench` imported from Vitest 5, which is undefined there, so the call throws. */
     private benchCall;
     private chainCall;
@@ -31,9 +39,21 @@ export declare class VitestAdapter implements Adapter {
     /** The function and modifiers a variable holds, as in `const skipOnCi = test.skipIf(isCI)`. */
     private alias;
     private aliasOf;
+    /**
+     * The function a call returns, as `conditionalTest({ min: 22 })` returns `it` or `it.skip`: what all the values the
+     * function returns have in common, as for a variable chosen by a condition. When the function can't be found, a call
+     * named like a test object is read as one on trust, with a warning; see `returnedTestObject`.
+     */
+    private returned;
     /** Whether a local variable is read as a test object it could be; see `localTestObject`. */
     private assumeLocal;
     private looksLikeTest;
+    /**
+     * Whether a call through an imported name is worth following to the module: shaped like a test, or any call with a
+     * title and a body through a name that reads like a test function, as `it.effect('title', fn)` on a test object that
+     * a package extends.
+     */
+    private worthFollowing;
     /** Vitest as followed modules are read, with the rules of the scanned version. */
     private framework;
     /** Follows the import of `name` once, and reports it once when it can't be followed and `report` is set. */
@@ -54,3 +74,4 @@ export declare class VitestAdapter implements Adapter {
     private arrayLength;
     private tagsUsed;
 }
+export {};