tstyche/build/tstyche.d.ts

The Essential Type Testing Tool.

import type ts from 'typescript';

declare enum DiagnosticCategory {
    Error = "error",
    Warning = "warning"
}

interface DiagnosticOrigin {
    breadcrumbs?: Array<string>;
    end: number;
    file: ts.SourceFile;
    start: number;
}
declare class Diagnostic {
    #private;
    text: string | Array<string>;
    category: DiagnosticCategory;
    origin?: DiagnosticOrigin | undefined;
    code?: string;
    related?: Array<Diagnostic>;
    constructor(text: string | Array<string>, category: DiagnosticCategory, origin?: DiagnosticOrigin | undefined);
    add(options: {
        code?: string;
        origin?: DiagnosticOrigin;
        related?: Array<Diagnostic>;
    }): this;
    static error(text: string | Array<string>, origin?: DiagnosticOrigin): Diagnostic;
    static fromDiagnostics(diagnostics: ReadonlyArray<ts.Diagnostic>, compiler: typeof ts): Array<Diagnostic>;
    static fromError(text: string | Array<string>, error: unknown): Diagnostic;
    static isTsDiagnosticWithLocation(diagnostic: ts.Diagnostic): diagnostic is ts.DiagnosticWithLocation;
    static warning(text: string | Array<string>, origin?: DiagnosticOrigin): Diagnostic;
}

declare class StoreService {
    #private;
    constructor();
    getSupportedTags(signal?: AbortSignal): Promise<Array<string>>;
    install(tag: string, signal?: AbortSignal): Promise<string | undefined>;
    load(tag: string, signal?: AbortSignal): Promise<typeof ts | undefined>;
    open(signal?: AbortSignal): Promise<void>;
    prune: () => Promise<void>;
    resolveTag(tag: string, signal?: AbortSignal): Promise<string | undefined>;
    update(signal?: AbortSignal): Promise<void>;
    validateTag(tag: string, signal?: AbortSignal): Promise<boolean>;
}

declare enum OptionBrand {
    String = "string",
    Number = "number",
    Boolean = "boolean",
    True = "true",// an option which does not take a value
    List = "list"
}

declare enum OptionGroup {
    CommandLine = 2,
    ConfigFile = 4
}

interface ItemDefinition {
    brand: OptionBrand.String;
    name: string;
    pattern?: string;
}
type OptionDefinition = PrimitiveTypeOptionDefinition | ListTypeOptionDefinition;
interface BaseOptionDefinition {
    brand: OptionBrand;
    description: string;
    group: OptionGroup;
    name: string;
}
interface PrimitiveTypeOptionDefinition extends BaseOptionDefinition {
    brand: OptionBrand.String | OptionBrand.Number | OptionBrand.Boolean | OptionBrand.True;
}
interface ListTypeOptionDefinition extends BaseOptionDefinition {
    brand: OptionBrand.List;
    items: ItemDefinition;
}
declare class OptionDefinitionsMap {
    #private;
    static for(optionGroup: OptionGroup): Map<string, OptionDefinition>;
}

/**
 * Options passed through the command line.
 */
interface CommandLineOptions {
    /**
     * The path to a TSTyche configuration file.
     */
    config?: string;
    /**
     * Stop running tests after the first failed assertion.
     */
    failFast?: boolean;
    /**
     * Print the list of command line options with brief descriptions and exit.
     */
    help?: boolean;
    /**
     * Install specified versions of the 'typescript' package and exit.
     */
    install?: boolean;
    /**
     * Print the list of the selected test files and exit.
     */
    listFiles?: boolean;
    /**
     * Only run tests with matching name.
     */
    only?: string;
    /**
     * Remove all installed versions of the 'typescript' package and exit.
     */
    prune?: boolean;
    /**
     * Print the resolved configuration and exit.
     */
    showConfig?: boolean;
    /**
     * Skip tests with matching name.
     */
    skip?: string;
    /**
     * The list of TypeScript versions to be tested on.
     */
    target?: Array<string>;
    /**
     * Fetch the 'typescript' package metadata from the registry and exit.
     */
    update?: boolean;
    /**
     * Print the version number and exit.
     */
    version?: boolean;
}

