Custom Playwright Matchers: Extend and Merge expect Safely

A custom matcher earns its place when it turns a repeated domain rule into a precise sentence and a better failure. await expect(orderRow).toHaveOrderStatus('shipped') can carry retry behavior, a consistent timeout option, and diagnostics about the actual status. A wrapper that merely hides three unrelated assertions offers less value and can make the suite harder to inspect.

The engineering challenge is not calling expect.extend. It is preserving Playwright's assertion semantics as matcher libraries grow: live locator retries, .not, soft assertions, timeout forwarding, TypeScript visibility, and one unambiguous expect import for every test.

Define a Domain Invariant, Not a Workflow

Matchers should answer a focused question about a received value or locator. Good candidates include an order row having a status, a money component displaying a normalized amount, or an API result satisfying a contract. The matcher name should read naturally after expect(received) and remain meaningful outside one page object.

Do not turn an entire checkout flow into toCompleteCheckout(). That method would mix actions, data creation, navigation, and several possible failures under an assertion-shaped name. Keep workflows explicit and reserve matchers for observable invariants.

The official Playwright assertions documentation shows custom matchers returning a pass flag and a message callback. For locator matchers, its example delegates to a built-in locator assertion, which is the key to preserving retries and rich mismatch details.

Write acceptance examples for the matcher before implementing it: immediate pass, eventual pass, timeout, and negated pass/failure. These examples define behavior more clearly than the implementation signature alone.

Preserve Locator Retry Behavior

A naive matcher reads an attribute once and performs a synchronous comparison. That introduces a race whenever the UI updates asynchronously. Delegate to Playwright's locator assertion so the matcher uses the normal retry loop.

// assertions/order-expect.ts
import {
  expect as baseExpect,
  type Locator,
} from '@playwright/test'

type OrderStatus = 'pending' | 'paid' | 'shipped' | 'cancelled'

export const orderExpect = baseExpect.extend({
  async toHaveOrderStatus(
    locator: Locator,
    expected: OrderStatus,
    options?: { timeout?: number },
  ) {
    const assertionName = 'toHaveOrderStatus'
    let pass = false
    let matcherResult: { actual?: unknown; message?: string } | undefined

    try {
      const assertion = this.isNot
        ? baseExpect(locator).not
        : baseExpect(locator)
      await assertion.toHaveAttribute('data-order-status', expected, options)
      pass = true
    } catch (error) {
      matcherResult = (error as { matcherResult?: typeof matcherResult }).matcherResult
    }

    if (this.isNot) pass = !pass

    return {
      name: assertionName,
      pass,
      expected,
      actual: matcherResult?.actual,
      message: () =>
        this.utils.matcherHint(assertionName, undefined, undefined, {
          isNot: this.isNot,
        }) +
        '\n\n' +
        `Locator: ${locator}\n` +
        `Expected status: ${this.utils.printExpected(expected)}\n` +
        `Received status: ${this.utils.printReceived(matcherResult?.actual)}`,
    }
  },
})

The matcher forwards the timeout and captures the underlying assertion result. The handling of this.isNot may look unusual because Playwright applies negation to the custom result after the matcher returns; follow the supported pattern and prove it with tests instead of simplifying it by intuition.

Choose the strongest built-in assertion that represents the invariant. A status exposed as accessible text may use toHaveText; an explicit machine-readable state may use toHaveAttribute. Do not duplicate Playwright's polling with a manual loop inside every matcher.

Design Useful Matcher Options

Keep the option surface narrow. A timeout is common for locator matchers. Domain-specific normalization can be reasonable, such as a currency code or tolerance, but accepting arbitrary callbacks turns the matcher into a hidden mini-framework.

Defaults should match product semantics. A money matcher might compare parsed minor units instead of formatted text so locale does not make a numeric rule ambiguous. If visible formatting is the requirement, test text separately. One matcher should not silently claim both presentation and numeric correctness.

Custom messages supplied at the call site still have value:

await orderExpect(
  orderRow,
  `order ${orderId} should be shipped after fulfillment webhook`,
).toHaveOrderStatus('shipped', { timeout: 10_000 })

The call-site message provides scenario context; the matcher output provides expected and actual state. Together they should explain the failure without a source-code search.

Test the Matcher as Production Code

Assertion utilities can create false passes, so unit-style fixture pages are worth the small investment. Cover positive, negative, eventual, and failure-message behavior. Deliberately make the DOM update after a short delay to prove the matcher retries rather than sampling once.

import { test } from '@playwright/test'
import { orderExpect } from '../assertions/order-expect'

