test-inventory 0.6.1 → 0.8.0

package/dist/framework-version.js

@@ -1,8 +1,12 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-const PACKAGES = { playwright: '@playwright/test', vitest: 'vitest' };
+import { globSync } from 'tinyglobby';
+import { OptionsError } from "./options.js";
+const PACKAGES = { playwright: '@playwright/test', vitest: 'vitest', jest: 'jest' };
+/** Each framework's name in messages. */
+export const FRAMEWORK_NAMES = { playwright: 'Playwright', vitest: 'Vitest', jest: 'Jest' };
 /** Oldest supported version of each framework. */
-export const OLDEST = { playwright: [1, 42], vitest: [3, 0] };
+export const OLDEST = { playwright: [1, 42], vitest: [3, 0], jest: [29, 0] };
 /** A file's text, or null when it is missing or can't be read. */
 function readText(file) {
     try {
@@ -71,12 +75,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)
@@ -94,3 +111,45 @@ export function detectFrameworkVersion(root, framework) {
     }
     return null;
 }
+/** Config file names of each runner. A Vite config alone doesn't count, as Vite apps without Vitest have one. */
+const CONFIG_NAMES = {
+    playwright: /^playwright\.config\.[cm]?[jt]s$/,
+    vitest: /^vitest\.config\.[cm]?[jt]s$/,
+    jest: /^jest\.config\.([cm]?[jt]s|json)$/,
+};
+/** Whether a package.json lists a runner, or for Jest has a `jest` key, its config. */
+function declares(manifest, framework) {
+    const json = readJson(manifest);
+    const fields = ['devDependencies', 'dependencies', 'peerDependencies', 'optionalDependencies'];
+    return (fields.some((field) => json?.[field]?.[PACKAGES[framework]] !== undefined) ||
+        (framework === 'jest' && json?.jest !== undefined));
+}
+/**
+ * The runner a project uses, for a scan without `framework`: the one whose package a package.json in the root or a
+ * folder below it, outside `ignore`, lists, or whose config is there. Only when none is found there do the package.json files above the
+ * root count, as a monorepo may declare its runner once at its top. Throws an `OptionsError` when the project uses
+ * none of them or several, naming what it found.
+ */
+export function detectFramework(root, ignore) {
+    const below = globSync(['**/package.json', '**/*.config.*'], {
+        cwd: root,
+        ignore: ['**/node_modules/**', '**/.git/**', ...ignore],
+    });
+    const manifests = below.filter((file) => path.basename(file) === 'package.json').map((file) => path.join(root, file));
+    const above = folders(root)
+        .slice(1)
+        .map((folder) => path.join(folder, 'package.json'));
+    const all = ['playwright', 'vitest', 'jest'];
+    let found = all.filter((framework) => below.some((file) => CONFIG_NAMES[framework].test(path.basename(file))) ||
+        manifests.some((manifest) => declares(manifest, framework)));
+    if (found.length === 0)
+        found = all.filter((framework) => above.some((manifest) => declares(manifest, framework)));
+    if (found.length === 1)
+        return found[0];
+    if (found.length === 0) {
+        throw new OptionsError('options.framework is needed: no package.json in the root, below it or above it lists @playwright/test, vitest or jest, and no config of theirs is in the root or below.');
+    }
+    const names = found.map((framework) => FRAMEWORK_NAMES[framework]);
+    const values = found.map((framework) => `"${framework}"`);
+    throw new OptionsError(`options.framework is needed, as the project uses ${names.slice(0, -1).join(', ')} and ${names.at(-1)}: scan it once with each of ${values.join(', ')}.`);
+}

package/dist/frameworks/bindings.d.ts

@@ -19,6 +19,8 @@ export interface TestObjects {
     returnsTestObject(name: string): boolean;
     /** Whether re-exporting `imported` from `source` exports a test object, or a function that returns one. */
     reexports(source: string, imported: string, exported: Exported): boolean;
+    /** What the test object the module exports as `name` stands for, as `it.skip` stands for `it` with `skip`. */
+    exportedStart?(name: string): unknown;
 }
 /**
  * The functions a module declares at its top level, by name, to tell whether one returns a test object: every value it
@@ -54,6 +56,13 @@ export declare function allDeclarators(program: Program): VariableDeclarator[];
 export declare function moduleImports(program: Program, isFramework: (source: string) => boolean): Map<string, ModuleImport>;
 /** The module of `require('module')`, or null for any other expression. */
 export declare function requiredModule(expression: Expression): string | null;
