playwright-json-runner/dist/index.d.mts

Extends Playwright to run tests using JSON-based test definitions.

import { L as LocatorParams, T as TestAction, a as TestRun } from './test-action-D-uP2iwB.mjs';
export { t as testRunSchema } from './test-action-D-uP2iwB.mjs';
import { Page, Locator } from 'playwright';
import 'zod';

type LocatorStrategyFn = (page: Page, params: LocatorParams) => Promise<Locator>;
type LocatorStrategies = Record<string, LocatorStrategyFn>;
declare function resolveLocator(strategies: LocatorStrategies, page: Page, params: LocatorParams): Promise<Locator>;

interface ActionContext {
    page: Page;
    locator?: Locator;
}
type ActionTypeHandler = (context: ActionContext, action: TestAction) => Promise<void>;
interface ConditionParams {
    document: Document;
    element: Element;
    xpathEval: (xpath: string) => boolean;
}
interface RuleMatch {
    id: string;
    xpath?: string;
    matchedChild: boolean;
}
interface StrategyParam {
    locator: Locator;
    ruleMatch: RuleMatch;
    value?: string;
}
type RuleType = (params: ConditionParams) => boolean;
type SetterStrategyType = (param: StrategyParam) => Promise<void>;
type GetterStrategyType = (param: StrategyParam) => Promise<string | null>;
interface Configuration<TActionType extends string = string> {
    /**
     * Absolute path to the directory containing the playwright-json config file.
     * Resolved automatically — do not set manually.
     * @internal
     */
    configDir?: string;
    /**
     * Directory where visual-regression snapshots are stored.
     * Defaults to `snapshots` (resolved relative to `configDir`).
     */
    snapshotDir: string;
    /**
     * Directory that will be recursively scanned for test files.
     * Defaults to `json-tests`.
     */
    jsonTestDir: string;
    /**
     * Glob pattern or RegExp to match test files.
     * Defaults to `**\/*.playwright.json`.
     */
    jsonTestMatch: string | RegExp;
    /**
     * Locator strategy functions keyed by the `by` discriminant value.
     * Add custom entries here to support new `by` types in your JSON tests.
     *
     * @example
     * ```ts
     * locatorStrategies: {
     *   textAfterLoad: async (page, params) => {
     *     await page.waitForLoadState("domcontentloaded");
     *     return page.getByText(params.value);
     *   }
     * }
     * // Then in JSON: { "by": "textAfterLoad", "value": "Submit" }
     * ```
     */
    locatorStrategies: LocatorStrategies;
    /**
     * Action handler functions keyed by the `action` field value.
     * Add custom entries here to support new action types in your JSON tests.
     *
     * @example
     * ```ts
     * actionTypeHandlers: {
     *   clearAndFill: async ({ locator }, action) => {
     *     if (!locator) throw new Error("clearAndFill requires a locator");
     *     await locator.clear();
     *     await locator.fill((action as any).value ?? "");
     *   }
     * }
     * // Then in JSON: { "action": "clearAndFill", "locator": {...}, "value": "hello" }
     * ```
     */
    actionTypeHandlers: Record<TActionType, ActionTypeHandler>;
    /**
     * Rules that determine which getter/setter strategy applies to a given element.
     * Each rule receives the element's HTML and returns true if its strategy should be used.
     * Order matters — the first matching rule wins.
     *
     * `xpathEval` runs an XPath query within the element's context, allowing you to
     * match on child elements (e.g. a `<select>` or `<input>` inside a wrapper `<div>`).
     */
    rules: Record<string, RuleType>;
    /**
     * Strategies for **setting** a field value. Keyed by rule name.
     * Called by `setLocatorValue` when the matching rule fires.
     */
    setterStrategies: Record<string, SetterStrategyType>;
    /**
     * Strategies for **getting** a field value. Keyed by rule name.
     * Called by `getLocatorValue` when the matching rule fires.
     */
    getterStrategies: Record<string, GetterStrategyType>;
    /**
     * Default timeout in milliseconds for `setFieldValue` / `assertFieldValue*`
     * actions to wait for the element to be attached before reading its HTML.
     * Defaults to `10_000` (10 seconds).
     */
    fieldValueTimeout: number;
}
declare const baseConfig: Configuration;
/**
 * Merge your custom config on top of the defaults.
 *
 * @example
 * ```ts
 * // playwright-json.config.ts
 * import { extendConfig } from "playwright-json-runner";
 *
 * export default extendConfig({
 *   jsonTestDir: "e2e/json-tests",
 *   actionTypeHandlers: {
 *     myCustomAction: async ({ locator }, action) => {
 *       await locator!.fill((action as any).value ?? "");
 *     }
 *   }
 * });
 * ```
 */
declare function extendConfig<TActionType extends string = string>(extensions: Partial<Configuration<TActionType>>): Configuration<TActionType>;
declare function getConfiguration(): Configuration;
declare function loadConfiguration(): Configuration;

declare function runTests(testRun: TestRun): Promise<void>;
declare function executeAction(config: Configuration, page: Page, action: TestAction): Promise<void>;

/**
 * Sets a field value using the first matching rule's setter strategy.
 */
declare function setLocatorValue(locator: Locator, value: string | undefined, options?: {
    timeout?: number;
}): Promise<void>;
/**
 * Gets a field value using the first matching rule's getter strategy.
 */
declare function getLocatorValue(locator: Locator, options?: {
    timeout?: number;
}): Promise<string | null>;

export { type ActionContext, type ActionTypeHandler, type ConditionParams, type Configuration, type GetterStrategyType, type LocatorStrategies, type LocatorStrategyFn, type RuleMatch, type RuleType, type SetterStrategyType, type StrategyParam, TestRun, baseConfig, executeAction, extendConfig, getConfiguration, getLocatorValue, loadConfiguration, resolveLocator, runTests, setLocatorValue };