@aljazmc/testero 0.4.2 → 0.5.0

package/bin/types/arguments.d.ts

@@ -2,12 +2,16 @@ import type { Rules } from "./rules.js";
 import type { Options } from "./testero.js";
 /** Command line arguments, named like Jest's. */
 export default class Arguments {
-    static readonly usage = "Usage: testero [patterns...] [options]\n\nRuns the test files whose paths match a pattern, every test file without patterns.\n\nOptions:\n  -t, --testNamePattern <regex>  run only tests whose name matches\n  --bail                         stop after the first failing test file\n  --verbose                      list every test\n  --listTests                    print the test files instead of running them\n  --passWithNoTests              succeed when there are no test files\n  --testTimeout <ms>             milliseconds a test or hook may take\n  --config [js]                  write the default testero.config.ts, or .js\n  -h, --help                     show this help\n";
+    static readonly usage = "Usage: testero [patterns...] [options]\n\nRuns the test files whose paths match a pattern, every test file without patterns.\n\nOptions:\n  -t, --testNamePattern <regex>  run only tests whose name matches\n  --bail                         stop after the first failing test file\n  --verbose                      list every test\n  --listTests                    print the test files instead of running them\n  --passWithNoTests              succeed when there are no test files\n  --testTimeout <ms>             milliseconds a test or hook may take\n  --coverage                     report which lines and functions the tests run\n  --watch                        rerun the tests of changed files and what imports them\n  --watchAll                     rerun every test when a file changes\n  --config [js]                  write the default testero.config.ts, or .js\n  -h, --help                     show this help\n";
     readonly patterns: string[];
     readonly rules: Partial<Rules>;
     namePattern: RegExp | undefined;
     listTests: boolean;
     help: boolean;
+    /** Reruns the tests of changed files, or all of them, when files change. */
+    watch: "related" | "all" | undefined;
+    /** The options, without the patterns and the watch ones, for the runs of watch mode. */
+    readonly flags: string[];
     constructor(argv: string[]);
     /** The configured rules, with the ones given on the command line instead. */
     options(rules: Rules): Options;

package/bin/types/coverage.d.ts

@@ -0,0 +1,63 @@
+/** How often the tests called a function of a file. */
+export interface FunctionCoverage {
+    name: string;
+    /** The line it starts on, from 1. */
+    line: number;
+    count: number;
+}
+/** The coverage of one source file. */
+export interface FileCoverage {
+    /** The path of the file, relative to the root. */
+    file: string;
+    /** How often each line with code ran, by its number from 1. */
+    lines: Map<number, number>;
+    /** The functions by where they start, like `3:10`. */
+    functions: Map<string, FunctionCoverage>;
+    /** Whether a test loaded the file, one no test loads is not covered at all. */
+    loaded: boolean;
+}
+/** How much of something ran. */
+export interface Ratio {
+    covered: number;
+    total: number;
+}
+/** A source map mapping, from a place in the generated code to one in a source, all from 0. */
+export interface Segment {
+    line: number;
+    column: number;
+    source: number;
+    sourceLine: number;
+    sourceColumn: number;
+}
+/**
+ * Measures which lines and functions of the sources the tests run, with V8's
+ * own coverage, mapped back to the sources by the source maps of the bundles.
+ * Every test file is bundled with the sources it imports, so the counts of a
+ * source are the sums of its copies.
+ */
+export default class Coverage {
+    #private;
+    /** Reports the files, relative to the root, that `tracks` takes. */
+    constructor(root: string, tracks: (file: string) => boolean);
+    /** Starts counting, before the tests load. */
+    start(): Promise<void>;
+    /**
+     * The coverage of the tracked sources of the bundles, by their paths,
+     * and of the files no test loaded, sorted by path.
+     */
+    collect(bundles: ReadonlyMap<string, string>, unloaded?: Iterable<string>): Promise<FileCoverage[]>;
+    /** The mappings of a source map with a source, in order, its base64 VLQs decoded. */
+    static decode(mappings: string): Segment[];
+    /** How many of the lines with code ran. */
+    static lines(coverage: FileCoverage): Ratio;
+    /** How many of the functions ran. */
+    static functions(coverage: FileCoverage): Ratio;
+    /** The sums of ratios. */
+    static sum(ratios: Ratio[]): Ratio;
+    /** A percentage like Jest's, 100 when there is nothing to run, unless nothing loaded it. */
+    static percent(ratio: Ratio, loaded?: boolean): number;
+    /** The lines that did not run, in ranges like `3-5,9`. */
+    static uncovered(coverage: FileCoverage): string;
+    /** The coverage in the lcov format editors and services read. */
+    static lcov(root: string, files: FileCoverage[]): string;
+}

package/bin/types/expect/assertion.d.ts

@@ -52,7 +52,10 @@ export default class Assertion {
     get resolves(): Assertion & Matchers;
     /** The assertion on why a promise rejects, its matchers return promises. */
     get rejects(): Assertion & Matchers;
-    /** Adds a matcher to every assertion, like `expect.extend`. */
-    static define(name: string, matcher: Matcher): void;
+    /**
+     * Adds a matcher to the assertions of a class: Assertion itself for the
+     * built in ones, the class of one test file for `expect.extend`.
+     */
+    static define(target: typeof Assertion, name: string, matcher: Matcher): void;
 }
 export {};

package/bin/types/expect/equality.d.ts

@@ -12,4 +12,6 @@ export default class Equality {
     static equals(a: unknown, b: unknown, strict?: boolean): boolean;
     /** Whether received has every property expected has, recursively, like `toMatchObject`. */
     static matches(received: unknown, expected: unknown): boolean;
+    /** The bytes of an ArrayBuffer, SharedArrayBuffer or DataView, undefined for other values. */
+    static bytes(value: unknown): Uint8Array | undefined;
 }

package/bin/types/expect/matchers.d.ts

@@ -8,7 +8,7 @@ export interface MatcherContext {
     isNot: boolean;
     promise: "" | "resolves" | "rejects";
 }
-export type Matcher = (this: MatcherContext, received: unknown, ...expected: any[]) => MatcherResult;
+export type Matcher = (this: MatcherContext, received: unknown, ...expected: any[]) => MatcherResult | Promise<MatcherResult>;
 /** The first line of a failure message, like `expect(received).not.toBe(expected)`. */
 export declare const hint: (context: MatcherContext, name: string, expected?: string) => string;
 /** Jest's matchers, `this` tells whether `.not`, `.resolves` or `.rejects` were used. */

package/bin/types/reporter.d.ts

@@ -1,3 +1,4 @@
+import { type FileCoverage } from "./coverage.js";
 import type { Result } from "./runner.js";
 /** The outcome of one test file. */
 export interface FileResult {
@@ -22,6 +23,8 @@ export default class Reporter {
     file(result: FileResult): void;
     /** Counts of test files and tests, and the time they took. */
     summary(files: FileResult[], duration: number): void;
+    /** The coverage of each file in a table like Jest's, under the totals. */
+    coverage(files: FileCoverage[]): void;
     /** Explains that no test files were found. */
     none(patterns: string[]): void;
 }

package/bin/types/rules.d.ts

@@ -16,4 +16,13 @@ export interface Rules {
     resetMocks: boolean;
     /** Restores every spy to the original before each test. */
     restoreMocks: boolean;
+    /** Measures which lines and functions of the sources the tests run. */
+    collectCoverage: boolean;
+    /**
+     * Globs of the files coverage is reported for, also when no test loads
+     * them, "!" excludes; empty reports the files the tests load.
+     */
+    collectCoverageFrom: string[];
+    /** Where `lcov.info` is written, relative to the root. */
+    coverageDirectory: string;
 }

package/bin/types/runner.d.ts

@@ -26,6 +26,11 @@ export default class Runner {
         results: Result[];
         errors: unknown[];
     }>;
+    /**
+     * Fails the running test or hook with an error thrown outside of it, like
+     * from a timer it started. Returns false when nothing is running.
+     */
+    fail(error: unknown): boolean;
     /** Whether a test runs: not skipped, focused when others are, matching the name pattern. */
     runs(test: Test): boolean;
 }

package/bin/types/transformer.d.ts

@@ -1,3 +1,4 @@
+import { type Loader } from "esbuild";
 /**
  * Compiles a test file and the local files it imports with esbuild, into one
  * module Node can import. Installed packages stay external, and the globals
@@ -9,9 +10,16 @@ export default class Transformer {
     static readonly modules: string[];
     /** Where compiled test files go, stack frames there are testero's own. */
     static readonly prefix: string;
-    constructor();
+    /** The code of each compiled module by its path, with an inline source map, for coverage. */
+    readonly bundles: Map<string, string>;
+    /** Keeps the code of the compiled modules in `bundles` when told. */
+    constructor(keep?: boolean);
     /** Bundles a test file, returns the URL of the module to import. */
     compile(file: string): Promise<string>;
+    /** The absolute paths of the local files a test file is bundled from, itself included. */
+    inputs(file: string): Promise<string[]>;
+    /** The esbuild loader of a source file, undefined for files it does not compile. */
+    static loader(path: string): Loader | undefined;
     /** Removes the compiled files. */
     dispose(): void;
 }