/**
 * Options loaded from the configuration file.
 */
interface ConfigFileOptions {
    /**
     * Stop running tests after the first failed assertion.
     */
    failFast?: boolean;
    /**
     * The path to a directory containing files of a test project.
     */
    rootPath?: string;
    /**
     * The list of TypeScript versions to be tested on.
     */
    target?: Array<string>;
    /**
     * The list of glob patterns matching the test files.
     */
    testFileMatch?: Array<string>;
}

interface ResolvedConfig extends Omit<CommandLineOptions, keyof ConfigFileOptions>, Required<ConfigFileOptions> {
    /**
     * Only run test files with matching path.
     */
    pathMatch: Array<string>;
}
declare class ConfigService {
    #private;
    compiler: typeof ts;
    constructor(compiler: typeof ts, storeService: StoreService);
    get commandLineOptions(): CommandLineOptions;
    get configFileOptions(): ConfigFileOptions;
    static get defaultOptions(): Required<ConfigFileOptions>;
    parseCommandLine(commandLineArgs: Array<string>): Promise<void>;
    readConfigFile(): Promise<void>;
    resolveConfig(): ResolvedConfig;
    selectTestFiles(): Array<string>;
}

declare class TSTyche {
    #private;
    readonly resolvedConfig: ResolvedConfig;
    static readonly version = "1.0.0-rc.2";
    constructor(resolvedConfig: ResolvedConfig, storeService: StoreService);
    run(testFiles: Array<string | URL>): Promise<void>;
}

declare class Cli {
    #private;
    constructor();
    run(commandLineArguments: Array<string>): Promise<void>;
}

declare enum TestMemberBrand {
    Describe = "describe",
    Test = "test",
    Expect = "expect"
}

declare enum TestMemberFlags {
    None = 0,
    Fail = 1,
    Only = 2,
    Skip = 4,
    Todo = 8
}

declare class TestTree {
    compiler: typeof ts;
    diagnostics: Set<ts.Diagnostic>;
    sourceFile: ts.SourceFile;
    members: Array<TestMember | Assertion>;
    constructor(compiler: typeof ts, diagnostics: Set<ts.Diagnostic>, sourceFile: ts.SourceFile);
    get hasOnly(): boolean;
}

declare class TestMember {
    brand: TestMemberBrand;
    node: ts.CallExpression;
    parent: TestTree | TestMember;
    flags: TestMemberFlags;
    compiler: typeof ts;
    diagnostics: Set<ts.Diagnostic>;
    members: Array<TestMember | Assertion>;
    name: string;
    constructor(brand: TestMemberBrand, node: ts.CallExpression, parent: TestTree | TestMember, flags: TestMemberFlags);
    get ancestorNames(): Array<string>;
    validate(): Array<Diagnostic>;
}

interface MatcherNode extends ts.CallExpression {
    expression: ts.PropertyAccessExpression;
}
declare class Assertion extends TestMember {
    matcherNode: MatcherNode;
    modifierNode: ts.PropertyAccessExpression;
    notNode: ts.PropertyAccessExpression | undefined;
    isNot: boolean;
    constructor(brand: TestMemberBrand, node: ts.CallExpression, parent: TestTree | TestMember, flags: TestMemberFlags, matcherNode: MatcherNode, modifierNode: ts.PropertyAccessExpression, notNode: ts.PropertyAccessExpression | undefined);
    get ancestorNames(): Array<string>;
    get matcherName(): ts.MemberName;
    get source(): ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode>;
    get target(): ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode>;
}

declare class CollectService {
    #private;
    compiler: typeof ts;
    readonly matcherIdentifiers: string[];
    readonly modifierIdentifiers: string[];
    readonly notIdentifier = "not";
    constructor(compiler: typeof ts);
    createTestTree(sourceFile: ts.SourceFile, semanticDiagnostics?: Array<ts.Diagnostic>): TestTree;
}

