@aljazmc/testero 0.1.6 → 0.2.1

package/bin/types/arguments.d.ts

@@ -0,0 +1,14 @@
+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  -h, --help                     show this help\n";
+    readonly patterns: string[];
+    readonly rules: Partial<Rules>;
+    namePattern: RegExp | undefined;
+    listTests: boolean;
+    help: boolean;
+    constructor(argv: string[]);
+    /** The configured rules, with the ones given on the command line instead. */
+    options(rules: Rules): Options;
+}

package/bin/types/collector.d.ts

@@ -0,0 +1,37 @@
+import { type Body, type HookKind, Suite } from "./suite.js";
+type TestFunction = (name: string, body?: Body, timeout?: number) => void;
+type DescribeFunction = (name: string, body: () => unknown) => void;
+type Table = (table: unknown, ...values: unknown[]) => unknown;
+/** `test` and `it`, with `only`, `skip`, `todo` and `each`. */
+export interface TestApi extends TestFunction {
+    only: TestFunction & {
+        each: Table;
+    };
+    skip: TestFunction & {
+        each: Table;
+    };
+    todo: (name: string) => void;
+    each: Table;
+}
+/** `describe`, with `only`, `skip` and `each`. */
+export interface DescribeApi extends DescribeFunction {
+    only: DescribeFunction & {
+        each: Table;
+    };
+    skip: DescribeFunction & {
+        each: Table;
+    };
+    each: Table;
+}
+/** Collects what a test file declares into a tree of suites. */
+export default class Collector {
+    #private;
+    readonly root: Suite;
+    readonly describe: DescribeApi;
+    readonly test: TestApi;
+    /** Ends collection, tests cannot be declared while tests run. */
+    close(): void;
+    /** `beforeAll`, `afterAll`, `beforeEach` or `afterEach`. */
+    readonly hook: (kind: HookKind) => (body: Body, timeout?: number) => void;
+}
+export {};

package/bin/types/config.d.ts

@@ -0,0 +1,6 @@
+import type { Rules } from "./rules.js";
+declare const _default: {
+    ignore: string[];
+    rules: Rules;
+};
+export default _default;

package/bin/types/each.d.ts

@@ -0,0 +1,11 @@
+/** Rows and titles of `test.each` and `describe.each`. */
+export default class Each {
+    #private;
+    /**
+     * The argument lists of a table: rows of arrays are spread, other rows
+     * are one argument, and a tagged template gives one object per row.
+     */
+    static rows(table: unknown, values: unknown[]): unknown[][];
+    /** A title with `$name` properties of an object row, or printf placeholders. */
+    static title(title: string, args: unknown[], index: number): string;
+}

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

@@ -0,0 +1,58 @@
+import { type Matcher, type MatcherContext } from "./matchers.js";
+/** A failed expectation, its message says what was expected and received. */
+export declare class AssertionError extends Error {
+    name: string;
+}
+type Result = void | Promise<void>;
+/** The matchers an assertion has, each throwing an AssertionError when it fails. */
+export interface Matchers {
+    toBe(expected: unknown): Result;
+    toEqual(expected: unknown): Result;
+    toStrictEqual(expected: unknown): Result;
+    toMatchObject(expected: object): Result;
+    toBeDefined(): Result;
+    toBeUndefined(): Result;
+    toBeNull(): Result;
+    toBeNaN(): Result;
+    toBeTruthy(): Result;
+    toBeFalsy(): Result;
+    toBeGreaterThan(expected: number | bigint): Result;
+    toBeGreaterThanOrEqual(expected: number | bigint): Result;
+    toBeLessThan(expected: number | bigint): Result;
+    toBeLessThanOrEqual(expected: number | bigint): Result;
+    toBeCloseTo(expected: number, digits?: number): Result;
+    toBeInstanceOf(expected: unknown): Result;
+    toContain(expected: unknown): Result;
+    toContainEqual(expected: unknown): Result;
+    toHaveLength(expected: number): Result;
+    toHaveProperty(path: string | PropertyKey[], value?: unknown): Result;
+    toMatch(expected: string | RegExp): Result;
+    toThrow(expected?: unknown): Result;
+    toHaveBeenCalled(): Result;
+    toHaveBeenCalledTimes(expected: number): Result;
+    toHaveBeenCalledWith(...expected: unknown[]): Result;
+    toHaveBeenLastCalledWith(...expected: unknown[]): Result;
+    toHaveBeenNthCalledWith(nth: number, ...expected: unknown[]): Result;
+    toHaveReturned(): Result;
+    toHaveReturnedTimes(expected: number): Result;
+    toHaveReturnedWith(expected: unknown): Result;
+    toHaveLastReturnedWith(expected: unknown): Result;
+    toHaveNthReturnedWith(nth: number, expected: unknown): Result;
+    [matcher: string]: unknown;
+}
+/** `expect(received)`, with every matcher, `.not`, `.resolves` and `.rejects`. */
+export default class Assertion {
+    #private;
+    /** Assertions made since the last reset, for `expect.assertions(n)`. */
+    static count: number;
+    constructor(received: unknown, context?: MatcherContext);
+    /** The same assertion, expecting the opposite. */
+    get not(): Assertion & Matchers;
+    /** The assertion on what a promise resolves to, its matchers return promises. */
+    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;
+}
+export {};

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

