test-inventory 0.7.0 → 0.9.0

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.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;