declare class Environment {
    #private;
    /**
     * Specifies whether color should be disabled in the output.
     */
    static get noColor(): boolean;
    /**
     * Specifies whether interactive elements should be disabled in the output.
     */
    static get noInteractive(): boolean;
    /**
     * The directory where to store the 'typescript' packages.
     */
    static get storePath(): string;
    /**
     * The number of seconds to wait before giving up stale operations.
     */
    static get timeout(): number;
    /**
     * The path to the currently installed TypeScript module.
     */
    static get typescriptPath(): string | undefined;
}

declare class ResultTiming {
    end: number;
    start: number;
    get duration(): number;
}

type FileResultStatus = ResultStatus.Runs | ResultStatus.Passed | ResultStatus.Failed;
declare enum ResultStatus {
    Runs = "runs",
    Passed = "passed",
    Failed = "failed",
    Skipped = "skipped",
    Todo = "todo"
}

declare class ExpectResult {
    assertion: Assertion;
    parent: TestResult | undefined;
    diagnostics: Array<Diagnostic>;
    status: ResultStatus;
    timing: ResultTiming;
    constructor(assertion: Assertion, parent: TestResult | undefined);
}

declare class ResultCount {
    failed: number;
    passed: number;
    skipped: number;
    todo: number;
    get total(): number;
}

declare class TestResult {
    test: TestMember;
    parent: DescribeResult | undefined;
    diagnostics: Array<Diagnostic>;
    expectCount: ResultCount;
    results: Array<ExpectResult>;
    status: ResultStatus;
    timing: ResultTiming;
    constructor(test: TestMember, parent: DescribeResult | undefined);
}

declare class DescribeResult {
    describe: TestMember;
    parent: DescribeResult | undefined;
    results: Array<DescribeResult | TestResult>;
    timing: ResultTiming;
    constructor(describe: TestMember, parent: DescribeResult | undefined);
}

declare class FileResult {
    testFile: URL;
    diagnostics: Array<Diagnostic>;
    expectCount: ResultCount;
    results: Array<DescribeResult | TestResult | ExpectResult>;
    status: FileResultStatus;
    testCount: ResultCount;
    timing: ResultTiming;
    constructor(testFile: URL);
}

declare class ProjectResult {
    compilerVersion: string;
    projectConfigFilePath: string | undefined;
    diagnostics: Array<Diagnostic>;
    results: Array<FileResult>;
    constructor(compilerVersion: string, projectConfigFilePath: string | undefined);
}

declare class TargetResult {
    versionTag: string;
    testFiles: Array<URL>;
    results: Map<string | undefined, ProjectResult>;
    status: ResultStatus.Runs | ResultStatus.Passed | ResultStatus.Failed;
    timing: ResultTiming;
    constructor(versionTag: string, testFiles: Array<URL>);
}

declare class Result {
    resolvedConfig: ResolvedConfig;
    testFiles: Array<URL>;
    expectCount: ResultCount;
    fileCount: ResultCount;
    results: Array<TargetResult>;
    targetCount: ResultCount;
    testCount: ResultCount;
    timing: ResultTiming;
    constructor(resolvedConfig: ResolvedConfig, testFiles: Array<URL>);
}

declare class ResultManager {
    #private;
    handleEvent([eventName, payload]: Event): void;
}