test('toHaveOrderStatus retries a live locator', async ({ page }) => {
  await page.setContent('<div id="order" data-order-status="pending"></div>')
  await page.evaluate(() => {
    setTimeout(() => {
      document.querySelector('#order')?.setAttribute('data-order-status', 'shipped')
    }, 100)
  })

  await orderExpect(page.locator('#order')).toHaveOrderStatus('shipped')
})

test('toHaveOrderStatus supports negation', async ({ page }) => {
  await page.setContent('<div id="order" data-order-status="cancelled"></div>')
  await orderExpect(page.locator('#order')).not.toHaveOrderStatus('shipped')
})

Also run a deliberately failing case and inspect its reporter output during review. A matcher can be logically correct yet operationally poor if it prints undefined, omits the locator, or swallows the underlying mismatch.

Merge Assertion Modules Deliberately

Large suites often separate accessibility, API, database, and domain assertions. mergeExpects combines extended Playwright expect objects into one assertion surface.

// test-support/expect.ts
import { mergeExpects } from '@playwright/test'
import { accessibilityExpect } from '../assertions/accessibility-expect'
import { orderExpect } from '../assertions/order-expect'

export const expect = mergeExpects(accessibilityExpect, orderExpect)

Tests should import this canonical export, not sometimes use @playwright/test and sometimes use a domain module. Mixed imports make matcher availability depend on the file and can cause reviewers to miss that an assertion is using the wrong implementation.

Give matcher names domain ownership, and reject collisions in review. Two modules that both export toBeValid may mean entirely different things. Prefer names such as toHaveValidInvoiceTotals and toHaveNoCriticalA11yViolations, even if they are longer. Precision at the call site is the point.

Keep Types and Runtime Exports Together

Runtime extension and TypeScript knowledge must travel together. Export the matcher implementation and its associated type augmentation from the same package or test-support boundary. Consumers should not need a separate undocumented type import just to make the editor recognize a matcher that exists at runtime.

Compile a small representative spec in CI. This catches three common problems: the type declaration is not included by tsconfig, the test imports base expect, or a package emits types without the runtime extension. Type success alone does not prove the matcher was merged; runtime tests remain necessary.

Avoid importing Jest's standalone expect library into Playwright tests. It is not fully integrated with the Playwright runner. Standardize lint rules or import conventions so custom matchers extend and merge the runner's own expect.

Keep Value and Locator Matchers Distinct

A matcher receiving a plain API object has no live source to re-query. It should compare the supplied value synchronously and tell the caller to perform polling outside when eventual consistency is expected. Pretending such a matcher auto-retries usually means it captured an API client or hid network calls, which makes its cost and side effects surprising.

Locator matchers can delegate to retrying DOM assertions because the locator resolves current state on every attempt. Value matchers should instead normalize one snapshot and produce a precise diff. For an eventual API contract, combine a focused value matcher with expect.poll, returning only the normalized object that matters. This separation keeps the matcher deterministic and lets the test own timeout and interval policy.

Be equally careful with response bodies. A matcher named toHaveValidInvoice may validate schema and totals, but it should not fetch missing line items behind the scenes. Pass the complete received object or expose an explicit API helper so the trace and network cost remain visible.

Analyze Matcher Failures and Tradeoffs

Custom matchers improve readability and consistency, but they add an API the team must maintain. Too many tiny matchers make search and onboarding difficult; too few giant matchers hide useful steps.

The best abstraction threshold is repeated meaning, not repeated syntax. Three lines that jointly express one stable invariant may deserve a matcher. One line repeated in many files may already be clear enough as a built-in assertion.

Operational Checklist for Custom expect

• Name one observable domain invariant per matcher.
• Delegate locator waiting to a built-in Playwright assertion.
• Forward timeout options and preserve focused matcher details.
• Test immediate, eventual, negative, and failing behavior.
• Inspect reporter output, not only pass/fail status.
• Merge modules through one canonical expect export.
• Prevent matcher-name collisions across ownership domains.
• Ship runtime code and TypeScript declarations together.
• Keep actions and multi-step workflows outside matcher bodies.

Action Plan

Inventory repeated assertion blocks and choose one whose business meaning is stable. Implement a matcher that delegates to the closest built-in assertion, add explicit negation and eventual-state tests, and review its forced-failure output. Export it through the suite's single expect module and update only a few representative specs first. If those tests become clearer while traces retain useful detail, expand adoption; if the matcher hides where a workflow failed, reduce its responsibility before it spreads.