test-inventory 0.7.0 → 0.9.0

package/dist/frameworks/bun.js

@@ -0,0 +1,272 @@
+import { isFunctionNode, unwrap } from "../ast.js";
+import { bunCaseTitle } from "../case-titles.js";
+import { snippet } from "../source.js";
+import { requiredModule } from "./bindings.js";
+import { atLeast, hookFunction, namedFunction, problem, readChain, readCondition, readCount, readOptions, readTitle, refused, text, unresolvedOptions, } from "./common.js";
+import { SuiteAdapter } from "./test-functions.js";
+const SOURCE = 'bun:test';
+/** Bun rewrites imports of these to `bun:test` in its test files. */
+const ALIASES = new Set(['@jest/globals', 'vitest']);
+/** The modes a chain may hold one of each group of, as Bun throws on a second. */
+const GROUPS = [new Set(['skip', 'todo', 'failing']), new Set(['only']), new Set(['concurrent', 'serial'])];
+const MODES = new Set(GROUPS.flatMap((group) => [...group]));
+const CONDITIONS = new Set(['if', 'skipIf', 'todoIf', 'failingIf', 'concurrentIf', 'serialIf']);
+const MODIFIERS = new Set([...MODES, ...CONDITIONS, 'each']);
+const BUN = {
+    name: 'Bun',
+    source: SOURCE,
+    aliases: ALIASES,
+    mismatched: new Set(['@playwright/test', 'playwright/test', 'mocha']),
+    starts: new Map([
+        ['test', { kind: 'test', links: [] }],
+        ['it', { kind: 'test', links: [] }],
+        ['describe', { kind: 'describe', links: [] }],
+        ['xtest', { kind: 'test', links: ['skip'] }],
+        ['xit', { kind: 'test', links: ['skip'] }],
+        ['xdescribe', { kind: 'describe', links: ['skip'] }],
+    ]),
+    hooks: new Map(['beforeEach', 'afterEach', 'beforeAll', 'afterAll'].map((name) => [name, name])),
+    derivations: new Set(),
+    modifiers: MODIFIERS,
+    carriesKinds: false,
+    isModule: (expression) => {
+        const source = requiredModule(expression);
+        return source === SOURCE || (source !== null && ALIASES.has(source));
+    },
+    defaultImport: null,
+    required: null,
+};
+/**
+ * Bun's `bun test`, from 1.2.23, which runs its tests the way 1.3 and 1.4 do. Its functions are globals in test files,
+ * and imports of `bun:test`, `@jest/globals` and `vitest` give them too. A chain holds its modes in any order, one of
+ * each group, and the conditions `if`, `skipIf`, `todoIf`, `failingIf`, `concurrentIf` and `serialIf` as often as
+ * it likes; options go second or third.
+ */
+export class BunAdapter extends SuiteAdapter {
+    constructor(parsed, file, readModule) {
+        super(parsed, file, readModule, BUN, MODIFIERS);
+    }
+    classify(call, context) {
+        return this.hookCall(call, context) ?? this.chainCall(call, context);
+    }
+    isAliasLink(_kind, link) {
+        return MODIFIERS.has(link.name);
+    }
+    /** A hook; before Bun 1.3, one given more than its function fails the file. */
+    hook(call, name, context) {
+        const fn = hookFunction(this.file, context.scopes, call.arguments);
+        if (call.arguments.length > 1 && !atLeast(this.file.version, 1, 3)) {
+            const callee = snippet(text(this.file, call.callee));
+            const message = `${callee}() takes only its function before Bun 1.3, so Bun fails the file and runs none of its tests.`;
+            return { kind: 'invalid', problem: problem('invalid-chain', call, message, callee) };
+        }
+        return { kind: 'hook', name, fn, testContext: null, fixtures: [], takesAllFixtures: false };
+    }
+    chainCall(call, context) {
+        const chain = readChain(call.callee);
+        const resolved = chain ? this.resolve(chain, call.arguments, context) : null;
+        if (!resolved)
+            return null;
+        const { kind, links } = resolved;
+        const last = links.at(-1);
+        if ((last?.name === 'each' || CONDITIONS.has(last?.name ?? '')) && !last?.args)
+            return { kind: 'other' };
+        if (this.isValid(kind, links, context))
+            return this.declaration(call, kind, links, context);
+        const callee = snippet(text(this.file, call.callee));
+        const refusal = problem('invalid-chain', call, `${callee} is not part of Bun's API; the call throws, and Bun fails the file and runs none of its tests.`, callee);
+        return refused(call, refusal, context, () => this.declaration(call, kind, [], context));
+    }
+    /**
+     * Whether Bun takes a chain: one of `skip`, `todo` and `failing`, one `only`, one of `concurrent` and `serial`, and
+     * one table, where a condition that holds counts as its mode, as `if(false)` counts as `skip`; the conditions and
+     * the table called and the modes not; and no `failing` on a describe. A condition the scan can't work out counts as
+     * not holding (checked with Bun 1.2.23, 1.3.14 and 1.4.4).
+     */
+    isValid(kind, links, context) {
+        if (!links.every((link) => MODIFIERS.has(link.name)))
+            return false;
+        const called = links.every((link) => (MODES.has(link.name) ? !link.args : link.args !== null) && !link.template);
+        if (!called)
+            return false;
+        const modes = links.flatMap((link) => {
+            if (!CONDITIONS.has(link.name))
+                return [link.name];
+            const holds = this.condition(link, context).applies === (link.name === 'if' ? 'never' : 'always');
+            return holds ? [link.name === 'if' ? 'skip' : link.name.slice(0, -2)] : [];
+        });
+        if ([...GROUPS, new Set(['each'])].some((group) => modes.filter((name) => group.has(name)).length > 1)) {
+            return false;
+        }
+        return kind !== 'describe' || !modes.includes('failing');
+    }
+    condition(link, context) {
+        return readCondition(this.file, context.scopes, link.args.at(0));
+    }
+    declaration(call, kind, links, context) {
+        const args = call.arguments;
+        const callee = snippet(text(this.file, call.callee));
+        const problems = [];
+        const { title, problem: titleProblem } = readTitle(this.file, context.scopes, args[0], {
+            stripTags: false,
+            functionNames: true,
+        });
+        if (titleProblem)
+            problems.push(titleProblem);
+        const spread = args.some((arg) => arg.type === 'SpreadElement');
+        // (title, fn, options) or (title, options, fn); a number is the timeout.
+        const [second, third] = [args.at(1), args.at(2)];
+        const fnSecond = third === undefined || isFunctionLike(second);
+        const body = spread ? undefined : fnSecond ? second : third;
+        const options = spread ? undefined : fnSecond ? third : second;
+        const fn = isFunctionNode(body) ? body : null;
+        const names = new Set(links.map((link) => link.name));
+        const line = this.file.source.line(call.start);
+        const states = this.states(links, line, context);
+        const table = links.find((link) => link.name === 'each') ?? null;
+        const run = this.options(options, problems, context);
+        const base = {
+            title,
+            states,
+            isOnly: names.has('only'),
+            mode: this.mode(links, context),
+            details: { tags: [], annotations: [], locks: [], meta: null, run },
+            fn,
+            hashed: fn ?? namedFunction(this.file, context.scopes, body),
+            isParameterized: table !== null,
+            caseCount: table ? this.caseCount(table, problems, context) : null,
+            cases: table ? this.tableCases(table, title, context) : null,
+            problems,
+        };
+        const declared = kind === 'describe'
+            ? { kind: 'describe', ...base, isShuffled: false, passesDown: null }
+            : { kind: 'test', ...base, testContext: null, fixtures: [], takesAllFixtures: false, usesBench: false };
+        // Only a skipped or todo test may leave out its function.
+        const mayLeaveOut = kind === 'test' && (names.has('skip') || names.has('todo'));
+        const rows = table?.args?.at(0);
+        const resolvedRows = rows && rows.type !== 'SpreadElement' ? this.file.values.resolve(rows, context.scopes) : null;
+        if (resolvedRows?.ok && !Array.isArray(resolvedRows.value)) {
+            const source = snippet(text(this.file, rows));
+            const refusal = problem('invalid-chain', rows, `.each() takes an array, and ${source} is not one, so Bun fails the file and runs none of its tests.`, source);
+            return refused(call, refusal, context, () => declared);
+        }
+        // Bun wants a function second or third; a value that can't be one, as options alone, is none.
+        const missing = body === undefined || isValue(body);
+        if (missing && !spread && !mayLeaveOut) {
+            const refusal = problem('test-without-body', call, `${callee}() has no function, so Bun fails the file and runs none of its tests.`, callee);
+            return refused(call, refusal, context, () => declared);
+        }
+        // Bun refuses a retry above 0 with any repeats, 0 too.
+        if (run.retry && run.retry.count > 0 && run.repeats !== undefined && atLeast(this.file.version, 1, 3)) {
+            const refusal = problem('invalid-chain', options, `${callee}() sets both retry and repeats, which Bun refuses from 1.3, so it fails the file and runs none of its tests.`, snippet(text(this.file, options)));
+            return refused(call, refusal, context, () => declared);
+        }
+        return declared;
+    }
+    /**
+     * The states of a chain, as Bun ranks them: `skip` over `todo` over `failing`. `if(condition)` skips when the
+     * condition is false; `skipIf`, `todoIf` and `failingIf` set theirs when it is true.
+     */
+    states(links, line, context) {
+        const setting = (state, condition) => ({
+            state,
+            condition,
+            reason: null,
+            hasDynamicReason: false,
+            line,
+        });
+        const states = [];
+        for (const link of links) {
+            if (link.name === 'skip')
+                states.push(setting('skip', null));
+            else if (link.name === 'todo')
+                states.push(setting('todo', null));
+            else if (link.name === 'failing')
+                states.push(setting('expectedToFail', null));
+            if (!['if', 'skipIf', 'todoIf', 'failingIf'].includes(link.name))
+                continue;
+            let condition = this.condition(link, context);
+            if (link.name === 'if')
+                condition = negated(condition);
+            if (condition.applies === 'never')
+                continue;
+            const state = link.name === 'todoIf' ? 'todo' : link.name === 'failingIf' ? 'expectedToFail' : 'skip';
+            states.push(setting(state, condition.applies === 'always' ? null : condition.text));
+        }
+        const rank = ['skip', 'todo', 'expectedToFail'];
+        return states.sort((a, b) => rank.indexOf(a.state) - rank.indexOf(b.state));
+    }
+    /** `concurrent` runs the test with others at once, and `serial` alone, also as `concurrentIf` and `serialIf` that hold. */
+    mode(links, context) {
+        for (const link of links) {
+            const holds = !link.name.endsWith('If') || this.condition(link, context).applies === 'always';
+            if (holds && (link.name === 'concurrent' || link.name === 'concurrentIf'))
+                return 'parallel';
+            if (holds && (link.name === 'serial' || link.name === 'serialIf'))
+                return 'default';
+        }
+        return null;
+    }
+    /** A number as the timeout, or an object with `timeout`, `retry` and `repeats`. */
+    options(node, problems, context) {
+        const run = {};
+        if (node === undefined || isFunctionLike(node))
+            return run;
+        const expression = unwrap(node);
+        const resolved = this.file.values.resolve(expression, context.scopes);
+        if (resolved.ok && typeof resolved.value === 'number') {
+            const value = readCount(this.file, 'timeout', { node: expression, resolved }, problems);
+            if (value !== null)
+                run.timeout = value;
+            return run;
+        }
+        const read = readOptions(this.file, context.scopes, node);
+        problems.push(...unresolvedOptions(this.file, read, 'its timeout, retry and repeats are missing'));
+        for (const key of ['timeout', 'retry', 'repeats']) {
+            const option = read.values.get(key);
+            const value = option ? readCount(this.file, key, option, problems) : null;
+            if (value === null)
+                continue;
+            if (key === 'retry')
+                run.retry = { count: value, delay: null, condition: null };
+            else
+                run[key] = value;
+        }
+        return run;
+    }
+    /** How many tests a table registers: one per item; null with a warning when the scan can't count them. */
+    caseCount(table, problems, context) {
+        const cases = table.args.at(0);
+        const length = cases ? this.arrayLength(cases, context) : null;
+        const resolved = cases && cases.type !== 'SpreadElement' ? this.file.values.resolve(cases, context.scopes) : null;
+        // A table that isn't an array fails the file, which is reported where the call is read.
+        if (length === null && cases && !resolved?.ok) {
+            const source = snippet(text(this.file, cases));
+            problems.push(problem('unresolved-cases', cases, 'The cases of .each() could not be counted; caseCount is null.', source));
+        }
+        return length;
+    }
+    /** The cases of a table the scan can work out: an item that is an array is spread into the arguments, another is one. */
+    tableCases(table, title, context) {
+        const first = table.args.at(0);
+        const resolved = first && first.type !== 'SpreadElement' ? this.file.values.resolve(first, context.scopes) : null;
+        if (!resolved?.ok || !Array.isArray(resolved.value))
+            return null;
+        return resolved.value.map((item, index) => {
+            const row = Array.isArray(item) ? item : [item];
+            return { title: title.isDynamic ? null : bunCaseTitle(title.text, row, index, this.file.version), args: row };
+        });
+    }
+}
+function negated(condition) {
+    if (condition.applies === 'sometimes')
+        return { applies: 'sometimes', text: `!(${condition.text})` };
+    return { applies: condition.applies === 'always' ? 'never' : 'always', text: null };
+}
+function isFunctionLike(node) {
+    return node !== undefined && node.type !== 'SpreadElement' && isFunctionNode(unwrap(node));
+}
+/** Whether an argument is a value that can't be a function, as a literal or an object. */
+function isValue(node) {
+    return ['Literal', 'ObjectExpression', 'ArrayExpression', 'TemplateLiteral'].includes(unwrap(node).type);
+}

