Implementation:Microsoft Playwright ExpectUtils

Overview

ExpectUtils provides utility functions for Playwright's expect assertion system, including text value serialization and diff formatting helpers adapted from Jest.

Description

This module offers:

• serializeExpectedTextValues -- converts arrays of strings and RegExps into the ExpectedTextValue protocol format with options for substring matching, case sensitivity, and whitespace normalization
• Diff formatting helpers (adapted from Jest's expect package) -- functions for highlighting differences in expected vs received strings with color coding
• InternalMatcherUtils interface -- defines the utility methods available to custom matchers for formatting output

The module bridges the gap between user-facing assertion syntax and the internal protocol representation used for server-side evaluation.

Usage

Used by Playwright's expect matchers to serialize expected values and format error messages.

Code Reference

Source Location

packages/playwright-core/src/server/utils/expectUtils.ts (178 lines)

Function Signatures

export interface InternalMatcherUtils {
  printDiffOrStringify(expected: unknown, received: unknown, ...): string;
  printExpected(value: unknown): string;
  printReceived(object: unknown): string;
  DIM_COLOR(text: string): string;
  RECEIVED_COLOR(text: string): string;
  INVERTED_COLOR(text: string): string;
  EXPECTED_COLOR(text: string): string;
}

export function serializeExpectedTextValues(
  items: (string | RegExp)[],
  options?: { matchSubstring?: boolean; normalizeWhiteSpace?: boolean; ignoreCase?: boolean }
): ExpectedTextValue[];

export const printReceivedStringContainExpectedSubstring: (utils: InternalMatcherUtils, received: string, start: number, length: number) => string;
export const printReceivedStringContainExpectedResult: (utils: InternalMatcherUtils, received: string, result: RegExpMatchArray | null) => string;

Import

import { serializeExpectedTextValues, printReceivedStringContainExpectedSubstring } from './server/utils/expectUtils';
import type { InternalMatcherUtils } from './server/utils/expectUtils';

I/O Contract

Inputs

• Arrays of strings/RegExps for serialization
• Received and expected values for diff formatting

Outputs

• ExpectedTextValue[] protocol objects
• Formatted diff strings with color highlighting

Related Pages

• Microsoft_Playwright_Comparators -- Visual comparison used by expect
• Microsoft_Playwright_StringUtils -- String utility functions