@progress/kendo-e2e/dist/rendering/html-comparer.d.ts

Kendo UI end-to-end test utilities.

import { type A11yResult } from "./a11y-comparer";
import { type IdRefResult } from "./a11y-id-validator";
import type { A11yAllowEntry } from "./a11y-comparer";
export type CompereOptions = {
    allowMissing?: string[];
    allowExtra?: string[];
    sanitizeNGSelectors?: boolean;
    /** When true, also compare aria-* and role attributes between actual and expected HTML. Disabled by default. */
    compareA11yAttributes?: boolean;
    /**
     * A11y attributes to ignore when missing from actual, scoped per node.
     * Each entry maps a CSS class selector to attribute names.
     * @example [{ ".k-slider": ["aria-label"] }, { ".k-radio": ["role"] }]
     */
    allowMissingA11yAttributes?: A11yAllowEntry[];
    /**
     * A11y attributes to ignore when extra in actual, scoped per node.
     * Same matching semantics as `allowMissingA11yAttributes`.
     * @example [{ ".k-button": ["aria-expanded"] }]
     */
    allowExtraA11yAttributes?: A11yAllowEntry[];
    /**
     * Attributes to compare by presence only (ignore exact value).
     * Defaults to: `["aria-label", "title", "aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"]`.
     * Set to `[]` to disable and compare all values exactly.
     */
    ignoreValueAttributes?: string[];
    /**
     * When true, validates that ID-referencing attributes (`aria-controls`, `aria-labelledby`,
     * `aria-owns`, `aria-describedby`) in the **actual** HTML point to elements that exist in the DOM.
     * Enabled by default when `compareA11yAttributes` is true.
     * Set to `false` to disable.
     */
    validateIdReferences?: boolean;
    /**
     * When true, classless nodes (e.g. `<svg>`, `<path>`) are excluded from
     * the a11y comparison entirely. Defaults to `false`.
     */
    ignoreClasslessNodes?: boolean;
    /**
     * CSS class selectors to collapse in the **actual** a11y tree.
     * Nodes whose classes are entirely covered by these entries are treated as
     * transparent wrappers: their children are promoted and their a11y
     * attributes are carried down.
     *
     * By default, inherits from `allowExtra`. Set to `[]` to disable
     * collapsing without affecting the CSS allow list.
     *
     * @example ['.k-icon-wrapper-host', '.k-button-text']
     */
    collapseExtraClasses?: string[];
    /**
     * CSS class selectors to collapse in the **expected** a11y tree.
     * Nodes whose classes are entirely covered by these entries are collapsed.
     *
     * By default, inherits from `allowMissing`. Set to `[]` to disable
     * collapsing without affecting the CSS allow list.
     *
     * @example ['.k-button-text']
     */
    collapseMissingClasses?: string[];
    /**
     * When provided, automatically generates an HTML diff report after comparison.
     * `actualHtml` and `expectedHtml` are wired automatically from the comparison inputs.
     * @example
     * compareHtml(actual, expected, {
     *   report: { specFilePath: __filename, specFileName: 'toolbar', testName: 'Toolbar normal' }
     * });
     */
    report?: Omit<HtmlReportOptions, 'actualHtml' | 'expectedHtml'>;
};
export type NodeDiff = {
    /** Depth level in the tree */
    depth: number;
    /** Classes matched in both actual and expected */
    matchedClasses: string[];
    /** Classes in actual but not expected */
    extraClasses: string[];
    /** Classes in expected but not actual */
    missingClasses: string[];
    /** Node comparison status */
    status: 'matched' | 'missing' | 'extra' | 'different';
    /** CSS class selector for this node (e.g. ".k-button.k-button-md") */
    classSelector: string;
    /** Child node diffs */
    children: NodeDiff[];
};
export type Result = {
    passed: string[];
    missing: string[];
    extra: string[];
    actualSelectors: string[];
    expectedSelectors: string[];
    /** Tree-based diff showing per-node class differences */
    treeDiff?: NodeDiff[];
    /** Suggested leaf selectors to add to allowMissing */
    suggestedAllowMissing?: string[];
    /** Suggested leaf selectors to add to allowExtra */
    suggestedAllowExtra?: string[];
    /** A11y attribute comparison result (only populated when compareA11yAttributes is enabled) */
    a11yResult?: A11yResult;
    /** ID reference validation result (populated when compareA11yAttributes is enabled) */
    idRefResult?: IdRefResult;
    /** Absolute path to the HTML report file, when the `report` option was provided */
    reportPath?: string;
};
/**
 * Check if two html documents have same class hierarchy.
 *
 * @example
 * await compareHtml("<div class="set">SET</div>", "<div class="qa">QA</div>");
 *
 * @param actualHtml An html object.
 * @param expectedHtml An html object.
 */