@@ -0,0 +1,49 @@
+/** A value that matches others by a rule instead of by equality, like `expect.any(Number)`. */
+export declare abstract class Asymmetric<Sample = unknown> {
+    protected readonly sample: Sample;
+    /** Set for the `expect.not` variants, which match what the rule does not. */
+    protected readonly inverse: boolean;
+    constructor(sample: Sample, inverse?: boolean);
+    asymmetricMatch(other: unknown): boolean;
+    protected abstract matches(other: unknown): boolean;
+    protected get prefix(): string;
+}
+type Constructor = abstract new (...args: never[]) => unknown;
+/** `expect.any(Type)`: values of a type, primitives by their wrapper. */
+export declare class Any extends Asymmetric<Constructor> {
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+/** `expect.anything()`: anything but null and undefined. */
+export declare class Anything extends Asymmetric<undefined> {
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+/** `expect.objectContaining(object)`: objects with at least these equal properties. */
+export declare class ObjectContaining extends Asymmetric<Record<PropertyKey, unknown>> {
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+/** `expect.arrayContaining(array)`: arrays with these items, among others. */
+export declare class ArrayContaining extends Asymmetric<unknown[]> {
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+/** `expect.stringContaining(text)`: strings with this text in them. */
+export declare class StringContaining extends Asymmetric<string> {
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+/** `expect.stringMatching(pattern)`: strings matching a regular expression. */
+export declare class StringMatching extends Asymmetric<RegExp> {
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+/** `expect.closeTo(number, digits)`: numbers equal up to some decimal digits. */
+export declare class CloseTo extends Asymmetric<number> {
+    #private;
+    constructor(sample: number, digits?: number, inverse?: boolean);
+    protected matches(other: unknown): boolean;
+    toString(): string;
+}
+export {};

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

@@ -0,0 +1,15 @@
+/** Deep equality of `toEqual` and `toStrictEqual`, and the subsets of `toMatchObject`. */
+export default class Equality {
+    #private;
+    /** Whether a value matches by its own rule, like `expect.any(Number)`. */
+    static asymmetric(value: unknown): value is {
+        asymmetricMatch(other: unknown): boolean;
+    };
+    /**
+     * Whether two values are deeply equal. Loosely, properties set to
+     * undefined count as missing; strictly, types and holes in arrays count.
+     */
+    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;
+}

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

@@ -0,0 +1,33 @@
+import Assertion, { type Matchers } from "./assertion.js";
+import { Any, Anything, ArrayContaining, CloseTo, ObjectContaining, StringContaining, StringMatching } from "./asymmetric.js";
+import type { Matcher } from "./matchers.js";
+type Constructor = abstract new (...args: never[]) => unknown;
+/** The `expect` function, its asymmetric matchers and the assertion counts of a test. */
+export default class Expect {
+    #private;
+    /** Starts the counts of a new test. */
+    reset(): void;
+    /** Failures of `expect.assertions(n)` and `expect.hasAssertions()` after a test. */
+    verify(): Error[];
+    /** The function test files call as `expect`. */
+    create(): ((received: unknown) => Assertion & Matchers) & {
+        objectContaining: (object: Record<PropertyKey, unknown>) => ObjectContaining;
+        arrayContaining: (array: unknown[]) => ArrayContaining;
+        stringContaining: (text: string) => StringContaining;
+        stringMatching: (pattern: string | RegExp) => StringMatching;
+        closeTo: (number: number, digits?: number) => CloseTo;
+        not: {
+            objectContaining: (object: Record<PropertyKey, unknown>) => ObjectContaining;
+            arrayContaining: (array: unknown[]) => ArrayContaining;
+            stringContaining: (text: string) => StringContaining;
+            stringMatching: (pattern: string | RegExp) => StringMatching;
+            closeTo: (number: number, digits?: number) => CloseTo;
+        };
+        any: (type: Constructor) => Any;
+        anything: () => Anything;
+        assertions: (count: number) => void;
+        hasAssertions: () => void;
+        extend: (added: Record<string, Matcher>) => void;
+    };
+}
+export {};

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

@@ -0,0 +1,10 @@
+/** Prints values like Jest's pretty-format, for messages and diffs. */
+export default class Format {
+    #private;
+    /** A value with one property or item per line. */
+    static value(value: unknown): string;
+    /** A value on one line. */
+    static inline(value: unknown): string;
+    /** A line diff of two values, `-` for expected lines and `+` for received ones. */
+    static diff(expected: unknown, received: unknown): string;
+}

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

@@ -0,0 +1,15 @@
+export interface MatcherResult {
+    pass: boolean;
+    /** The failure message, worded for `.not` too. */
+    message: () => string;
+}
+/** What a matcher knows besides its arguments. */
+export interface MatcherContext {
+    isNot: boolean;
+    promise: "" | "resolves" | "rejects";
+}
+export type Matcher = (this: MatcherContext, received: unknown, ...expected: any[]) => 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. */
+export declare const matchers: Record<string, Matcher>;

package/bin/types/globals.d.ts

@@ -0,0 +1,12 @@
+import type Collector from "./collector.js";
+import type Expect from "./expect/expect.js";
+import type { Settings } from "./runner.js";
+/** The functions test files use as globals, injected into them by the transformer. */
+export default class Globals {
+    static readonly key: unique symbol;
+    static readonly names: string[];
+    /** The module the transformer injects, it reads the globals of the file being run. */
+    static source(): string;
+    /** Sets the globals for the next test file to import. */
+    static install(collector: Collector, expect: Expect, settings: Settings): void;
+}

package/bin/types/mock.d.ts

@@ -0,0 +1,49 @@
+type Procedure = (...args: any[]) => any;
+export interface MockResult {
+    type: "return" | "throw" | "incomplete";
+    value: unknown;
+}
+/** What a mock function remembers of its calls, as `fn.mock`. */
+export interface MockState {
+    calls: unknown[][];
+    results: MockResult[];
+    instances: unknown[];
+    contexts: unknown[];
+    lastCall: unknown[] | undefined;
+}
+/** A function that records its calls, with Jest's `mock*` methods. */
+export interface MockFunction<T extends Procedure = Procedure> {
+    (...args: Parameters<T>): ReturnType<T>;
+    new (...args: Parameters<T>): ReturnType<T>;
+    readonly mock: MockState;
+    mockImplementation(implementation: T): this;
+    mockImplementationOnce(implementation: T): this;
+    mockReturnValue(value: ReturnType<T>): this;
+    mockReturnValueOnce(value: ReturnType<T>): this;
+    mockResolvedValue(value: Awaited<ReturnType<T>>): this;
+    mockResolvedValueOnce(value: Awaited<ReturnType<T>>): this;
+    mockRejectedValue(value: unknown): this;
+    mockRejectedValueOnce(value: unknown): this;
+    mockReturnThis(): this;
+    mockName(name: string): this;
+    getMockName(): string;
+    getMockImplementation(): T | undefined;
+    mockClear(): this;
+    mockReset(): this;
+    mockRestore(): void;
+}
+/** Creates mock functions and spies, and clears, resets or restores them all at once. */
+export default class Mocks {
+    #private;
+    /** A mock function, doing what an implementation does, if given. */
+    static fn<T extends Procedure>(implementation?: T): MockFunction<T>;
+    /** Replaces a method with a mock that calls it, until restored. */
+    static spyOn<T extends object, K extends keyof T>(object: T, method: K): MockFunction;
+    static isMockFunction(value: unknown): value is MockFunction;
+    static clearAll(): void;
+    static resetAll(): void;
+    static restoreAll(): void;
+    /** Forgets every mock, between test files. */
+    static forget(): void;
+}
+export {};

package/bin/types/reporter.d.ts

@@ -0,0 +1,27 @@
+import type { Result } from "./runner.js";
+/** The outcome of one test file. */
+export interface FileResult {
+    /** The path of the file, relative to the root. */
+    file: string;
+    results: Result[];
+    /** Errors outside tests, like a file that does not compile. */
+    errors: unknown[];
+    duration: number;
+}
+export interface ReporterOptions {
+    verbose?: boolean;
+    color?: boolean;
+    write?: (text: string) => void;
+}
+/** Writes results like Jest's default reporter. */
+export default class Reporter {
+    #private;
+    constructor(root: string, options?: ReporterOptions);
+    static failed(result: FileResult): boolean;
+    /** The results of a test file, with the failures in detail. */
+    file(result: FileResult): void;
+    /** Counts of test files and tests, and the time they took. */
+    summary(files: FileResult[], duration: number): void;
+    /** Explains that no test files were found. */
+    none(patterns: string[]): void;
+}

package/bin/types/rules.d.ts

@@ -0,0 +1,19 @@
+/** Jest like settings, set in `testero.config.ts`. */
+export interface Rules {
+    /** Globs of the test files in order, the last match decides, "!" excludes. */
+    testMatch: string[];
+    /** Milliseconds a test or a hook may take. */
+    testTimeout: number;
+    /** Stops after the first test file that fails. */
+    bail: boolean;
+    /** Lists every test, not only the files. */
+    verbose: boolean;
+    /** Succeeds when there are no test files. */
+    passWithNoTests: boolean;
+    /** Clears the calls of every mock before each test. */
+    clearMocks: boolean;
+    /** Also removes the implementations of every mock before each test. */
+    resetMocks: boolean;
+    /** Restores every spy to the original before each test. */
+    restoreMocks: boolean;
+}

package/bin/types/runner.d.ts

@@ -0,0 +1,31 @@
+import { Suite, type Test } from "./suite.js";
+export type Status = "passed" | "failed" | "skipped" | "todo";
+export interface Result {
+    test: Test;
+    status: Status;
+    /** Milliseconds the test took with its hooks. */
+    duration: number;
+    errors: unknown[];
+}
+export interface Settings {
+    /** Milliseconds a test or hook may take, unless it sets its own. */
+    timeout: number;
+    /** Runs only the tests whose full name matches. */
+    namePattern?: RegExp | undefined;
+    /** Called before each test runs, like resetting mocks. */
+    beforeTest?: (test: Test) => void;
+    /** Called after each test, returns more errors, like missed assertion counts. */
+    afterTest?: (test: Test) => unknown[];
+}
+/** Runs the tests of a suite tree in order, with their hooks and timeouts. */
+export default class Runner {
+    #private;
+    constructor(settings: Settings);
+    /** Results of every test, and errors of `afterAll` hooks that belong to no test. */
+    run(root: Suite): Promise<{
+        results: Result[];
+        errors: unknown[];
+    }>;
+    /** Whether a test runs: not skipped, focused when others are, matching the name pattern. */
+    runs(test: Test): boolean;
+}

package/bin/types/suite.d.ts

@@ -0,0 +1,41 @@
+/** How a test or suite was declared: `test`, `test.only`, `test.skip` or `test.todo`. */
+export type Mode = "run" | "only" | "skip" | "todo";
+/** A test or hook body: it may return a promise or take a `done` callback. */
+export type Body = (done: (error?: unknown) => void) => unknown;
+export type HookKind = "beforeAll" | "afterAll" | "beforeEach" | "afterEach";
+export interface Hook {
+    body: Body;
+    timeout: number | undefined;
+}
+/** A `describe` block, with its tests, nested suites and hooks in declaration order. */
+export declare class Suite {
+    readonly name: string;
+    readonly mode: Mode;
+    readonly parent: Suite | undefined;
+    readonly children: (Suite | Test)[];
+    readonly hooks: Record<HookKind, Hook[]>;
+    constructor(name: string, mode?: Mode, parent?: Suite);
+    /** The names of the suites from the file down to this one, the file has none. */
+    get titles(): string[];
+    /** This suite and the ones around it, from the file down. */
+    get path(): Suite[];
+    /** Every test, of nested suites too, in order. */
+    tests(): Generator<Test>;
+}
+/** A named test body in a suite. */
+export declare class Test {
+    readonly name: string;
+    readonly body: Body | undefined;
+    readonly mode: Mode;
+    readonly timeout: number | undefined;
+    readonly suite: Suite;
+    constructor(name: string, body: Body | undefined, mode: Mode, timeout: number | undefined, suite: Suite);
+    /** The names of the suites around the test, and its own. */
+    get titles(): string[];
+    /** The titles joined like Jest does for `-t`. */
+    get fullName(): string;
+    /** Whether the test, or a suite around it, is marked with `only`. */
+    get focused(): boolean;
+    /** Whether the test, or a suite around it, is skipped or todo. */
+    get skipped(): boolean;
+}

package/bin/types/testero.d.ts

@@ -1,4 +1,19 @@
-declare const _default: {
-    greeting: string;
-};
-export default _default;
+import type Config from "@aljazmc/config";
+import Reporter from "./reporter.js";
+import type { Rules } from "./rules.js";
+/** The rules, with what the command line adds to them. */
+export interface Options extends Rules {
+    /** Runs only test files whose path matches one of these regular expressions. */
+    patterns: string[];
+    /** Runs only tests whose full name matches. */
+    namePattern?: RegExp | undefined;
+}
+/** Finds test files, then compiles, runs and reports them one after another. */
+export default class Testero {
+    #private;
+    constructor(config: Config<Rules>, options: Options, reporter?: Reporter);
+    /** The test files to run, relative to the root. */
+    files(): string[];
+    /** Runs every test file, returns whether all of them passed. */
+    run(): Promise<boolean>;
+}

package/bin/types/transformer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ * like `describe` and `expect` are injected where the file uses them.
+ */
+export default class Transformer {
+    #private;
+    /** Packages test files import the globals from, like with Jest. */
+    static readonly modules: string[];
+    /** Where compiled test files go, stack frames there are testero's own. */
+    static readonly prefix: string;
+    constructor();
+    /** Bundles a test file, returns the URL of the module to import. */
+    compile(file: string): Promise<string>;
+    /** Removes the compiled files. */
+    dispose(): void;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aljazmc/testero",
-  "version": "0.1.6",
-  "description": "A simple test runner. Easy to understand, easy to customize and easy to extend.",
+  "version": "0.2.1",
+  "description": "A simple, Jest like test runner. Easy to understand, easy to customize and easy to extend.",
   "author": "aljazmc",
   "license": "MIT",
   "type": "module",
@@ -10,19 +10,17 @@
     "url": "https://github.com/aljazmc/aljazmc.git",
     "directory": "packages/testero"
   },
-  "devDependencies": {
-    "@types/node": "^25.6.0"
-  },
   "keywords": [
     "customizable",
+    "jest",
+    "test runner",
     "tester",
     "typescript",
     "modern",
     "modular"
   ],
-  "packageManager": "yarn@4.13.0",
   "engines": {
-    "node": "^20.19.0 || ^22.13.0 || >=24"
+    "node": "^20.19.0 || ^22.13.0 || ^24 || ^25 || ^26"
   },
   "types": "./bin/types/testero.d.ts",
   "bin": "./bin/main.js",
@@ -32,5 +30,13 @@
       "default": "./bin/main.js"
     },
     "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@aljazmc/config": "0.2.0",
+    "@jest/globals": "^30.5.2",
+    "@types/node": "^26.6.5"
+  },
+  "dependencies": {
+    "esbuild": "0.28.2"
   }
 }