package/dist/frameworks/common.d.ts

@@ -63,7 +63,9 @@ export declare function returnedFunction<T>(returns: Returns, shared: (a: T | nu
 export declare function looksLikeDeclaration(args: readonly Argument[]): boolean;
 /**
  * A call the runner refuses. Shaped like a declaration outside any test or hook, it is also declared, without what
- * makes it fail, so that its tests, and those of a describe, are listed as not loaded rather than missing.
+ * makes it fail, so that its tests, and those of a describe, are listed as not loaded rather than missing. Inside a
+ * test or hook body, a test or describe is nested, whatever its arguments: the runner refuses it when the test runs,
+ * and the file still loads.
  */
 export declare function refused(call: CallExpression, refusal: Problem, context: CallContext, declare: () => ApiCall): ApiCall;
 /**

package/dist/frameworks/common.js

@@ -132,10 +132,18 @@ export function looksLikeDeclaration(args) {
 }
 /**
  * A call the runner refuses. Shaped like a declaration outside any test or hook, it is also declared, without what
- * makes it fail, so that its tests, and those of a describe, are listed as not loaded rather than missing.
+ * makes it fail, so that its tests, and those of a describe, are listed as not loaded rather than missing. Inside a
+ * test or hook body, a test or describe is nested, whatever its arguments: the runner refuses it when the test runs,
+ * and the file still loads.
  */
 export function refused(call, refusal, context, declare) {
-    const declared = context.inBody || !looksLikeDeclaration(call.arguments) ? null : declare();
+    if (context.inBody) {
+        const nested = declare();
+        if (nested.kind === 'test' || nested.kind === 'describe')
+            return nested;
+        return { kind: 'invalid', problem: refusal };
+    }
+    const declared = looksLikeDeclaration(call.arguments) ? declare() : null;
     // A declaration refused for a second reason as well, as for its options, is reported for the first.
     const found = declared?.kind === 'invalid' ? declared.declaration : declared;
     const declaration = found?.kind === 'test' || found?.kind === 'describe' ? found : undefined;
@@ -151,13 +159,7 @@ export function mayDeclareTests(name, links) {
 }
 /** A function declared in the file and passed by name, as in `test('fills an order', checkFill)`; null otherwise. */
 export function namedFunction(file, scopes, node) {
-    if (node?.type !== 'Identifier')
-        return null;
-    const declaration = file.values.declarationOf(node.name, scopes);
-    if (declaration?.type === 'FunctionDeclaration')
-        return declaration;
-    const init = declaration?.type === 'VariableDeclarator' && declaration.init ? unwrap(declaration.init) : null;
-    return isFunctionNode(init) ? init : null;
+    return node?.type === 'Identifier' ? file.values.functionOf(node.name, scopes) : null;
 }
 export function findFunction(args, from = 0) {
     for (const arg of args.slice(from)) {
@@ -185,6 +187,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 };

package/dist/frameworks/cypress.d.ts

@@ -0,0 +1,31 @@
+import type { Argument, CallExpression } from 'oxc-parser';
+import type { CallContext, ModuleReader, SuiteDeclaration, TestDeclaration } from '../model.ts';
+import type { ParsedFile } from '../parse.ts';
+import { type FileContext } from './common.ts';
+import { MochaAdapter } from './mocha.ts';
+/**
+ * Cypress runs its specs on its own copy of Mocha's BDD interface. A test or describe takes Cypress's settings as an
+ * object before its function, as `it(title, { retries: 2 }, fn)`, and Cypress sets no Mocha timeout or retries from
+ * `this`.
+ */
+export declare class CypressAdapter extends MochaAdapter {
+    protected readonly readsContextSettings = false;
+    protected readonly refusedEffect = "Cypress fails the spec and runs none of its tests";
+    constructor(parsed: ParsedFile, file: FileContext, readModule: ModuleReader | null);
+    protected splitArguments(args: CallExpression['arguments']): {
+        body: Argument | undefined;
+        options: Argument | null;
+    };
+    /**
+     * Cypress's test config: `retries`, a count or `{ runMode, openMode }`, of which `cypress run` takes `runMode`;
+     * `browser`, which skips the test in the browsers it leaves out; `@cypress/grep`'s `tags`; and `env`, which Cypress
+     * 16 refuses in a test's config.
+     */
+    protected withOptions(declared: TestDeclaration | SuiteDeclaration, options: Argument, context: CallContext): void;
+    /**
+     * A retry count, or `runMode` of `{ runMode, openMode }`, which `cypress run` uses; null when it is `null`, which
+     * Cypress takes as no retries set, or can't be worked out.
+     */
+    private retryCount;
+    private count;
+}

package/dist/frameworks/cypress.js

@@ -0,0 +1,70 @@
+import { unwrap } from "../ast.js";
+import { snippet } from "../source.js";
+import { atLeast, problem, readCount, readOptions, readStrings, text, unresolvedOptions, } from "./common.js";
+import { dialect, MochaAdapter } from "./mocha.js";
+/**
+ * Cypress runs its specs on its own copy of Mocha's BDD interface. A test or describe takes Cypress's settings as an
+ * object before its function, as `it(title, { retries: 2 }, fn)`, and Cypress sets no Mocha timeout or retries from
+ * `this`.
+ */
+export class CypressAdapter extends MochaAdapter {
+    readsContextSettings = false;
+    refusedEffect = 'Cypress fails the spec and runs none of its tests';
+    constructor(parsed, file, readModule) {
+        super(parsed, file, readModule, 'bdd', { ...dialect('bdd'), name: 'Cypress', source: 'cypress' });
+    }
+    splitArguments(args) {
+        // Cypress takes the config only before a function: `it(title, { retries: 2 })` gives Mocha the object as the test's
+        // function, so the test runs, and fails.
+        if (args.length >= 3)
+            return { body: args.at(2), options: args.at(1) };
+        return { body: args.at(1), options: null };
+    }
+    /**
+     * Cypress's test config: `retries`, a count or `{ runMode, openMode }`, of which `cypress run` takes `runMode`;
+     * `browser`, which skips the test in the browsers it leaves out; `@cypress/grep`'s `tags`; and `env`, which Cypress
+     * 16 refuses in a test's config.
+     */
+    withOptions(declared, options, context) {
+        const read = readOptions(this.file, context.scopes, options);
+        const { problems, details } = declared;
+        problems.push(...unresolvedOptions(this.file, read, 'its retries, tags and browser are missing'));
+        const retries = read.values.get('retries');
+        if (retries) {
+            const count = this.retryCount(retries, context, problems);
+            if (count !== null)
+                details.run = { ...details.run, retry: { count, delay: null, condition: null } };
+        }
+        const tags = read.values.get('tags');
+        if (tags)
+            details.tags.push(...readStrings(this.file, context.scopes, tags).values);
+        const browser = read.values.get('browser');
+        if (browser) {
+            const line = this.file.source.line(browser.node.start);
+            const condition = `browser: ${snippet(text(this.file, browser.node))}`;
+            declared.states.push({ state: 'skip', condition, reason: null, hasDynamicReason: false, line });
+        }
+        const env = read.values.get('env');
+        if (env && atLeast(this.file.version, 16, 0)) {
+            const source = snippet(text(this.file, env.node));
+            const message = "Cypress 16 no longer takes env in a test's or describe's config, and fails each test it applies to when the test runs; expose: { KEY: value } sets a value the browser reads.";
+            problems.push(problem('removed-api', env.node, message, source));
+        }
+    }
+    /**
+     * A retry count, or `runMode` of `{ runMode, openMode }`, which `cypress run` uses; null when it is `null`, which
+     * Cypress takes as no retries set, or can't be worked out.
+     */
+    retryCount(option, context, problems) {
+        const node = unwrap(option.node);
+        if (node.type !== 'ObjectExpression')
+            return this.count('retries', option, problems);
+        const runMode = readOptions(this.file, context.scopes, node).values.get('runMode');
+        return runMode ? this.count('retries.runMode', runMode, problems) : null;
+    }
+    count(name, option, problems) {
+        if (option.resolved.ok && option.resolved.value === null)
+            return null;
+        return readCount(this.file, name, option, problems);
+    }
+}

package/dist/frameworks/jasmine.d.ts

@@ -0,0 +1,28 @@
+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 } from './common.ts';
+import { SuiteAdapter } from './test-functions.ts';
+export declare class JasmineAdapter extends SuiteAdapter {
+    /** What the runner does with a call it refuses at the top level of a file, as the end of a sentence. */
+    protected readonly refusedEffect: string;
+    /** Whether a number after a spec's timeout is a retry count, as WebdriverIO reads it. */
+    protected readonly trailingRetries: boolean;
+    constructor(parsed: ParsedFile, file: FileContext, readModule: ModuleReader | null);
+    classify(call: CallExpression, context: CallContext): ApiCall | null;
+    protected isAliasLink(): boolean;
+    protected hook(call: CallExpression, name: keyof HookCounts, context: CallContext): ApiCall;
+    /**
+     * `pending(reason)` in a spec or its `beforeEach` or `afterEach` hook, and from Jasmine 7 `notApplicable(reason)`,
+     * which mark the spec as not run, with the reason (checked with Jasmine 4.6.0, 5.13.0 and 7.0.0).
+     */
+    private pendingCall;
+    private chainCall;
+    private declaration;
+    /**
+     * A call Jasmine refuses: written at the top level of a file, it stops Jasmine before it runs any spec; inside a
+     * describe, Jasmine catches it, reports the describe as failed, and registers none of the specs written after it there.
+     */
+    private refusal;
+}