import { type ChildProcess } from "node:child_process";
export { outputResults, loadEnvs, log, logLevelEnabled, timestamp, getOrInitRunTimestamp, getRunOutputDir, runArchivesArtifacts, replaceEnvs, spawnCommand, spawnBackgroundCommand, spawnPtyBackgroundCommand, resolveShellName, resolveShellExecutable, shellSpawnEnv, waitForReady, waitForPort, waitForHttp, waitForStdio, waitForOutputMatch, inContainer, cleanTemp, calculateFractionalDifference, serializeBrowserResult, matchesExpectedOutput, fetchFile, isRelativeUrl, appendQueryParams, isDeviceWebContext, computeSettleCeiling, redactUrlForOutput, assertUrlHostIsPublic, sanitizeFilesystemName, compileFilter, isRetryableSessionError, isSessionAlive, isPageBroken, isPageUnnavigated, isInitialBlankDocument, classifyContextRetry, isTransientProcessInitError, matchesFilter, selectSpecsForRun, shouldFailRun, findFreePort, runConcurrent, createResourceRegistry, runResourceAware, rollUpResults, rollUpAssertions, createAppiumPool, evaluateContextRequirements, };
export type { BackgroundProcess, ResourceRegistry };
declare function createAppiumPool(ports: number[]): {
    acquire(): Promise<number>;
    release(port: number): void;
};
declare function runConcurrent<T>(items: T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
type ResourceRegistry = {
    tryAcquire(names: string[]): boolean;
    release(names: string[]): void;
    waitForFree(): Promise<void>;
};
declare function createResourceRegistry(): ResourceRegistry;
declare function runResourceAware<T>(items: T[], limit: number, registry: ResourceRegistry, fn: (item: T) => Promise<void>, resourcesOf?: (item: T) => string[]): Promise<void>;
declare function rollUpResults(children: Array<{
    result?: string;
}>): string;
declare function rollUpAssertions(assertions?: Array<{
    result?: string;
}> | null): string;
declare function findFreePort(): Promise<number>;
interface BackgroundProcess {
    child?: ChildProcess;
    pid: number | undefined;
    getStdout(): string;
    getStderr(): string;
    getCombined(): string;
    write(data: string): boolean;
    onChunk(cb: (chunk: string, stream: "stdout" | "stderr") => void): () => void;
    exited: Promise<number | null>;
    kill?(): Promise<void> | void;
    isPty?: boolean;
}
declare function spawnBackgroundCommand(cmd: string, args?: string[], options?: any): BackgroundProcess;
declare function spawnPtyBackgroundCommand(cmd: string, args?: string[], options?: any): Promise<BackgroundProcess>;
declare function waitForPort(port: number, { deadline }: {
    deadline: number;
}): Promise<void>;
declare function waitForHttp(url: string, { deadline }: {
    deadline: number;
}): Promise<void>;
declare function waitForStdio(bg: BackgroundProcess, expected: string, { deadline }: {
    deadline: number;
}): Promise<void>;
declare function waitForOutputMatch(bg: BackgroundProcess, expected: string, { deadline }: {
    deadline: number;
}): Promise<boolean>;
declare function waitForReady(bg: BackgroundProcess, waitUntil: any, { timeoutMs }: {
    timeoutMs: number;
}): Promise<void>;
declare function isRetryableSessionError(message: string | undefined, startupCeiling?: number | undefined): boolean;
declare function isSessionAlive(driver: any, probeTimeoutMs?: number): Promise<boolean>;
declare function isPageBroken(driver: any): Promise<boolean>;
declare function isPageUnnavigated(driver: any): Promise<boolean>;
declare function isInitialBlankDocument(url: unknown): boolean;
export type ContextRetryReason = "session-died" | "page-broken" | "unnavigated";
declare function classifyContextRetry(probeDrivers: any[]): Promise<ContextRetryReason | null>;
declare function isTransientProcessInitError(message: string | undefined, platform?: string): boolean;
declare function compileFilter(patterns?: string[] | unknown): RegExp[];
declare function matchesFilter(id: string | undefined, filters: RegExp[]): boolean;
declare function selectSpecsForRun(specs: any[], config: any): any[];
declare function shouldFailRun(results: any): boolean;
declare function isRelativeUrl(url: string): boolean;
declare function isDeviceWebContext(driver: any): boolean;
/**
 * @internal Implementation detail of goTo's device-web settle, exported only so
 * the unit tests can exercise it. Not a public API; do not rely on it externally.
 */
declare function computeSettleCeiling(waitTimeout: number, elapsedMs: number): number;
declare function appendQueryParams(url: string, params: Record<string, unknown> | undefined | null): string;
declare function cleanTemp(): void;
declare function sanitizeFilesystemName(name: string, fallback: string): string;
declare function redactUrlForOutput(value: string): string;
declare function assertUrlHostIsPublic(fileURL: string): Promise<void>;
declare function fetchFile(fileURL: string, opts?: {
    binary?: boolean;
}): Promise<{
    result: string;
    path: string;
    message?: undefined;
} | {
    path?: undefined;
    result: string;
    message: unknown;
}>;
declare function outputResults(path: string, results: any, config: any): Promise<void>;
/**
 * Loads environment variables from a specified .env file.
 *
 * @async
 * @param {string} envsFile - Path to the environment variables file.
 * @returns {Promise<Object>} An object containing the operation result.
 * @returns {string} returns.status - "PASS" if environment variables were loaded successfully, "FAIL" otherwise.
 * @returns {string} returns.description - A description of the operation result.
 */
declare function loadEnvs(envsFile: string): Promise<{
    status: string;
    description: string;
}>;
declare function logLevelEnabled(config: any, level: string): boolean;
/**
 * Benign viewport delta (px) that must not raise a mismatch warning. A vertical
 * scrollbar appearing/disappearing after a resize shifts the content width by
 * ~15px on desktop; this absorbs that so only a meaningful floor (e.g. a mobile
 * width clamped up by a hundred-plus pixels) is flagged.
 */
export declare const VIEWPORT_TOLERANCE_PX = 16;
/**
 * Compare a requested browser viewport against the viewport the page actually
 * rendered (window.innerWidth/innerHeight read back after a resize) and produce
 * a warning when they diverge.
 *
 * Browsers and the host OS enforce a minimum window size, so a requested
 * viewport — a 375px mobile width, say — can be silently floored to a larger
 * size with no error and no failing step (the "the browser had a floor I didn't
 * know about" case). This surfaces that gap so the rendered size is honest
 * rather than assumed.
 *
 * Only dimensions the caller actually requested (a positive number) are
 * compared, so a width-only request is never warned about an unrequested
 * height. A requested dimension that couldn't be read back (non-finite actual)
 * is treated as a mismatch — an unconfirmed size is not a matched size.
 * `tolerance` (px) absorbs benign deltas such as a scrollbar's width. Returns
 * null when every requested dimension landed within tolerance.
 */
export declare function viewportMismatchWarning(requested: {
    width?: number;
    height?: number;
} | undefined, actual: {
    width?: number;
    height?: number;
} | undefined, tolerance?: number): string | null;
/**
 * True when the browser FLOORED a requested viewport — the realized size came
 * back LARGER than requested by more than `tolerance`, i.e. the window refused
 * to shrink past its minimum. A smaller-than-requested render is not a floor.
 *
 * Distinct from `viewportMismatchWarning`, which flags any divergence (either
 * direction, plus unreadable dimensions). This is the narrower "the user asked
 * for a phone-sized viewport and couldn't get it" signal.
 */
export declare function isViewportFloored(requested: {
    width?: number;
    height?: number;
} | undefined, actual: {
    width?: number;
    height?: number;
} | undefined, tolerance?: number): boolean;
/**
 * Resolve the concrete target the viewport should be set to. A request may name
 * only one dimension (width OR height); the other is filled from the current
 * viewport so the unrequested dimension is left as-is. Non-positive/absent
 * values fall back to the current size.
 */
export declare function resolveViewportTarget(requested: {
    width?: number;
    height?: number;
} | undefined, current: {
    width?: number;
    height?: number;
} | undefined): {
    width: number;
    height: number;
};
/**
 * Realize a requested browser viewport by resizing the OS window, then read the
 * viewport back and return the size the page actually rendered.
 *
 * The window is grown/shrunk by the delta between the requested and current
 * viewport. This is subject to the browser/OS minimum *window* size, so a small
 * mobile width (375px) can be floored to a larger size; the realized size is
 * read back and a warning is emitted when the request wasn't met, since the size
 * the page rendered — not the size requested — is ground truth.
 *
 * True viewport *emulation* (`driver.setViewport`, setting the content size
 * below the window floor) was evaluated and rejected: it needs a WebDriver BiDi
 * socket, which crashed headed recording contexts with a stack overflow and
 * flaked geckodriver startup — the cross-driver instability ADR 00132 documented.
 * See [ADR 01072] (rejected). This resize-and-warn path is the shipped behavior.
 *
 * Only meaningful when at least one dimension was requested; callers guard that.
 */
export declare function realizeViewport(driver: any, requested: {
    width?: number;
    height?: number;
}, config?: any, label?: string): Promise<{
    width: number;
    height: number;
}>;
declare function log(config: any, level: string, message?: any): Promise<void>;
type RequirementDeps = {
    env?: Record<string, string | undefined>;
    existsSync?: (candidate: string) => boolean;
    commandExists?: (command: string) => boolean;
    platform?: NodeJS.Platform;
};
declare function evaluateContextRequirements({ requires, deps, }: {
    requires: any;
    deps?: RequirementDeps;
}): {
    met: boolean;
    missing: string[];
};
declare function replaceEnvs(stringOrObject: any): any;
declare function timestamp(): string;
declare function getOrInitRunTimestamp(config: any): string;
declare function getRunOutputDir(config: any, { create }?: {
    create?: boolean;
}): string;
declare function runArchivesArtifacts(config?: any, specs?: any[]): boolean;
type ShellName = "bash" | "cmd" | "powershell";
declare function resolveShellName({ config, step, }?: {
    config?: any;
    step?: any;
}): ShellName;
interface ResolveShellDeps {
    platform?: string;
    env?: Record<string, string | undefined>;
    cacheDir?: string;
    resolveWindowsBash?: (options?: {
        cacheDir?: string;
    }) => Promise<string>;
    probePosixBash?: () => Promise<boolean>;
}
declare function resolveShellExecutable(shellName: string, deps?: ResolveShellDeps): Promise<string>;
declare function shellSpawnEnv(shellExecutable: string | undefined, deps?: {
    platform?: string;
    env?: Record<string, string | undefined>;
}): Record<string, string | undefined> | undefined;
/**
 * Executes a command in a child process using the `spawn` function from the `child_process` module.
 * @param {string} cmd - The command to execute.
 * @param {string[]} args - The arguments to pass to the command.
 * @param {object} options - The options for the command execution.
 * @param {boolean} options.workingDirectory - Directory in which to execute the command.
 * @param {boolean} options.debug - Whether to enable debug mode.
 * @returns {Promise<object>} A promise that resolves to an object containing the stdout, stderr, and exit code of the command.
 */
declare function spawnCommand(cmd: string, args?: string[], options?: any): Promise<{
    stdout: string;
    stderr: string;
    exitCode: unknown;
}>;
declare function inContainer(): Promise<boolean>;
/**
 * Calculates the fractional difference between two strings using Levenshtein distance.
 * @param {string} text1 - First string to compare
 * @param {string} text2 - Second string to compare
 * @returns {number} Fractional difference between 0 and 1, where 0 means identical
 *                   and 1 means completely different. Compare against maxVariation
 *                   thresholds directly (e.g., 0.1 for 10% tolerance).
 */
declare function calculateFractionalDifference(text1: string, text2: string): number;
/**
 * Serialize the value returned by a browser script into a string for assertion
 * and snapshotting. Strings pass through unchanged; other primitives and `null`
 * go through `String(value)` (preserving `NaN`/`Infinity`/`BigInt`, which JSON
 * would coerce or throw on); objects and arrays are JSON-serialized, falling
 * back to `String(value)` for circular or otherwise unserializable structures
 * so the result is always a usable string.
 *
 * @param {unknown} value - The raw return value from `driver.execute`.
 * @returns {string} A string representation suitable for substring/regex
 *                   matching and writing to a snapshot file.
 */
declare function serializeBrowserResult(value: unknown): string;
/**
 * Test whether a serialized value contains the expected output. Mirrors the
 * `runShell`/`runCode` `stdio` matching contract: when `expected` starts and
 * ends with `/`, the inner text is treated as a regular expression; otherwise
 * it's a plain substring match.
 *
 * @param {string} serialized - The serialized script result.
 * @param {string} expected - Expected content; a `/pattern/` regex or a literal substring.
 * @returns {boolean} `true` when the expected content is found.
 */
declare function matchesExpectedOutput(serialized: string, expected: string): boolean;
//# sourceMappingURL=utils.d.ts.map