test-inventory 0.8.0 → 0.9.0

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;
+}

package/dist/frameworks/jasmine.js

@@ -0,0 +1,218 @@
+import { isFunctionNode, unwrap } from "../ast.js";
+import { snippet } from "../source.js";
+import { atLeast, hookFunction, namedFunction, problem, readChain, readCount, readReason, readTitle, refused, text, } from "./common.js";
+import { SuiteAdapter } from "./test-functions.js";
+const HOOKS = ['beforeEach', 'afterEach', 'beforeAll', 'afterAll'];
+const JASMINE = {
+    name: 'Jasmine',
+    // Jasmine has no module to import its functions from: they are globals, set by the jasmine command, Karma or a
+    // browser page.
+    source: 'jasmine-core',
+    mismatched: new Set(['@playwright/test', 'playwright/test', 'vitest', '@jest/globals', 'mocha']),
+    starts: new Map([
+        ['describe', { kind: 'describe', links: [] }],
+        ['xdescribe', { kind: 'describe', links: ['skip'] }],
+        ['fdescribe', { kind: 'describe', links: ['only'] }],
+        ['it', { kind: 'test', links: [] }],
+        ['xit', { kind: 'test', links: ['skip'] }],
+        ['fit', { kind: 'test', links: ['only'] }],
+    ]),
+    hooks: new Map(HOOKS.map((name) => [name, name])),
+    derivations: new Set(),
+    modifiers: new Set(),
+    carriesKinds: false,
+    isModule: () => false,
+    defaultImport: null,
+    required: null,
+};
+/**
+ * Marks what runs with each spec, the spec and its `beforeEach` and `afterEach` hooks, where `pending()` marks the spec
+ * pending, and a describe, around which Jasmine catches what its callback throws.
+ */
+const IN_SPEC = Symbol('in a spec');
+const IN_DESCRIBE = Symbol('in a describe');
+export 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. */
+    refusedEffect = 'Jasmine stops before it runs any spec';
+    /** Whether a number after a spec's timeout is a retry count, as WebdriverIO reads it. */
+    trailingRetries = false;
+    constructor(parsed, file, readModule) {
+        super(parsed, file, readModule, JASMINE, []);
+    }
+    classify(call, context) {
+        return this.pendingCall(call, context) ?? this.hookCall(call, context) ?? this.chainCall(call, context);
+    }
+    isAliasLink() {
+        return false;
+    }
+    hook(call, name, context) {
+        const fn = hookFunction(this.file, context.scopes, call.arguments);
+        // In `beforeAll` and `afterAll`, `pending()` is an error of the describe, and the specs keep the state they get.
+        const testContext = name === 'beforeEach' || name === 'afterEach' ? IN_SPEC : null;
+        return { kind: 'hook', name, fn, testContext, fixtures: [], takesAllFixtures: false };
+    }
+    /**
+     * `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).
+     */
+    pendingCall(call, context) {
+        const callee = unwrap(call.callee);
+        if (callee.type !== 'Identifier' || context.testContext !== IN_SPEC)
+            return null;
+        const isPending = callee.name === 'pending';
+        const isNotApplicable = callee.name === 'notApplicable' && atLeast(this.file.version, 7, 0);
+        if (!isPending && !isNotApplicable)
+            return null;
+        if (this.file.values.declarationOf(callee.name, context.scopes) !== null)
+            return null;
+        const reason = readReason(this.file, context.scopes, call.arguments.at(0));
+        return {
+            kind: 'modifier',
+            state: 'skip',
+            condition: { applies: 'always', text: null },
+            reason: reason.reason,
+            hasDynamicReason: reason.isDynamic,
+            problems: reason.problem ? [reason.problem] : [],
+        };
+    }
+    chainCall(call, context) {
+        const chain = readChain(call.callee);
+        if (!chain)
+            return null;
+        const resolved = this.resolve(chain, call.arguments, context);
+        if (!resolved)
+            return null;
+        const { kind, links } = resolved;
+        const callee = snippet(text(this.file, call.callee));
+        // Jasmine's functions have no members: `xit` and `fit` carry their modifier in the name.
+        if (chain.links.length === 0)
+            return this.declaration(call, kind, links, context);
+        const refusal = this.refusal('invalid-chain', call, `${callee} is not part of Jasmine's API`, context);
+        return refused(call, refusal, context, () => this.declaration(call, kind, [], context));
+    }
+    declaration(call, kind, links, context) {
+        const args = call.arguments;
+        const callee = snippet(text(this.file, call.callee));
+        // Jasmine registers `it()` as a pending spec titled '', and refuses a describe without a function.
+        if (args.length === 0 && kind === 'describe') {
+            return {
+                kind: 'invalid',
+                problem: this.refusal('test-without-body', call, `${callee}() has no function`, context),
+            };
+        }
+        const flags = new Set(links.map((link) => link.name));
+        const problems = [];
+        let title = { text: '', withoutTags: '', isDynamic: false };
+        if (args.length > 0) {
+            const read = readTitle(this.file, context.scopes, args[0], { stripTags: false, functionNames: false });
+            title = read.title;
+            if (read.problem)
+                problems.push(read.problem);
+        }
+        const spread = args.some((arg) => arg.type === 'SpreadElement');
+        const written = spread ? null : args.at(1);
+        // `undefined` given as the function is no function, as when none is given.
+        const body = written?.type === 'Identifier' && written.name === 'undefined' ? undefined : written;
+        const fn = isFunctionNode(body) ? body : null;
+        const line = this.file.source.line(call.start);
+        // A spec without a function is pending, unless it is focused: `fit` needs one.
+        const isSkipped = flags.has('skip') || (kind === 'test' && body === undefined);
+        const base = {
+            title,
+            states: isSkipped
+                ? [{ state: 'skip', condition: null, reason: null, hasDynamicReason: false, line }]
+                : [],
+            isOnly: flags.has('only'),
+            mode: null,
+            details: { tags: [], annotations: [], locks: [], meta: null, run: {} },
+            fn,
+            hashed: fn ?? namedFunction(this.file, context.scopes, body ?? undefined),
+            isParameterized: false,
+            caseCount: null,
+            cases: null,
+            problems,
+        };
+        if (kind === 'test') {
+            const declared = {
+                kind: 'test',
+                ...base,
+                testContext: IN_SPEC,
+                fixtures: [],
+                takesAllFixtures: false,
+                usesBench: false,
+            };
+            const timeout = spread ? undefined : args.at(2);
+            if (timeout && timeout.type !== 'SpreadElement') {
+                const option = { node: timeout, resolved: this.file.values.resolve(timeout, context.scopes) };
+                const value = readCount(this.file, 'timeout', option, problems);
+                if (value !== null)
+                    declared.details.run = { timeout: value };
+            }
+            const retries = this.trailingRetries && !spread ? args.at(3) : undefined;
+            if (retries && retries.type !== 'SpreadElement') {
+                const option = { node: retries, resolved: this.file.values.resolve(retries, context.scopes) };
+                const count = readCount(this.file, 'retries', option, problems);
+                if (count !== null)
+                    declared.details.run = { ...declared.details.run, retry: { count, delay: null, condition: null } };
+            }
+            if (body === null || (body === undefined ? !flags.has('only') : isFunctionLike(body)))
+                return declared;
+            const reason = body === undefined ? `${callee}() has no function` : `${callee}() takes a function second`;
+            return refused(call, this.refusal('test-without-body', call, reason, context), context, () => declared);
+        }
+        const declared = { kind: 'describe', ...base, isShuffled: false, passesDown: IN_DESCRIBE };
+        if (body === null)
+            return declared;
+        if (body === undefined || !isFunctionLike(body)) {
+            const refusal = this.refusal('test-without-body', call, `${callee}() has no function`, context);
+            return refused(call, refusal, context, () => declared);
+        }
+        if (fn?.async) {
+            const refusal = this.refusal('async-describe', fn, 'The describe callback is async, which Jasmine refuses', context);
+            return refused(call, refusal, context, () => declared);
+        }
+        if (fn && declaresNothing(fn)) {
+            const refusal = this.refusal('describe-throws', fn, 'The describe declares no spec or describe, which Jasmine refuses', context);
+            return refused(call, refusal, context, () => declared);
+        }
+        if (fn && fn.params.length > 0) {
+            const refusal = this.refusal('describe-throws', fn, 'The describe callback takes arguments, which Jasmine refuses', context);
+            return refused(call, refusal, context, () => declared);
+        }
+        return declared;
+    }
+    /**
+     * 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.
+     */
+    refusal(code, node, what, context) {
+        const source = snippet(text(this.file, node));
+        if (context.passedDown !== IN_DESCRIBE) {
+            return problem(code, node, `${what}, so ${this.refusedEffect}.`, source);
+        }
+        const message = `${what}, so the describe around it throws: Jasmine reports it as failed, and registers none of the specs written after this call in it.`;
+        return { ...problem(code, node, message, source), afterLoad: true };
+    }
+}
+/**
+ * Whether a describe callback surely declares nothing: its body is empty or holds only hook calls. A call to anything
+ * else, as a helper that declares specs, may declare some.
+ */
+function declaresNothing(fn) {
+    if (fn.body?.type !== 'BlockStatement')
+        return false;
+    return fn.body.body.every((statement) => {
+        if (statement.type !== 'ExpressionStatement')
+            return false;
+        const expression = unwrap(statement.expression);
+        if (expression.type !== 'CallExpression')
+            return false;
+        const callee = unwrap(expression.callee);
+        return callee.type === 'Identifier' && HOOKS.includes(callee.name);
+    });
+}
+/** Whether an argument may be a function: anything but a value that can't be one, as a number or an object. */
+function isFunctionLike(node) {
+    const value = unwrap(node);
+    return !['Literal', 'ObjectExpression', 'ArrayExpression', 'TemplateLiteral'].includes(value.type);
+}