export declare function compareHtml(actualHtml: string, expectedHtml: string, options?: CompereOptions): Result;
/**
 * Get partial html of bigger html block.
 *
 * @example
 * await getPartialHtml("<div><ul class="k-list"><ul></div>", ".k-list");
 *
 * @param originalHtml An html object.
 * @param selector Css selector.
 */
export declare function getPartialHtml(originalHtml: string, selector: string): string;
/**
 * Remove angular specific selectors.
 *
 * @example
 * await sanitize(".k-scrollview.ng-tns-c43-0 .k-scrollview-wrap.ng-tns-c43-0.ng-trigger.ng-trigger-animateTo");
 *
 * @param selector Css selector as string.
 */
export declare function sanitizeNGSelectors(selector: string): string;
/**
 * Format a comparison result for display.
 *
 * - `format: 'llm'` (default) — structured plain text optimised for LLM / AI consumption.
 *   No ANSI codes; uses `KEY: value` and `[STATUS] selector` notation.
 * - `format: 'human'` — coloured, human-readable diff with Unicode box-drawing.
 *
 * @example
 * // LLM format (default)
 * console.log(formatDiff(result));
 * // Human-readable with colours
 * console.log(formatDiff(result, { format: 'human', useColors: true }));
 *
 * @param result The comparison result from compareHtml.
 * @param options Formatting options.
 */
export declare function formatDiff(result: Result, options?: {
    useColors?: boolean;
    format?: 'human' | 'llm';
}): string;
export type HtmlReportOptions = {
    /** Directory to write reports to. Defaults to a `rendering-reports` folder next to `specFilePath`. */
    outputDir?: string;
    /**
     * Absolute path to the spec file. Used to determine the default `outputDir`
     * (a `rendering-reports` subfolder next to the spec file) when `outputDir` is not provided.
     */
    specFilePath?: string;
    /** The spec file name (without extension). Used as prefix in the filename. */
    specFileName: string;
    /** The test name. Used as part of the filename. */
    testName: string;
    /** The raw actual HTML markup (before sanitization) for visualization */
    actualHtml?: string;
    /** The raw expected HTML markup (before sanitization) for visualization */
    expectedHtml?: string;
    /** CSS class allow-missing entries (e.g. [".k-button"]) — used to dim allowed diffs in visualizations */
    allowMissing?: string[];
    /** CSS class allow-extra entries (e.g. [".k-ripple"]) — used to dim allowed diffs in visualizations */
    allowExtra?: string[];
    /** When true, classless nodes were excluded from a11y comparison */
    ignoreClasslessNodes?: boolean;
};
/**
 * Generate an HTML report file visualizing the comparison result.
 *
 * The file is named: `{specFileName}_{testName}_{MM-DD-HH-mm-ss}.html`
 *
 * By default the report is written to a `rendering-reports` subfolder next to the spec file
 * (when `specFilePath` is provided). You can override this via `outputDir`.
 *
 * @param result The comparison result from compareHtml.
 * @param options Report options including file naming and optional raw HTML.
 * @returns The absolute path of the generated report file.
 */
export declare function generateHtmlReport(result: Result, options: HtmlReportOptions): string;