type Event = ["start", {
    result: Result;
}] | ["end", {
    result: Result;
}] | ["config:error", {
    diagnostics: Array<Diagnostic>;
}] | ["store:info", {
    compilerVersion: string;
    installationPath: string;
}] | ["store:error", {
    diagnostics: Array<Diagnostic>;
}] | ["target:start", {
    result: TargetResult;
}] | ["target:end", {
    result: TargetResult;
}] | ["project:info", {
    compilerVersion: string;
    projectConfigFilePath: string | undefined;
}] | ["project:error", {
    diagnostics: Array<Diagnostic>;
}] | ["file:start", {
    result: FileResult;
}] | ["file:error", {
    diagnostics: Array<Diagnostic>;
    result: FileResult;
}] | ["file:end", {
    result: FileResult;
}] | ["describe:start", {
    result: DescribeResult;
}] | ["describe:end", {
    result: DescribeResult;
}] | ["test:start", {
    result: TestResult;
}] | ["test:error", {
    diagnostics: Array<Diagnostic>;
    result: TestResult;
}] | ["test:fail", {
    result: TestResult;
}] | ["test:pass", {
    result: TestResult;
}] | ["test:skip", {
    result: TestResult;
}] | ["test:todo", {
    result: TestResult;
}] | ["expect:start", {
    result: ExpectResult;
}] | ["expect:error", {
    diagnostics: Array<Diagnostic>;
    result: ExpectResult;
}] | ["expect:fail", {
    diagnostics: Array<Diagnostic>;
    result: ExpectResult;
}] | ["expect:pass", {
    result: ExpectResult;
}] | ["expect:skip", {
    result: ExpectResult;
}];
type EventHandler = (event: Event) => void;
declare class EventEmitter {
    #private;
    static addHandler(handler: EventHandler): void;
    static dispatch(event: Event): void;
    static removeHandler(handler: EventHandler): void;
}

interface MatchResult {
    explain: () => Array<Diagnostic>;
    isMatch: boolean;
}
type Relation = Map<string, unknown>;
interface TypeChecker extends ts.TypeChecker {
    isTypeRelatedTo: (source: ts.Type, target: ts.Type, relation: Relation) => boolean;
    relation: {
        assignable: Relation;
        identity: Relation;
        subtype: Relation;
    };
}

declare class PrimitiveTypeMatcher {
    #private;
    typeChecker: TypeChecker;
    constructor(typeChecker: TypeChecker, targetTypeFlag: ts.TypeFlags, targetTypeText: string);
    match(sourceType: ts.Type, isNot: boolean): MatchResult;
}

declare class ToBeAssignable {
    #private;
    typeChecker: TypeChecker;
    constructor(typeChecker: TypeChecker);
    match(sourceType: ts.Type, targetType: ts.Type, isNot: boolean): MatchResult;
}

declare class ToEqual {
    #private;
    typeChecker: TypeChecker;
    constructor(typeChecker: TypeChecker);
    match(sourceType: ts.Type, targetType: ts.Type, isNot: boolean): MatchResult;
}

declare class ToHaveProperty {
    #private;
    compiler: typeof ts;
    typeChecker: TypeChecker;
    constructor(compiler: typeof ts, typeChecker: TypeChecker);
    match(sourceType: ts.Type, targetType: ts.StringLiteralType | ts.NumberLiteralType | ts.UniqueESSymbolType, isNot: boolean): MatchResult;
}

declare class ToMatch {
    #private;
    typeChecker: TypeChecker;
    constructor(typeChecker: TypeChecker);
    match(sourceType: ts.Type, targetType: ts.Type, isNot: boolean): MatchResult;
}

declare class ToRaiseError {
    #private;
    compiler: typeof ts;
    typeChecker: TypeChecker;
    constructor(compiler: typeof ts, typeChecker: TypeChecker);
    match(source: {
        diagnostics: Array<ts.Diagnostic>;
        node: ts.Expression | ts.TypeNode;
    }, targetTypes: Array<ts.StringLiteralType | ts.NumberLiteralType>, isNot: boolean): MatchResult;
}

declare class Expect {
    #private;
    compiler: typeof ts;
    typeChecker: TypeChecker;
    toBeAny: PrimitiveTypeMatcher;
    toBeAssignable: ToBeAssignable;
    toBeBigInt: PrimitiveTypeMatcher;
    toBeBoolean: PrimitiveTypeMatcher;
    toBeNever: PrimitiveTypeMatcher;
    toBeNull: PrimitiveTypeMatcher;
    toBeNumber: PrimitiveTypeMatcher;
    toBeString: PrimitiveTypeMatcher;
    toBeSymbol: PrimitiveTypeMatcher;
    toBeUndefined: PrimitiveTypeMatcher;
    toBeUniqueSymbol: PrimitiveTypeMatcher;
    toBeUnknown: PrimitiveTypeMatcher;
    toBeVoid: PrimitiveTypeMatcher;
    toEqual: ToEqual;
    toHaveProperty: ToHaveProperty;
    toMatch: ToMatch;
    toRaiseError: ToRaiseError;
    constructor(compiler: typeof ts, typeChecker: TypeChecker);
    static assertTypeChecker(typeChecker: ts.TypeChecker): typeChecker is TypeChecker;
    match(assertion: Assertion, expectResult: ExpectResult): MatchResult | undefined;
}