+/**
+ * What a CommonJS module exports under `name`: `exports.name = value`, `module.exports.name = value` or a key of
+ * `module.exports = { ... }`, and for `default`, `module.exports` itself; the last one written wins; null otherwise.
+ */
+export declare function commonJsExport(program: Program, name: string): Expression | null;
+/** The names a CommonJS module exports one by one, as `exports.name = value` and `module.exports.name = value` do. */
+export declare function commonJsNames(program: Program): string[];
 /** What `module.exports = value` assigns, the default export of a CommonJS module; null for any other statement. */
 export declare function moduleExportsValue(statement: Node): Expression | null;
 /** Applies `bind` to each declarator until no more names are bound, so declaration order doesn't matter. */
@@ -103,10 +112,15 @@ export declare function followModule(source: string, name: string, readModule: M
 interface Followed {
     exported: boolean;
     reason: string | null;
+    /** What the exported test object stands for, when the framework's test objects say. */
+    start?: unknown;
+    /** The module writes a function under the name, a helper that registers tests itself, which the walk follows. */
+    isHelper?: boolean;
 }
 /** Follows the import of `name` in a test file, with the diagnostic to report when it isn't a test object. */
 export declare function followImport(name: string, imported: ModuleImport, readModule: ModuleReader | null, file: FileContext, framework: Framework): {
     exported: boolean;
     problem: Problem | null;
+    start: unknown;
 };
 export {};

package/dist/frameworks/bindings.js

@@ -1,4 +1,4 @@
-import { childNodes, isFunctionNode, propertyName, returnValues, unwrap } from "../ast.js";
+import { childNodes, isFunctionNode, propertyKey, propertyName, returnValues, unwrap, } from "../ast.js";
 import { parseFile } from "../parse.js";
 import { snippet } from "../source.js";
 import { problem, text } from "./common.js";
@@ -125,6 +125,18 @@ export function moduleImports(program, isFramework) {
             imports.set(specifier.local.name, { source: statement.source.value, imported, node: specifier });
         }
     }
+    // `const { test } = require('./fixtures')` imports as `import { test } from './fixtures'` does.
+    for (const declarator of topLevelDeclarators(program)) {
+        const source = declarator.init ? requiredModule(declarator.init) : null;
+        if (source === null || !/^\.\.?\//.test(source) || declarator.id.type !== 'ObjectPattern')
+            continue;
+        for (const property of declarator.id.properties) {
+            const key = property.type === 'Property' ? propertyKey(property) : null;
+            if (key !== null && property.type === 'Property' && property.value.type === 'Identifier') {
+                imports.set(property.value.name, { source, imported: key, node: declarator });
+            }
+        }
+    }
     return imports;
 }
 /** The module of `require('module')`, or null for any other expression. */
@@ -135,6 +147,59 @@ export function requiredModule(expression) {
     const argument = node.arguments.at(0);
     return argument?.type === 'Literal' && typeof argument.value === 'string' ? argument.value : null;
 }