package/bin/types/watcher.d.ts

@@ -0,0 +1,52 @@
+/** Test files to run, or all of them. */
+export type Selection = string[] | "all";
+/** A run in progress. */
+export interface Run {
+    /** Settles when the run is over, also when it was stopped. */
+    done: Promise<unknown>;
+    stop(): void;
+}
+export interface WatcherOptions {
+    /** Reruns every test file on a change, or only the ones it concerns. */
+    mode: "all" | "related";
+    /** Starts a run of test files, of all of them when undefined. */
+    run: (files: string[] | undefined) => Run;
+    /** The test files that changed paths, relative to the root, concern. */
+    related: (changed: ReadonlySet<string>) => Promise<string[]>;
+    /** Calls back with each changed path relative to the root, returns how to stop. */
+    subscribe: (listener: (path: string) => void) => () => void;
+    /** Whether a change to a path, relative to the root, is left alone. */
+    ignores?: (path: string) => boolean;
+    /** Keys, like `a` to run all tests, come from it when given. */
+    input?: NodeJS.ReadStream | undefined;
+    write?: (text: string) => void;
+    /** Clears the screen before each run. */
+    clear?: boolean;
+    /** Milliseconds to wait for more changes, as saving often writes several files. */
+    delay?: number;
+}
+/**
+ * Reruns tests when files change. A change during a run stops it, the next
+ * run takes its files too.
+ */
+export default class Watcher {
+    #private;
+    constructor(options: WatcherOptions);
+    /** Runs all tests, then watches. */
+    start(): void;
+    /** Stops watching and the run in progress. */
+    close(): void;
+    /** Two selections in one, all when either is. */
+    static merge(a: Selection | undefined, b: Selection): Selection;
+}
+/**
+ * Which test files changed paths concern: changed ones, and the ones bundled
+ * from a changed file. The files of each test are remembered until one of
+ * them changes; a test file that does not compile always counts.
+ */
+export declare class Dependencies {
+    #private;
+    /** `list` gives the files a test file is bundled from, all relative to the root. */
+    constructor(list: (file: string) => Promise<string[]>);
+    related(tests: string[], changed: ReadonlySet<string>): Promise<string[]>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aljazmc/testero",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A simple, Jest-like test runner for JavaScript, TypeScript and JSX, compiling tests with esbuild. Easy to understand, easy to customize and easy to extend.",
   "author": "aljazmc",
   "license": "MIT",
@@ -35,11 +35,10 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@jest/globals": "^30.5.2",
     "@types/node": "^26.6.6"
   },
   "dependencies": {
-    "@aljazmc/config": "^0.3.1",
+    "@aljazmc/config": "^0.3.2",
     "esbuild": "0.28.2"
   }
 }