package/dist/frameworks/jest.js

@@ -19,7 +19,7 @@ const JEST = {
         ['fdescribe', { kind: 'describe', links: ['only'] }],
         ['xdescribe', { kind: 'describe', links: ['skip'] }],
     ]),
-    hooks: new Set(['beforeEach', 'afterEach', 'beforeAll', 'afterAll']),
+    hooks: new Map(['beforeEach', 'afterEach', 'beforeAll', 'afterAll'].map((name) => [name, name])),
     derivations: new Set(),
     modifiers: new Set(['only', 'skip', 'todo', 'concurrent', 'failing']),
     carriesKinds: false,

package/dist/frameworks/mocha.d.ts

@@ -0,0 +1,50 @@
+import type { Argument, CallExpression } from 'oxc-parser';
+import type { ApiCall, CallContext, ModuleReader, SuiteDeclaration, TestDeclaration } 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 Dialect, type Kind } from './test-functions.ts';
+/** The interfaces Mocha's `ui` option names whose globals the scan reads; QUnit and exports declare tests otherwise. */
+export type MochaInterface = 'bdd' | 'tdd';
+export declare function dialect(ui: MochaInterface): Dialect;
+export declare class MochaAdapter extends SuiteAdapter {
+    /**
+     * Whether `this.timeout()` and `this.retries()` set the tests' settings, as in Mocha. Cypress reads neither, and its
+     * `retries()` throws.
+     */
+    protected readonly readsContextSettings: boolean;
+    /** What the runner does with a call it refuses while it loads the file, as the end of a sentence. */
+    protected readonly refusedEffect: string;
+    /** Whether a number after a test's function is a retry count, as WebdriverIO reads it. */
+    protected readonly trailingRetries: boolean;
+    constructor(parsed: ParsedFile, file: FileContext, readModule: ModuleReader | null, ui?: MochaInterface, runner?: Dialect);
+    /** A declaration's function, and the options written before it; Mocha takes none. */
+    protected splitArguments(args: CallExpression['arguments']): {
+        body: Argument | undefined;
+        options: Argument | null;
+    };
+    /** Sets on a declaration what the options written before its function set; Mocha takes none. */
+    protected withOptions?(declared: TestDeclaration | SuiteDeclaration, options: Argument, context: CallContext): void;
+    classify(call: CallExpression, context: CallContext): ApiCall | null;
+    protected isAliasLink(_kind: Kind, link: Link): boolean;
+    protected hook(call: CallExpression, name: keyof HookCounts, context: CallContext): ApiCall;
+    /**
+     * `this.timeout(n)`, `this.retries(n)` and `this.skip()` where `this` is Mocha's context: in a describe written as a
+     * `function`, they set its tests' timeout and retries; in a test, its own; `this.skip()` in a test or hook skips the
+     * tests it runs for. In a hook, `this.timeout()` sets the hook's own timeout, which no test record holds.
+     */
+    private contextCall;
+    /**
+     * `it(title, fn).timeout(n)` and `.retries(n)`, which Mocha's `it` and `describe` return their test or suite for: the
+     * declaration with the setting. A describe's tests are added before the call, and take its retries when they are
+     * added, so `describe(...).retries(n)` reaches none of them; its timeout reaches them from Mocha 12, which reads it as
+     * each test runs (checked with 10.8.2, 11.7.5 and 12.0.3).
+     */
+    private chainedSetting;
+    /** A timeout or a retry count from its argument; null, with a warning, when it can't be worked out. */
+    private setting;
+    private chainCall;
+    private declaration;
+}
+/** A timeout in milliseconds or a retry count as Mocha reads it; null for a value it doesn't take. */
+export declare function durationOf(value: unknown, name: 'timeout' | 'retries'): number | null;