@bitforgehq/ui 0.3.0

package/types/bitforgehq-ui-testing.d.ts

@@ -0,0 +1,495 @@
+import { EnvironmentProviders } from "@angular/core";
+import { provideBfDefaults, provideBfLabels } from "@bitforgehq/ui";
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate, LocatorFactory } from "@angular/cdk/testing";
+/**
+ * Options of `installBfJsdomShims()`.
+ *
+ * @summary Options of the jsdom shims: the matchMedia stub and its reduced-motion answer
+ * @since 0.3.0
+ */
+interface BfJsdomShimOptions {
+  /**
+   * Install a `matchMedia` stub where missing (all queries false).
+   * @default true
+   */
+  matchMedia?: boolean;
+  /**
+   * With the stub: report `(prefers-reduced-motion: reduce)` as matching, so overlays use their
+   * short fade. Has no effect where the environment already has `matchMedia`.
+   * @default false
+   */
+  reducedMotion?: boolean;
+}
+/**
+ * Sets `target[key]` and returns the function that puts back what was there, or `null` when the
+ * property cannot be set (then nothing changed). A new property is writable and configurable, so
+ * it can be deleted again; a configurable existing one is restored from its descriptor, getters
+ * included. An existing non-configurable one (a runner's own `matchMedia` mock, assigned
+ * `undefined` to test without it) is assigned through its setter or value and restored the same
+ * way; a non-writable one without a setter is left alone. Internal: not exported from the entry.
+ */
+declare function installGlobal(target: object, key: string, value: unknown): (() => void) | null;
+/**
+ * Installs, only where missing: `Element.prototype.animate` (an Animation whose `finished`
+ * resolves at once), `PointerEvent` (a MouseEvent subclass with pointerId, isPrimary, pointerType,
+ * width, height, pressure) and optionally `matchMedia`. Idempotent; returns a function that removes
+ * exactly what it installed. Call it once in the test runner's setup file (Vitest `setupFiles`,
+ * Jest `setupFilesAfterEnv`).
+ *
+ * @example
+ * // src/test-setup.ts
+ * import { installBfJsdomShims } from '@bitforgehq/ui/testing';
+ * installBfJsdomShims();
+ * @param options Whether to stub `matchMedia`, and whether the stub reports reduced motion.
+ * @returns A function that removes the shims this call installed.
+ * @summary Installs the browser APIs jsdom lacks and the library needs, only where missing
+ * @since 0.3.0
+ */
+export declare function installBfJsdomShims(options?: BfJsdomShimOptions): () => void;
+/**
+ * Options of `provideBfTesting()`.
+ *
+ * @summary Options of the test providers: the size defaults and labels a spec runs with
+ * @since 0.3.0
+ */
+interface BfTestingOptions {
+  /** Passed to `provideBfDefaults()`, e.g. `{ fieldSize: 'sm' }`; left out, the library defaults apply. */
+  defaults?: Parameters<typeof provideBfDefaults>[0];
+  /** Passed to `provideBfLabels()`, e.g. German validation messages; left out, the English defaults apply. */
+  labels?: Parameters<typeof provideBfLabels>[0];
+}
+/**
+ * Test providers for apps using the root and overlay entries: passes `defaults`/`labels` to 3b's
+ * providers, and on environment teardown removes what overlays and themes leave on the document —
+ * `dark` and `cdk-global-scrollblock` on `<html>`, `inert` on body children, stray
+ * `.cdk-overlay-container` children. The cleanup runs when TestBed destroys the test environment,
+ * so it needs TestBed's default `teardown: { destroyAfterEach: true }`; with `destroyAfterEach:
+ * false` nothing is cleaned between tests. Mobile shell apps use `provideBfShellTesting()` from
+ * `@bitforgehq/ui/mobile` instead.
+ *
+ * @example
+ * TestBed.configureTestingModule({
+ *   providers: [provideBfTesting({ defaults: { fieldSize: 'sm' } })],
+ * });
+ * @param options The size defaults and labels to provide.
+ * @returns The environment providers for `TestBed.configureTestingModule()`.
+ * @summary Test providers for the widgets and overlays, with document cleanup after each test
+ * @since 0.3.0
+ */
+export declare function provideBfTesting(options?: BfTestingOptions): EnvironmentProviders;
+/**
+ * Filters of every `@bitforgehq/ui/testing` harness's `with()`: the CDK's `selector` and
+ * `ancestor`, plus the widget's label (a select's label, a dialog's title, a toast's message, a
+ * menu item's text).
+ *
+ * @summary Filters a library harness query by selector, ancestor and the widget label
+ * @since 0.3.0
+ */
+interface BfHarnessFilters extends BaseHarnessFilters {
+  /** The label the harness's `getLabel()` (or equivalent) returns: exact text or a pattern. */
+  label?: string | RegExp;
+}
+/**
+ * Harness for `bf-select`. It works by option label, so a test never needs the native option
+ * values (an object option's native value is its index).
+ *
+ * @example
+ * const select = await loader.getHarness(BfSelectHarness.with({ label: 'Project' }));
+ * await select.selectOption('Two');
+ * @summary Test harness for the select: reads its label and options and picks one
+ * @since 0.3.0
+ */
+export declare class BfSelectHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly select;
+  private readonly label;
+  private readonly error;
+  private readonly help;
+  private readonly nativeOptions;
+  /**
+   * A predicate for a select with the given label.
+   * @param filters The label (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfSelectHarness>;
+  /**
+   * The visible label without the required mark, else the `aria-label`.
+   * @returns The label text.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The selected option's label, `''` while nothing is selected.
+   * @returns The label text.
+   */
+  getValueLabel(): Promise<string>;
+  /**
+   * The labels of the options, in order, without the placeholder.
+   * @returns The option labels.
+   */
+  getOptionLabels(): Promise<string[]>;
+  /**
+   * Chooses the option with this label, as a user would: the select's `value` becomes that
+   * option's value. Throws, leaving the value as it is, for an unknown or disabled option and
+   * while the select itself is disabled.
+   * @param label The option's label.
+   */
+  selectOption(label: string): Promise<void>;
+  /**
+   * Whether the select is disabled.
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * Whether the select is read-only (`aria-readonly`).
+   * @returns True when read-only.
+   */
+  isReadonly(): Promise<boolean>;
+  /**
+   * Whether the select is required.
+   * @returns True when required.
+   */
+  isRequired(): Promise<boolean>;
+  /**
+   * The error text under the select (an explicit message, or the first form error once touched).
+   * @returns The error text, `''` when there is none.
+   */
+  getErrorText(): Promise<string>;
+  /**
+   * The help text under the select; it is hidden while an error shows.
+   * @returns The help text, `''` when there is none.
+   */
+  getHelpText(): Promise<string>;
+  /** Focuses the native select. */
+  focus(): Promise<void>;
+  /** Blurs the native select, which marks a bound form field touched. */
+  blur(): Promise<void>;
+  /** Every native option; the placeholder or hidden empty option comes first, empty and disabled. */
+  private options;
+}
+/**
+ * Harness for `bf-radio-group`. It works by option label, so a test never needs the native radio
+ * values (an object option's native value is its index).
+ *
+ * @example
+ * const plan = await loader.getHarness(BfRadioGroupHarness.with({ label: 'Plan' }));
+ * await plan.select('Team');
+ * @summary Test harness for the radio group: reads its options and selects one by label
+ * @since 0.3.0
+ */
+export declare class BfRadioGroupHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly fieldset;
+  private readonly legend;
+  private readonly error;
+  private readonly radios;
+  private readonly labels;
+  /**
+   * A predicate for a radio group with the given label.
+   * @param filters The label (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfRadioGroupHarness>;
+  /**
+   * The legend, else the group's `aria-label`.
+   * @returns The label text.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The labels of the options, in order.
+   * @returns The option labels.
+   */
+  getOptionLabels(): Promise<string[]>;
+  /**
+   * The selected option's label, `null` while nothing is selected.
+   * @returns The label text or `null`.
+   */
+  getSelectedLabel(): Promise<string | null>;
+  /**
+   * Clicks the option with this label, as a user would. Throws for an unknown label, and for a
+   * disabled option or group (a user's click would do nothing).
+   * @param label The option's label.
+   */
+  select(label: string): Promise<void>;
+  /**
+   * Whether the whole group is disabled.
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * The error text under the options.
+   * @returns The error text, `''` when there is none.
+   */
+  getErrorText(): Promise<string>;
+}
+/**
+ * Harness for `bf-segmented`. It works by segment label, so a test never needs the option values.
+ *
+ * @example
+ * const range = await loader.getHarness(BfSegmentedHarness.with({ label: 'Range' }));
+ * await range.select('Week');
+ * @summary Test harness for the segmented control: reads its segments and selects one
+ * @since 0.3.0
+ */
+export declare class BfSegmentedHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly group;
+  private readonly error;
+  private readonly segments;
+  /**
+   * A predicate for a segmented control with the given label.
+   * @param filters The label (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfSegmentedHarness>;
+  /**
+   * The group's accessible name (`label`, else `ariaLabel`); it is not rendered visibly.
+   * @returns The label text.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The labels of the segments, in order.
+   * @returns The segment labels.
+   */
+  getOptionLabels(): Promise<string[]>;
+  /**
+   * The selected segment's label, `null` while nothing is selected.
+   * @returns The label text or `null`.
+   */
+  getSelectedLabel(): Promise<string | null>;
+  /**
+   * Clicks the segment with this label, as a user would. Throws for an unknown label, and for a
+   * disabled segment or control (a user's click would do nothing).
+   * @param label The segment's label.
+   */
+  select(label: string): Promise<void>;
+  /**
+   * Whether the control is disabled: every segment is.
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * The error text under the track.
+   * @returns The error text, `''` when there is none.
+   */
+  getErrorText(): Promise<string>;
+}
+/**
+ * Harness for `bf-dialog`, the card `BfDialogService` opens (a `confirm()` alert dialog is built
+ * from it too). Dialogs render in the CDK overlay container outside the tested component, so get
+ * it through `TestbedHarnessEnvironment.documentRootLoader(fixture)`.
+ *
+ * @example
+ * const dialog = await TestbedHarnessEnvironment.documentRootLoader(fixture).getHarness(
+ *   BfDialogHarness.with({ label: 'Delete project?' }),
+ * );
+ * await dialog.clickButton('Delete');
+ * @summary Test harness for a dialog: its title, text and role, its buttons and Escape
+ * @since 0.3.0
+ */
+export declare class BfDialogHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly title;
+  private readonly body;
+  private readonly closeButton;
+  private readonly buttons;
+  /**
+   * A predicate for a dialog with the given title.
+   * @param filters The title (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfDialogHarness>;
+  /**
+   * The title heading.
+   * @returns The title, `''` without one.
+   */
+  getTitle(): Promise<string>;
+  /**
+   * The text of the dialog's body (its content, without the title and footer).
+   * @returns The body text.
+   */
+  getText(): Promise<string>;
+  /**
+   * The role of the overlay panel this dialog sits in: `dialog`, or `alertdialog` for
+   * `confirm()` and `role: 'alertdialog'`. The panel is found by the dialog's own
+   * `data-bf-dialog-id`, so a dialog under another one (a confirm opened from a dialog) reads its
+   * own panel.
+   * @returns The role, `null` outside `BfDialogService` (a `bf-dialog` rendered in the page).
+   */
+  getRole(): Promise<string | null>;
+  /**
+   * Clicks the button with this text (a footer or content button). Throws for an unknown label.
+   * @param label The button's text.
+   */
+  clickButton(label: string): Promise<void>;
+  /** Clicks the close button (×), which closes the dialog with no result. Throws without one. */
+  close(): Promise<void>;
+  /** Presses `Escape` inside the dialog: it closes, or a `confirm()` resolves its cancel answer. */
+  pressEscape(): Promise<void>;
+}
+/**
+ * Harness for one row of a `bf-menu`: a `bfMenuItem`, `bfMenuItemCheckbox` or `bfMenuItemRadio`
+ * button (or `a[bfMenuItem]` link). Its `label` filter matches the row's text.
+ *
+ * @example
+ * const [first] = await menu.getItems({ label: 'Duplicate' });
+ * expect(await first.isDisabled()).toBe(false);
+ * @summary Test harness for a menu row: its text, disabled, checked and submenu state
+ * @since 0.3.0
+ */
+export declare class BfMenuItemHarness extends ComponentHarness {
+  /** The host element's selector: the menu item directives' selectors. */
+  static hostSelector: string;
+  /**
+   * A predicate for a menu item with the given text.
+   * @param filters The text (exact or a pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfMenuItemHarness>;
+  /**
+   * The row's text.
+   * @returns The text.
+   */
+  getText(): Promise<string>;
+  /**
+   * Whether the row is disabled (`aria-disabled`; a disabled row stays focusable).
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * Whether a checkbox or radio row is checked.
+   * @returns True when checked.
+   */
+  isChecked(): Promise<boolean>;
+  /**
+   * Whether the row opens a submenu.
+   * @returns True when it has a submenu.
+   */
+  hasSubmenu(): Promise<boolean>;
+  /** Clicks the row: runs its action (closing the menu), toggles it, or opens its submenu. */
+  click(): Promise<void>;
+  /**
+   * The submenu this row opened, or `null` while it is closed or when it has none.
+   * @returns The submenu's harness or `null`.
+   */
+  getSubmenu(): Promise<BfMenuHarness | null>;
+}
+/**
+ * Harness for `bf-menu`, the card a `bfMenuTriggerFor` trigger or `bf-menu-button` opens. It
+ * renders in the CDK overlay container, so get it from `BfMenuButtonHarness.getMenu()` or through
+ * `TestbedHarnessEnvironment.documentRootLoader(fixture)`. Its `label` filter matches the menu's
+ * accessible name (its `ariaLabel`, else its trigger's text).
+ *
+ * @example
+ * const menu = await (await loader.getHarness(BfMenuButtonHarness)).getMenu();
+ * await menu.clickItem('Move to', 'Archive');
+ * @summary Test harness for a menu: lists its items and clicks one, through submenus
+ * @since 0.3.0
+ */
+export declare class BfMenuHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  /**
+   * A predicate for a menu with the given accessible name.
+   * @param filters The name (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfMenuHarness>;
+  /**
+   * The menu's accessible name: its `aria-label`, else the text of the element it is labelled
+   * by (its trigger).
+   * @returns The name, `''` without one.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The menu's rows, in order (a submenu's rows belong to the submenu).
+   * @param filter Only the rows matching it, e.g. `{ label: 'Archive' }`.
+   * @returns The row harnesses.
+   */
+  getItems(filter?: BfHarnessFilters): Promise<BfMenuItemHarness[]>;
+  /**
+   * Clicks the row with this text; with a `submenuPath`, the row opens a submenu and the path's
+   * labels are clicked in the submenus that open, in order. Throws for an unknown label.
+   * @param label The row's text.
+   * @param submenuPath The labels to click in the submenus that open, in order.
+   */
+  clickItem(label: string, ...submenuPath: string[]): Promise<void>;
+}
+/** The `bf-menu` with this id in the document, or `null`. Internal. */
+declare function menuById(root: LocatorFactory, id: string): Promise<BfMenuHarness | null>;
+/**
+ * Harness for `bf-menu-button`, a button that opens a `bf-menu`. Its `label` filter matches the
+ * button's accessible name (its `label`, else its text).
+ *
+ * @example
+ * const button = await loader.getHarness(BfMenuButtonHarness.with({ label: 'Actions' }));
+ * await (await button.getMenu()).clickItem('Archive');
+ * @summary Test harness for a menu button: opens it and hands out the menu it opened
+ * @since 0.3.0
+ */
+export declare class BfMenuButtonHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly button;
+  /**
+   * A predicate for a menu button with the given accessible name.
+   * @param filters The name (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfMenuButtonHarness>;
+  /**
+   * The button's accessible name: its `aria-label` (the `label` input), else its text.
+   * @returns The name.
+   */
+  getLabel(): Promise<string>;
+  /** Opens the menu with a click; does nothing while it is open. */
+  open(): Promise<void>;
+  /**
+   * Whether the menu is open (`aria-expanded`).
+   * @returns True while open.
+   */
+  isOpen(): Promise<boolean>;
+  /**
+   * The open menu, opening it first when it is closed.
+   * @returns The menu's harness.
+   */
+  getMenu(): Promise<BfMenuHarness>;
+}
+/**
+ * Harness for `bf-desktop-toast`, the card `BfDesktopToastService.show()` renders. Toasts render
+ * in the CDK overlay container, so get it through
+ * `TestbedHarnessEnvironment.documentRootLoader(fixture)`.
+ *
+ * @example
+ * const toast = await TestbedHarnessEnvironment.documentRootLoader(fixture).getHarness(
+ *   BfDesktopToastHarness,
+ * );
+ * await toast.clickAction();
+ * @summary Test harness for a desktop toast: its message, its action and Escape
+ * @since 0.3.0
+ */
+export declare class BfDesktopToastHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly message;
+  private readonly action;
+  /**
+   * A predicate for a toast with the given message.
+   * @param filters The message (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfDesktopToastHarness>;
+  /**
+   * The toast's message.
+   * @returns The message text.
+   */
+  getMessage(): Promise<string>;
+  /** Clicks the action button, which dismisses the toast with `'action'`. Throws without one. */
+  clickAction(): Promise<void>;
+  /** Presses `Escape` inside the toast, which dismisses it with `'dismiss'`. */
+  pressEscape(): Promise<void>;
+}
+export type { BfHarnessFilters, BfJsdomShimOptions, BfTestingOptions };