/**
 * A stream to output messages.
 */
interface WriteStream {
    /**
     * @param log - Message to write to the stream.
     */
    write: (log: string) => void;
}
/**
 * Options to configure an instance of the {@link Logger}.
 */
interface LoggerOptions {
    /**
     * Specifies whether color should be disabled in the output. Default: `Environment.noColor`.
     */
    noColor?: boolean;
    /**
     * A stream to write warnings and errors. Default: `process.stderr`.
     */
    stderr?: WriteStream;
    /**
     * A stream to write informational messages. Default: `process.stdout`.
     */
    stdout?: WriteStream;
}
/**
 * Wraps the provided streams with a set of convenience methods.
 */
declare class Logger {
    #private;
    /**
     * @param options - {@link LoggerOptions | Options} to configure an instance of the Logger.
     */
    constructor(options?: LoggerOptions);
    /**
     * Moves the cursor one line up in the `stdout` stream and erases that line.
     */
    eraseLastLine(): void;
    writeError(body: JSX.Element | Array<JSX.Element>): void;
    writeMessage(body: JSX.Element | Array<JSX.Element>): void;
    writeWarning(body: JSX.Element | Array<JSX.Element>): void;
}

declare function addsPackageStepText(compilerVersion: string, installationPath: string): JSX.Element;

declare function describeNameText(name: string, indent?: number): JSX.Element;

declare function diagnosticText(diagnostic: Diagnostic): JSX.Element;

declare function fileStatusText(status: FileResultStatus, testFile: URL): JSX.Element;

declare function fileViewText(lines: Array<JSX.Element>, addEmptyFinalLine: boolean): JSX.Element;

declare function formattedText(input: string | Array<string> | Record<string, unknown>): JSX.Element;

declare function helpText(optionDefinitions: Map<string, OptionDefinition>, tstycheVersion: string): JSX.Element;

declare function summaryText({ duration, expectCount, fileCount, onlyMatch, pathMatch, skipMatch, targetCount, testCount, }: {
    duration: number;
    expectCount: ResultCount;
    fileCount: ResultCount;
    onlyMatch: string | undefined;
    pathMatch: Array<string>;
    skipMatch: string | undefined;
    targetCount: ResultCount;
    testCount: ResultCount;
}): JSX.Element;

declare function testNameText(status: "fail" | "pass" | "skip" | "todo", name: string, indent?: number): JSX.Element;

declare function usesCompilerStepText(compilerVersion: string, tsconfigFilePath: string | undefined, options?: {
    prependEmptyLine: boolean;
}): JSX.Element;

declare class Path {
    static dirname(filePath: string): string;
    static join(...filePaths: Array<string>): string;
    static normalizeSlashes(filePath: string): string;
    static relative(from: string, to: string): string;
    static resolve(...filePaths: Array<string>): string;
}

declare class ProjectService {
    #private;
    compiler: typeof ts;
    constructor(compiler: typeof ts);
    closeFile(filePath: string): void;
    getDefaultProject(filePath: string): ts.server.Project | undefined;
    getLanguageService(filePath: string): ts.LanguageService | undefined;
    openFile(filePath: string, sourceText?: string | undefined, projectRootPath?: string | undefined): void;
}

declare abstract class Reporter {
    readonly resolvedConfig: ResolvedConfig;
    protected logger: Logger;
    constructor(resolvedConfig: ResolvedConfig);
    abstract handleEvent([eventName, payload]: Event): void;
}

declare class SummaryReporter extends Reporter {
    handleEvent([eventName, payload]: Event): void;
}

declare class ThoroughReporter extends Reporter {
    #private;
    handleEvent([eventName, payload]: Event): void;
}

