Library

The package also exports the functions the command line uses. It is ESM only.

import { scan, scanSource, type Inventory } from 'test-inventory';

scan

Scans the files that match the patterns and returns the inventory. The options are the same as on the command line, in camel case.

/**
 * Scans the test files that match `patterns` under `root`, one file at a time.
 *
 * Throws a `TypeError` for invalid options. Problems with files and code are reported as diagnostics.
 */
export function scan(options: ScanOptions): Promise<Inventory>;

export interface ScanOptions {
  /** Glob patterns for the test files, relative to `root`. */
  patterns: string[];
  framework: Framework;
  /** The project root. Paths in the output are relative to it. Defaults to the current directory. */
  root?: string;
  /** Glob patterns to leave out, in addition to `node_modules`. */
  ignore?: string[];
  /** The framework version whose rules apply, instead of the one read from the project. */
  frameworkVersion?: string;
  /** Which tests get the comments above them. Defaults to `non-active`. */
  comments?: CommentsMode;
}

export type Framework = 'playwright' | 'vitest';

export type CommentsMode = 'all' | 'non-active' | 'none';

To count the tests that are always skipped in the web app:

const inventory = await scan({
  patterns: ['tests/**/*.spec.ts'],
  framework: 'playwright',
  root: 'apps/trading-web',
  ignore: ['tests/legacy/**'],
});

const skipped = inventory.tests.filter((test) => test.isSkipped && !test.isConditional);
console.log(`${skipped.length} tests are always skipped`);

scanSource

Scans the code of one file without reading anything from disk. Use it in editors, linters or tests.

/**
 * Scans the code of one test file, without reading anything from disk.
 *
 * Throws a `TypeError` for invalid options. Problems in the code itself are reported as diagnostics.
 * A custom `test` object imported from a local file can't be followed here; use `scan()` for that.
 */
export function scanSource(options: ScanSourceOptions): Inventory;

export interface ScanSourceOptions {
  code: string;
  /** Path of the file from the project root, used in the output and in ids. */
  relativeFilePath: string;
  framework: Framework;
  /** The framework version whose rules apply. The newest rules apply when it is missing. */
  frameworkVersion?: string | null;
  /** Which tests get the comments above them. Defaults to `non-active`. */
  comments?: CommentsMode;
}

To read the state of a test from code that is not on disk:

const inventory = scanSource({
  code: "import { test } from 'vitest';\ntest.todo('charges the daily borrow fee');",
  relativeFilePath: 'tests/orders/short-selling.test.ts',
  framework: 'vitest',
  frameworkVersion: '5.0.3',
});
inventory.tests[0].state; // 'todo'

Because it reads no files, scanSource cannot follow a custom test object imported from a fixtures file. Tests that use one are reported with an unresolved-test-import diagnostic; scan follows the import.

Inventory

Both functions return an inventory, the object the command line writes as JSON. The output reference describes each of its records key by key.

/** The output of one scan. */
export interface Inventory {
  /** Version of this format. It changes only when a key is removed, renamed or changes meaning. */
  schemaVersion: 1;
  tool: Tool;
  /** The framework the scan was run for. */
  framework: Framework;
  /** Read from the project, or given with `--framework-version`; null when unknown. */
  frameworkVersion: string | null;
  summary: Summary;
  suites: SuiteRecord[];
  tests: TestRecord[];
  diagnostics: Diagnostic[];
}

export interface Tool {
  name: 'test-inventory';
  /** Version of test-inventory that produced the output. */
  version: string;
}

Errors

Both functions throw a TypeError that names the option when an option is invalid. Anything about the scanned code or files becomes a diagnostic in the result.

JSON Schema

The output's JSON Schema ships with the package, under the schemaVersion it describes, so a reader can pin the version of the format it understands:

import schema from 'test-inventory/schema/v1.json' with { type: 'json' };

It is also published at huldoser.github.io/test-inventory/schema/v1.json, the URL in its $id.