matchScreenshot.ts

import type {Brand} from './brand';
import type {Url} from './http';
import type {RunLabel} from './runLabel';
import type {Selector} from './selectors';
import type {TestStaticOptions} from './testRun';
import type {TestMetaPlaceholder} from './userland';

/**
 * Dimensions of screenshot image.
 */
export type Dimensions = Readonly<{
  height: number;
  width: number;
}>;

/**
 * String with dimensions of screenshot, like `320x108`.
 */
export type DimensionsString = Brand<string, 'DimensionsString'>;

/**
 * Functions that describe the `toMatchScreenshot` assert (in `expect`).
 */
export type MatchScreenshotConfig<TestMeta = TestMetaPlaceholder> = Readonly<{
  /**
   * Get url to screenshot (for using in web-interfaces) by `screenshotId`.
   */
  getScreenshotUrlById: (this: void, screenshotId: string) => Url;

  /**
   * Reads screenshot by `screenshotId`.
   */
  readScreenshot: (
    this: void,
    screenshotId: string,
    meta: ScreenshotMeta<TestMeta>,
  ) => Promise<Uint8Array | undefined>;

  /**
   * Writes screenshot by `screenshotId` and optional context info.
   */
  writeScreenshot: (
    this: void,
    screenshot: Uint8Array,
    meta: ScreenshotMeta<TestMeta>,
  ) => Promise<string>;
}>;

/**
 * Log fields for single screenshot.
 * @internal
 */
export type ScreenshotLogFields = {
  dimensions: DimensionsString;
  readonly screenshotId: string;
  url: Url;
};

/**
 * General screenshot metadata (like test name, assert description, etc.).
 */
export type ScreenshotMeta<TestMeta = TestMetaPlaceholder> = Readonly<{
  actual: string | undefined;
  description: string;
  expected: string | undefined;
  options: ToMatchScreenshotOptions;
  pageUrl: Url;
  pathToPack: string;
  runLabel: RunLabel;
  selector: string;
  testStaticOptions: TestStaticOptions<TestMeta>;
  timeInMs: number;
}>;

/**
 * Options for `toMatchScreenshot` assert.
 */
export type ToMatchScreenshotOptions = Readonly<{
  animations?: 'allow' | 'disabled';
  caret?: 'hide' | 'initial';
  mask?: readonly Selector[];
  maskColor?: string;
  maxDiffPixelRatio?: number;
  maxDiffPixels?: number;
  omitBackground?: boolean;
  scale?: 'css' | 'device';
  threshold?: number;
  timeout?: number;
}>;