declare class TaskRunner {
    #private;
    readonly resolvedConfig: ResolvedConfig;
    constructor(resolvedConfig: ResolvedConfig, storeService: StoreService);
    run(testFiles: Array<URL>, target: Array<string>, signal?: AbortSignal): Promise<Result>;
}

declare enum Color {
    Reset = "0",
    Red = "31",
    Green = "32",
    Yellow = "33",
    Blue = "34",
    Magenta = "35",
    Cyan = "36",
    Gray = "90"
}

interface LineProps {
    children?: JSX.ElementChildrenAttribute["children"];
    color?: Color;
    indent?: number;
}
declare class Line implements JSX.ElementClass {
    readonly props: LineProps;
    constructor(props: LineProps);
    render(): JSX.Element;
}

type ElementChildren = Array<ElementChildren> | JSX.Element | string | undefined;
type ComponentConstructor = new (props: Record<string, unknown>) => JSX.ElementClass;
declare global {
    namespace JSX {
        interface Element {
            $$typeof: symbol;
            children: ElementChildren;
            props: Record<string, unknown> | null;
            type: ComponentConstructor | string;
        }
        interface ElementAttributesProperty {
            props: Record<string, unknown> | null;
        }
        interface ElementClass {
            render: () => JSX.Element | null;
        }
        interface ElementChildrenAttribute {
            children: ElementChildren;
        }
        interface IntrinsicElements {
            ansi: {
                children?: never;
                escapes: Color | Array<Color>;
            };
            newLine: {
                children?: never;
            };
            text: {
                children: ElementChildren;
                indent?: number | undefined;
            };
        }
    }
}
/**
 * Options to configure an instance of the {@link Scribbler}.
 */
interface ScribblerOptions {
    /**
     * The end of line sequence to be used in the output. Default: `"\n"`.
     */
    newLine?: string;
    /**
     * Do not include ANSI color escape codes in the output. Default: `false`.
     */
    noColor?: boolean;
}
/**
 * Provides the JSX factory function and renderer.
 */
declare class Scribbler {
    #private;
    /**
     * @param options - {@link ScribblerOptions | Options} to configure an instance of the Scribbler.
     */
    constructor(options?: ScribblerOptions);
    /**
     * Creates a new text element of the given `type`.
     */
    static createElement(type: ComponentConstructor | string, props: Record<string, unknown> | null, ...children: Array<ElementChildren>): JSX.Element;
    /**
     * Renders the provided JSX `element` and returns the resulting string.
     */
    render(element: JSX.Element | null): string;
}

interface TextProps {
    children?: JSX.ElementChildrenAttribute["children"];
    color?: Color | undefined;
    indent?: number | undefined;
}
declare class Text implements JSX.ElementClass {
    readonly props: TextProps;
    constructor(props: TextProps);
    render(): JSX.Element;
}

declare class Version {
    #private;
    static isGreaterThan(source: string, target: string): boolean;
    static isSatisfiedWith(source: string, target: string): boolean;
    static isVersionTag(target: string): boolean;
}

export { Assertion, Cli, CollectService, Color, type CommandLineOptions, type ConfigFileOptions, ConfigService, DescribeResult, Diagnostic, DiagnosticCategory, type DiagnosticOrigin, Environment, type Event, EventEmitter, type EventHandler, Expect, ExpectResult, FileResult, type FileResultStatus, type ItemDefinition, Line, Logger, type LoggerOptions, type MatchResult, OptionBrand, type OptionDefinition, OptionDefinitionsMap, OptionGroup, Path, ProjectResult, ProjectService, Reporter, type ResolvedConfig, Result, ResultCount, ResultManager, ResultStatus, ResultTiming, Scribbler, type ScribblerOptions, StoreService, SummaryReporter, TSTyche, TargetResult, TaskRunner, TestMember, TestMemberBrand, TestMemberFlags, TestResult, TestTree, Text, ThoroughReporter, type TypeChecker, Version, type WriteStream, addsPackageStepText, describeNameText, diagnosticText, fileStatusText, fileViewText, formattedText, helpText, summaryText, testNameText, usesCompilerStepText };