+/**
+ * What a CommonJS module exports under `name`: `exports.name = value`, `module.exports.name = value` or a key of
+ * `module.exports = { ... }`, and for `default`, `module.exports` itself; the last one written wins; null otherwise.
+ */
+export function commonJsExport(program, name) {
+    let found = null;
+    for (const statement of program.body) {
+        const whole = moduleExportsValue(statement);
+        if (whole) {
+            const object = unwrap(whole);
+            if (name === 'default')
+                found = whole;
+            else if (object.type === 'ObjectExpression') {
+                for (const property of object.properties) {
+                    if (property.type === 'Property' && propertyKey(property) === name)
+                        found = property.value;
+                }
+            }
+            continue;
+        }
+        if (statement.type !== 'ExpressionStatement')
+            continue;
+        const expression = unwrap(statement.expression);
+        if (expression.type !== 'AssignmentExpression' || expression.left.type !== 'MemberExpression')
+            continue;
+        if (propertyName(expression.left) !== name)
+            continue;
+        const target = unwrap(expression.left.object);
+        const isExports = target.type === 'Identifier' && target.name === 'exports';
+        const isModuleExports = target.type === 'MemberExpression' &&
+            target.object.type === 'Identifier' &&
+            target.object.name === 'module' &&
+            propertyName(target) === 'exports';
+        if (isExports || isModuleExports)
+            found = expression.right;
+    }
+    return found;
+}
+/** The names a CommonJS module exports one by one, as `exports.name = value` and `module.exports.name = value` do. */
+export function commonJsNames(program) {
+    const names = new Set();
+    for (const statement of program.body) {
+        if (statement.type !== 'ExpressionStatement')
+            continue;
+        const expression = unwrap(statement.expression);
+        if (expression.type !== 'AssignmentExpression' || expression.left.type !== 'MemberExpression')
+            continue;
+        const name = propertyName(expression.left);
+        if (name !== null && commonJsExport(program, name) === expression.right)
+            names.add(name);
+    }
+    return [...names];
+}
 /** What `module.exports = value` assigns, the default export of a CommonJS module; null for any other statement. */
 export function moduleExportsValue(statement) {
     if (statement.type !== 'ExpressionStatement')
@@ -187,6 +252,9 @@ export function exportsTestObject(program, name, objects, exported = 'test objec
         case 'specifier':
             return own.source === null ? local(own.local) : objects.reexports(own.source, own.local, exported);
     }
+    const commonJs = exported === 'test object' && name !== 'default' ? commonJsExport(program, name) : null;
+    if (commonJs)
+        return objects.isTestObject(commonJs);
     return program.body.some((statement) => {
         const source = starReexport(statement);
         return source !== null && objects.reexports(source, name, exported);
@@ -382,12 +450,21 @@ function followExports(module, name, framework, exported, within, followed) {
         return { exported: false, reason: 'could not be parsed' };
     const followFrom = (from, imported, kind) => followModule(from, imported, module.readModule, framework, kind, within, followed);
     const objects = framework.testObjects(program, (from, imported, kind = 'test object') => followFrom(from, imported, kind).exported);
-    if (exportsTestObject(program, name, objects, exported))
-        return { exported: true, reason: null };
+    if (exportsTestObject(program, name, objects, exported)) {
+        return { exported: true, reason: null, start: objects.exportedStart?.(name) };
+    }
+    // A function the module writes and exports is a helper that registers tests itself, which the walk follows.
+    if (exported === 'test object' && exportsFunction(program, name)) {
+        return { exported: false, reason: null, isHelper: true };
+    }
     const unrecognized = (kind) => `does not export ${kind === 'function' ? 'a function that returns a test object' : `a ${framework.name} test object`} that could be recognized`;
     const origin = importOrigin(program, name, framework.isSource, exported);
     if (origin) {
-        const end = followFrom(origin.source, origin.imported, origin.exported).reason ?? unrecognized(origin.exported);
+        const followed = followFrom(origin.source, origin.imported, origin.exported);
+        // A helper function re-exported, as `import helper from './a'; export { helper }`, is no broken test object.
+        if (followed.isHelper && origin.how === 're-exports')
+            return followed;
+        const end = followed.reason ?? unrecognized(origin.exported);
         return { exported: false, reason: `${origin.how} it from '${origin.source}', which ${end}` };
     }
     if (importsFrom(program, framework.isSource))
@@ -397,6 +474,22 @@ function followExports(module, name, framework, exported, within, followed) {
     const call = exported === 'test object' ? creatingCall(program, name, source) : null;
     return { exported: false, reason: call ? `builds it with ${call}, which is not followed` : null };
 }
+/** Whether a module writes the function it exports as `name`: declared, written in place, or held in a variable. */
+function exportsFunction(program, name) {
+    const own = ownExport(program, name);
+    if (own?.kind === 'function')
+        return true;
+    if (own?.kind === 'default') {
+        const value = unwrap(own.value);
+        return value.type === 'FunctionDeclaration' || isFunctionNode(value);
+    }
+    const local = own?.kind === 'variable' ? name : own?.kind === 'specifier' && own.source === null ? own.local : null;
+    if (local === null)
+        return false;
+    const declared = program.body.some((statement) => statement.type === 'FunctionDeclaration' && statement.id?.name === local);
+    const declarator = topLevelDeclarators(program).find((item) => item.id.type === 'Identifier' && item.id.name === local);
+    return declared || isFunctionNode(declarator?.init ? unwrap(declarator.init) : null);
+}
 /**
  * The call that creates what the module exports as `name`, a variable or its default export, as `defineBrokerTest()`;
  * null for other values.
@@ -412,9 +505,9 @@ function creatingCall(program, name, source) {
 }
 /** Follows the import of `name` in a test file, with the diagnostic to report when it isn't a test object. */
 export function followImport(name, imported, readModule, file, framework) {
-    const { exported, reason } = followModule(imported.source, imported.imported, readModule, framework);
+    const { exported, reason, start } = followModule(imported.source, imported.imported, readModule, framework);
     const problemFound = reason
         ? problem('unresolved-test-import', imported.node, `'${name}' is imported from '${imported.source}', which ${reason}; tests that use it are missing.`, snippet(text(file, imported.node)))
         : null;
-    return { exported, problem: problemFound };
+    return { exported, problem: problemFound, start };
 }

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

@@ -185,6 +185,13 @@ export function readTitle(file, scopes, node, options) {
     if (value === null && options.functionNames && expression?.type === 'Identifier') {
         value = file.values.isFunction(expression.name, scopes) ? expression.name : null;
     }
+    // A function or class written in place gives its name, as `describe(function OrderBook() {}, ...)` does.
+    const written = expression && unwrap(expression);
+    if (value === null &&
+        options.functionNames &&
+        (written?.type === 'FunctionExpression' || written?.type === 'ClassExpression')) {
+        value = written.id?.name ?? '';
+    }
     if (value !== null) {
         const withoutTags = options.stripTags ? value.replace(/@\S+/g, ' ').replace(/\s+/g, ' ').trim() : value;
         return { title: { text: value, withoutTags, isDynamic: false }, problem: null };
@@ -287,6 +294,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/jest.d.ts

@@ -0,0 +1,46 @@
+import type { CallExpression } from 'oxc-parser';
+import type { ApiCall, CallContext, ModuleReader } from '../model.ts';
+import type { ParsedFile } from '../parse.ts';
+import type { HookCounts } from '../types.ts';
+import { type FileContext, type Link } from './common.ts';
+import { SuiteAdapter, type Kind } from './test-functions.ts';
+export declare class JestAdapter extends SuiteAdapter {
+    constructor(parsed: ParsedFile, file: FileContext, readModule: ModuleReader | null);
+    classify(call: CallExpression, context: CallContext): ApiCall | null;
+    protected isAliasLink(_kind: Kind, link: Link): boolean;
+    protected hook(call: CallExpression, name: keyof HookCounts, context: CallContext): ApiCall;
+    /**
+     * `jest.retryTimes(n, options)`. Jest keeps one count for the file and reads it as each test runs, so the last call
+     * made while the file loads applies to every test, wherever it is written. From 30.5, `entireDescribe` keeps the
+     * count for the describe it is called in instead, and retries the describe as a whole.
+     */
+    private retryCall;
+    /** Whether an expression is Jest's `jest` object: the global, a name imported from Jest, or a member of the module. */
+    private isJest;
+    private chainCall;
+    private declaration;
+    /** Whether a table makes `describe.each` throw, as jest-each does on an empty array or a value that isn't a table. */
+    private isInvalidTable;
+    /** Jest's order: `todo` and `skip` set the test's mode, `only` runs it, and `failing` applies when it runs. */
+    private states;
+    /**
+     * How many tests a table registers. No table, an empty array, or a tagged template whose first line isn't a line of names or
+     * whose values don't fill its rows, makes Jest register one test with the title as written, which fails.
+     */
+    private caseCount;
+    /**
+     * The cases of a table whose values the scan can work out, as Jest passes them: a case that is an array is spread
+     * into the callback's arguments when every case is one; otherwise each case is passed whole. A tagged template gives
+     * one object per row, keyed by the names in its first line.
+     */
+    private tableCases;
+}
+/**
+ * What jest-each's heading pattern, `/^\n\s*[^\s]+\s*(\|\s*[^\s]+\s*)*\n/`, matches at the start of a table's first
+ * string. The pattern backtracks exponentially on a long run of `|` it can't match, which a scanned file could hang the
+ * scan with, so its tries are worked out once per position, from the end. `heading[i]` is where the match ends when a
+ * heading, `\s*[^\s]+\s*`, starts at `i`, and `rest[i]` where it ends when the heading before ends at `i`: on a `|`,
+ * another heading first, else the line break. The pattern tries the whole word first, with its spaces given back one by
+ * one, then shorter words, of which only one that ends before a `|` can go on.
+ */
+export declare function headingsMatch(text: string): string | null;