/**
 * Testing utilities for handling expected failures and errors.
 */
import { type PromiseReference, type PromiseOrValue, type ClassType, type Maybe, type ClassLikeType } from '@dereekb/util';
import { BaseError } from 'make-error';
import { type TestDoneCallback } from './shared';
/**
 * Error thrown by fail() and used by expectError()
 */
export declare class ExpectedFailError extends BaseError {
}
/**
 * Creates an {@link ExpectedFailError} without throwing it, for use in deferred error handling.
 *
 * @param message - optional error message
 * @returns a new {@link ExpectedFailError} instance
 */
export declare function failSuccessfullyError(message?: string): ExpectedFailError;
/**
 * Throws an {@link ExpectedFailError} to signal that a test reached the expected failure point.
 *
 * Used within {@link shouldFail} or {@link expectSuccessfulFail} to indicate that the expected
 * error path was taken successfully.
 *
 * @param message - optional error message
 */
export declare function failSuccessfully(message?: string): never;
/**
 * Error thrown when success occurs when it should not have.
 */
export declare class UnexpectedSuccessFailureError extends BaseError {
}
/**
 * Creates an {@link UnexpectedSuccessFailureError} without throwing it.
 *
 * @param message - optional error message; defaults to a standard "expected an error" message
 * @returns a new {@link UnexpectedSuccessFailureError} instance
 */
export declare function failDueToSuccessError(message?: string): UnexpectedSuccessFailureError;
/**
 * Error thrown when the error type was different than the expected type.
 */
export declare class ExpectedErrorOfSpecificTypeError extends BaseError {
    readonly encounteredType: unknown;
    readonly expectedType?: Maybe<ClassLikeType | string>;
    constructor(encounteredType: unknown, expectedType?: Maybe<ClassLikeType | string>);
}
/**
 * Fails the current test by throwing an {@link UnexpectedSuccessFailureError}.
 * Use when a code path should not have been reached.
 *
 * @param message - optional error message
 */
export declare function failTest(message?: string): never;
/**
 * Throws an {@link UnexpectedSuccessFailureError} with a default message.
 * Typically called when an operation succeeds but was expected to throw.
 */
export declare function failDueToSuccess(): never;
/**
 * Default error handler for {@link expectSuccessfulFail} that passes through {@link ExpectedFailError}
 * instances and re-throws all other errors.
 *
 * @param e - the caught error to evaluate
 */
export declare function EXPECT_ERROR_DEFAULT_HANDLER(e: unknown): void;
/**
 * Used to assert additional information about the expected error.
 *
 * Can assert within this function, or return a boolean. A boolean returning false means the test should throw an ExpectedErrorOfSpecificTypeError.
 */
export type ExpectFailAssertionFunction = (error: unknown) => PromiseOrValue<Maybe<boolean> | void>;
/**
 * Creates an ExpectFailAssertionFunction that asserts the encountered error is of the expected type using the instanceof keyword.
 *
 * Throws an ExpectedErrorOfSpecificTypeError on failures.
 *
 * @param expectedType - the class or constructor function that the error should be an instance of
 * @returns an assertion function that validates the error type via instanceof
 */
export declare function expectFailAssertErrorType(expectedType: ClassType | ClassLikeType | typeof Error | any): ExpectFailAssertionFunction;
/**
 * Function that expects any failure to be thrown, then throws an ExpectedFailError.
 *
 * @param errorFn - function expected to throw an error (sync or async)
 * @param assertFailType - optional assertion to validate the type or content of the thrown error
 * @returns a promise that resolves when the expected failure is verified
 */
export declare function expectFail(errorFn: () => PromiseOrValue<any>, assertFailType?: ExpectFailAssertionFunction): Promise<void>;
/**
 * Function that expects an ExpectedFailError to be thrown.
 *
 * @param errorFn - function expected to throw (sync or async); if it succeeds, the test fails
 * @param handleError - optional custom error handler; defaults to {@link EXPECT_ERROR_DEFAULT_HANDLER}
 */
export declare function expectSuccessfulFail(errorFn: () => void, handleError?: (e: unknown) => void): void;
export declare function expectSuccessfulFail(errorFn: () => Promise<void>, handleError?: (e: unknown) => void): Promise<void>;
/**
 * Extended done callback for {@link shouldFail} tests that adds a {@link failSuccessfully} convenience method.
 */
export interface ShouldFailDoneCallback extends TestDoneCallback {
    failSuccessfully(): void;
}
/**
 * A test function for {@link shouldFail} that receives a {@link ShouldFailDoneCallback} to signal failure outcomes.
 */
export type ShouldFailProvidesCallbackWithDone = (cb: ShouldFailDoneCallback) => void | undefined;
/**
 * A test function for {@link shouldFail} that returns its result directly (sync or async), without using a done callback.
 */
export type ShouldFailProvidesCallbackWithResult = () => PromiseOrValue<unknown>;
/**
 * Union type for test functions accepted by {@link shouldFail}. Supports both done-callback and promise-based patterns.
 */
export type ShouldFailProvidesCallback = ShouldFailProvidesCallbackWithDone | ShouldFailProvidesCallbackWithResult;
/**
 * Used to wrap a testing function and watch for ExpectedFailError errors in order to pass the test. Other exceptions are treated normally as failures.
 *
 * This is typically used in conjunction with failSuccessfully(), expectSuccessfulFail(), or expectFail().
 *
 * @param fn - the test function that is expected to throw an {@link ExpectedFailError}
 * @returns an async test function suitable for use with `it()`
 */
export declare function shouldFail(fn: ShouldFailProvidesCallback): () => Promise<unknown>;
/**
 * Convenience wrapper that registers an `it()` test case which is expected to fail.
 *
 * Automatically generates a "should fail" description and wraps the test function with {@link shouldFail}.
 *
 * @param describeOrFn - either a description suffix (e.g., "when input is null") or the test function directly
 * @param fn - the test function, if a description string was provided as the first argument
 */
export declare function itShouldFail(fn: ShouldFailProvidesCallback): void;
export declare function itShouldFail(describe: string, fn: ShouldFailProvidesCallback): void;
/**
 * A simulated done callback that bridges callback-based test patterns to promises.
 *
 * Calling the handler or its `fail` method resolves or rejects the underlying promise,
 * allowing callback-style tests to be awaited.
 */
export interface FakeDoneHandler extends TestDoneCallback, PromiseReference {
    _ref: PromiseReference;
}
/**
 * Creates a {@link FakeDoneHandler} that converts done-callback invocations into promise resolution/rejection.
 *
 * Calling the returned function with no arguments resolves the promise;
 * calling it with an error (or calling `.fail()`) rejects the promise.
 *
 * @returns a new {@link FakeDoneHandler} backed by a promise reference
 */
export declare function fakeDoneHandler(): FakeDoneHandler;