Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(expect): include aria snapshot in expect failure messages (#40390)

Pavel Feldmand8378c36529b
diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.ts
index 0890cf167e..5d8290e5bc 100644
--- a/packages/injected/src/injectedScript.ts
+++ b/packages/injected/src/injectedScript.ts
@@ -54,6 +54,7 @@ export type FrameExpectParams = Omit<channels.FrameExpectParams, 'expectedValue'
export type ElementState = 'visible' | 'hidden' | 'enabled' | 'disabled' | 'editable' | 'checked' | 'unchecked' | 'indeterminate' | 'stable';
export type ElementStateWithoutStable = Exclude<ElementState, 'stable'>;
export type ElementStateQueryResult = { matches: boolean, received?: string | 'error:notconnected', isRadio?: boolean };
+export type ExpectReceived = { value?: any, ariaSnapshot?: string };
export type HitTargetInterceptionResult = {
stop: () => 'done' | { hitTargetDescription: string };
@@ -1441,7 +1442,39 @@ export class InjectedScript {
this.onGlobalListenersRemoved.add(addHitTargetInterceptorListeners);
}
- async expect(element: Element | undefined, options: FrameExpectParams, elements: Element[]): Promise<{ matches: boolean, received?: any, missingReceived?: boolean }> {
+ async expect(element: Element | undefined, options: FrameExpectParams, elements: Element[]): Promise<{ matches: boolean, received?: ExpectReceived, missingReceived?: boolean }> {
+ const core = await this._expectCore(element, options, elements);
+ const ariaSnapshot = this._ariaSnapshotForExpect(element, options);
+ if (core.received === undefined && ariaSnapshot === undefined)
+ return { matches: core.matches, missingReceived: core.missingReceived };
+ return { matches: core.matches, received: { value: core.received, ariaSnapshot }, missingReceived: core.missingReceived };
+ }
+
+ private _ariaSnapshotForExpect(element: Element | undefined, options: FrameExpectParams): string | undefined {
+ const expression = options.expression;
+ if (expression === 'to.have.count' || expression.endsWith('.array'))
+ return undefined;
+ if (expression === 'to.match.aria')
+ return undefined;
+ if (element && isElementVisible(element)) {
+ // Element-scoped snapshot. Containment matchers want the full subtree;
+ // property matchers only need the element's own line.
+ const isContainment = expression === 'to.have.text';
+ return this._renderAriaSnapshot(element, { mode: 'default', depth: isContainment ? undefined : 1 });
+ }
+ // Element missing or hidden — fall back to a full-page snapshot for context.
+ if (!this.document.body)
+ return undefined;
+ return this._renderAriaSnapshot(this.document.body, { mode: 'default' });
+ }
+
+ private _renderAriaSnapshot(element: Element, options: AriaTreeOptions): string {
+ // Bypass _lastAriaSnapshotForQuery — that cache is reserved for explicit
+ // ariaSnapshot() calls used by the aria-ref selector engine.
+ return renderAriaTree(generateAriaTree(element, options), options).text;
+ }
+
+ private async _expectCore(element: Element | undefined, options: FrameExpectParams, elements: Element[]): Promise<{ matches: boolean, received?: any, missingReceived?: boolean }> {
const isArray = options.expression === 'to.have.count' || options.expression.endsWith('.array');
if (isArray)
return this.expectArray(elements, options);
diff --git a/packages/playwright-core/src/client/frame.ts b/packages/playwright-core/src/client/frame.ts
index b4d6bd3c36..73aeab57a0 100644
--- a/packages/playwright-core/src/client/frame.ts
+++ b/packages/playwright-core/src/client/frame.ts
@@ -487,16 +487,29 @@ export class Frame extends ChannelOwner<channels.FrameChannel> implements api.Fr
return (await this._channel.title()).value;
}
- async _expect(expression: string, options: Omit<channels.FrameExpectParams, 'expression'>): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {
+ async _expect(expression: string, options: Omit<channels.FrameExpectParams, 'expression'>): Promise<ExpectResult> {
const params: channels.FrameExpectParams = { expression, ...options, isNot: !!options.isNot };
params.expectedValue = serializeArgument(options.expectedValue);
- const result = (await this._channel.expect(params));
- if (result.received !== undefined)
- result.received = parseResult(result.received);
+ const channelResult = await this._channel.expect(params);
+ const result: ExpectResult = {
+ matches: channelResult.matches,
+ log: channelResult.log,
+ timedOut: channelResult.timedOut,
+ errorMessage: channelResult.errorMessage,
+ };
+ if (channelResult.received !== undefined) {
+ result.received = {
+ value: channelResult.received.value !== undefined ? parseResult(channelResult.received.value) : undefined,
+ ariaSnapshot: channelResult.received.ariaSnapshot,
+ };
+ }
return result;
}
}
+export type ExpectReceived = { value?: any, ariaSnapshot?: string };
+export type ExpectResult = { matches: boolean, received?: ExpectReceived, log?: string[], timedOut?: boolean, errorMessage?: string };
+
export function verifyLoadState(name: string, waitUntil: LifecycleEvent): LifecycleEvent {
if (waitUntil as unknown === 'networkidle0')
waitUntil = 'networkidle';
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index 8dda1580c1..071e6a4efa 100644
--- a/packages/playwright-core/src/client/locator.ts
+++ b/packages/playwright-core/src/client/locator.ts
@@ -22,7 +22,7 @@ import { monotonicTime } from '@isomorphic/time';
import { ElementHandle } from './elementHandle';
import { DisposableStub } from './disposable';
-import type { Frame } from './frame';
+import type { ExpectResult, Frame } from './frame';
import type { DropPayload, FilePayload, FrameExpectParams, Rect, SelectOption, SelectOptionOptions, TimeoutOptions } from './types';
import type * as structs from '../../types/structs';
import type * as api from '../../types/types';
@@ -396,7 +396,7 @@ export class Locator implements api.Locator {
}
- async _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {
+ async _expect(expression: string, options: FrameExpectParams): Promise<ExpectResult> {
return this._frame._expect(expression, {
...options,
selector: this._selector,
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index d9eaec067b..7826167045 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -2040,7 +2040,10 @@ scheme.FrameExpectParams = tObject({
});
scheme.FrameExpectResult = tObject({
matches: tBoolean,
- received: tOptional(tType('SerializedValue')),
+ received: tOptional(tObject({
+ value: tOptional(tType('SerializedValue')),
+ ariaSnapshot: tOptional(tString),
+ })),
timedOut: tOptional(tBoolean),
errorMessage: tOptional(tString),
log: tOptional(tArray(tString)),
diff --git a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
index b20a19587a..cc7605bd39 100644
--- a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
@@ -282,8 +282,18 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Br
if (params.expression === 'to.match.aria' && expectedValue)
expectedValue = parseAriaSnapshotUnsafe(yaml, expectedValue);
const result = await this._frame.expect(progress, params.selector, { ...params, expectedValue, timeoutForLogs: params.timeout });
- if (result.received !== undefined)
- result.received = serializeResult(result.received);
- return result;
+ const channelResult: channels.FrameExpectResult = {
+ matches: result.matches,
+ log: result.log,
+ timedOut: result.timedOut,
+ errorMessage: result.errorMessage,
+ };
+ if (result.received !== undefined) {
+ channelResult.received = {
+ value: result.received.value !== undefined ? serializeResult(result.received.value) : undefined,
+ ariaSnapshot: result.received.ariaSnapshot,
+ };
+ }
+ return channelResult;
}
}
diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.ts
index a298a0df92..39a6a7d774 100644
--- a/packages/playwright-core/src/server/frames.ts
+++ b/packages/playwright-core/src/server/frames.ts
@@ -95,7 +95,8 @@ export class NavigationAbortedError extends Error {
}
}
-export type ExpectResult = { matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string };
+export type ExpectReceived = { value?: any, ariaSnapshot?: string };
+export type ExpectResult = { matches: boolean, received?: ExpectReceived, log?: string[], timedOut?: boolean, errorMessage?: string };
const kDummyFrameId = '<dummy>';
@@ -1443,7 +1444,7 @@ export class Frame extends SdkObject<FrameEventMap> {
async expect(progress: Progress, selector: string | undefined, options: FrameExpectParams): Promise<ExpectResult> {
progress.log(`${renderTitleForCall(progress.metadata)}${options.timeoutForLogs ? ` with timeout ${options.timeoutForLogs}ms` : ''}`);
- const lastIntermediateResult: { received?: any, isSet: boolean, errorMessage?: string } = { isSet: false };
+ const lastIntermediateResult: { received?: ExpectReceived, isSet: boolean, errorMessage?: string } = { isSet: false };
const fixupMetadataError = (result: ExpectResult) => {
// Library mode special case for the expect errors which are return values, not exceptions.
if (result.matches === options.isNot)
@@ -1503,7 +1504,7 @@ export class Frame extends SdkObject<FrameEventMap> {
}
}
- private async _expectInternal(progress: Progress, selector: string | undefined, options: FrameExpectParams, lastIntermediateResult: { received?: any, isSet: boolean, errorMessage?: string }, noAbort: boolean) {
+ private async _expectInternal(progress: Progress, selector: string | undefined, options: FrameExpectParams, lastIntermediateResult: { received?: ExpectReceived, isSet: boolean, errorMessage?: string }, noAbort: boolean) {
const progressLog = (text: string) => progress.log(text);
const callId = progress.metadata.id;
// The first expect check, a.k.a. one-shot, always finishes - even when progress is aborted.
@@ -1537,15 +1538,11 @@ export class Frame extends SdkObject<FrameEventMap> {
progressLog(log);
// Note: missingReceived avoids `unexpected value "undefined"` when element was not found.
if (matches === options.isNot) {
- if (missingReceived) {
- lastIntermediateResult.errorMessage = 'Error: element(s) not found';
- } else {
- lastIntermediateResult.errorMessage = undefined;
- lastIntermediateResult.received = received;
- }
+ lastIntermediateResult.errorMessage = missingReceived ? 'Error: element(s) not found' : undefined;
+ lastIntermediateResult.received = received;
lastIntermediateResult.isSet = true;
- if (!missingReceived && !Array.isArray(received))
- progressLog(` unexpected value "${renderUnexpectedValue(options.expression, received)}"`);
+ if (!missingReceived && !Array.isArray(received?.value))
+ progressLog(` unexpected value "${renderUnexpectedValue(options.expression, received?.value)}"`);
}
return { matches, received };
}
diff --git a/packages/playwright/src/matchers/matcherHint.ts b/packages/playwright/src/matchers/matcherHint.ts
index 442b459680..8217718bcd 100644
--- a/packages/playwright/src/matchers/matcherHint.ts
+++ b/packages/playwright/src/matchers/matcherHint.ts
@@ -132,6 +132,7 @@ type MatcherMessageDetails = {
timeout?: number;
errorMessage?: string;
log?: string[];
+ ariaSnapshot?: string;
};
export function formatMatcherMessage(utils: InternalMatcherUtils, details: MatcherMessageDetails) {
@@ -169,6 +170,8 @@ export function formatMatcherMessage(utils: InternalMatcherUtils, details: Match
message += '\n';
}
message += callLogText(utils, details.log);
+ if (details.ariaSnapshot)
+ message += `\nAria snapshot:\n${utils.DIM_COLOR(details.ariaSnapshot)}\n`;
return message;
}
diff --git a/packages/playwright/src/matchers/matchers.ts b/packages/playwright/src/matchers/matchers.ts
index 86f3191b36..d2fedd70cd 100644
--- a/packages/playwright/src/matchers/matchers.ts
+++ b/packages/playwright/src/matchers/matchers.ts
@@ -36,6 +36,7 @@ import type { ExpectMatcherState } from '../../types/test';
import type { ExpectTestInfo } from './expect';
import type { InternalMatcherUtils } from './matcherHint';
import type { APIResponse, Locator, Frame, Page } from 'playwright-core';
+import type { ExpectResult } from 'playwright-core/lib/client/frame';
import type { FrameExpectParams } from 'playwright-core/lib/client/types';
import type { ExpectMatcherUtils } from '../../types/test';
import type { URLPattern } from '@isomorphic/urlMatch';
@@ -46,11 +47,11 @@ export type ExpectMatcherStateInternal = Omit<ExpectMatcherState, 'utils'> & {
export interface LocatorEx extends Locator {
_selector: string;
- _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }>;
+ _expect(expression: string, options: FrameExpectParams): Promise<ExpectResult>;
}
export interface FrameEx extends Frame {
- _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }>;
+ _expect(expression: string, options: FrameExpectParams): Promise<ExpectResult>;
}
interface APIResponseEx extends APIResponse {
diff --git a/packages/playwright/src/matchers/toBeTruthy.ts b/packages/playwright/src/matchers/toBeTruthy.ts
index 74b9132fe1..15ad6c4f49 100644
--- a/packages/playwright/src/matchers/toBeTruthy.ts
+++ b/packages/playwright/src/matchers/toBeTruthy.ts
@@ -18,6 +18,7 @@ import { expectTypes, formatMatcherMessage } from './matcherHint';
import type { MatcherResult } from './matcherHint';
import type { Locator } from 'playwright-core';
+import type { ExpectResult } from 'playwright-core/lib/client/frame';
import type { ExpectMatcherStateInternal } from './matchers';
export async function toBeTruthy(
@@ -27,7 +28,7 @@ export async function toBeTruthy(
receiverType: 'Locator',
expected: string,
arg: string,
- query: (isNot: boolean, timeout: number) => Promise<{ matches: boolean, log?: string[], received?: any, timedOut?: boolean, errorMessage?: string }>,
+ query: (isNot: boolean, timeout: number) => Promise<ExpectResult>,
options: { timeout?: number } = {},
): Promise<MatcherResult<any, any>> {
expectTypes(locator, [receiverType], matcherName);
@@ -35,6 +36,7 @@ export async function toBeTruthy(
const timeout = options.timeout ?? this.timeout;
const { matches: pass, log, timedOut, received, errorMessage } = await query(!!this.isNot, timeout);
+ const receivedValue = received?.value;
if (pass === !this.isNot) {
return {
@@ -52,7 +54,7 @@ export async function toBeTruthy(
printedReceived = errorMessage ? '' : `Received: ${expected}`;
} else {
printedExpected = `Expected: ${expected}`;
- printedReceived = errorMessage ? '' : `Received: ${received}`;
+ printedReceived = errorMessage ? '' : `Received: ${receivedValue}`;
}
const message = () => {
return formatMatcherMessage(this.utils, {
@@ -67,13 +69,14 @@ export async function toBeTruthy(
printedReceived,
errorMessage,
log,
+ ariaSnapshot: received?.ariaSnapshot,
});
};
return {
message,
pass,
- actual: received,
+ actual: receivedValue,
name: matcherName,
expected,
log,
diff --git a/packages/playwright/src/matchers/toEqual.ts b/packages/playwright/src/matchers/toEqual.ts
index 01fc9414ad..0b45dce8ef 100644
--- a/packages/playwright/src/matchers/toEqual.ts
+++ b/packages/playwright/src/matchers/toEqual.ts
@@ -20,6 +20,7 @@ import { expectTypes, formatMatcherMessage } from './matcherHint';
import type { MatcherResult } from './matcherHint';
import type { Locator } from 'playwright-core';
+import type { ExpectResult } from 'playwright-core/lib/client/frame';
import type { ExpectMatcherStateInternal } from './matchers';
// Omit colon and one or more spaces, so can call getLabelPrinter.
@@ -31,7 +32,7 @@ export async function toEqual<T>(
matcherName: string,
locator: Locator,
receiverType: 'Locator',
- query: (isNot: boolean, timeout: number) => Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }>,
+ query: (isNot: boolean, timeout: number) => Promise<ExpectResult>,
expected: T,
options: { timeout?: number, contains?: boolean } = {},
): Promise<MatcherResult<any, any>> {
@@ -40,6 +41,7 @@ export async function toEqual<T>(
const timeout = options.timeout ?? this.timeout;
const { matches: pass, received, log, timedOut, errorMessage } = await query(!!this.isNot, timeout);
+ const receivedValue = received?.value;
if (pass === !this.isNot) {
return {
@@ -55,12 +57,12 @@ export async function toEqual<T>(
let printedDiff: string | undefined;
if (pass) {
printedExpected = `Expected: not ${this.utils.printExpected(expected)}`;
- printedReceived = errorMessage ? '' : `Received: ${this.utils.printReceived(received)}`;
+ printedReceived = errorMessage ? '' : `Received: ${this.utils.printReceived(receivedValue)}`;
} else if (errorMessage) {
printedExpected = `Expected: ${this.utils.printExpected(expected)}`;
- } else if (Array.isArray(expected) && Array.isArray(received)) {
+ } else if (Array.isArray(expected) && Array.isArray(receivedValue)) {
const normalizedExpected = expected.map((exp, index) => {
- const rec = received[index];
+ const rec = receivedValue[index];
if (isRegExp(exp))
return exp.test(rec) ? rec : exp;
@@ -68,7 +70,7 @@ export async function toEqual<T>(
});
printedDiff = this.utils.printDiffOrStringify(
normalizedExpected,
- received,
+ receivedValue,
EXPECTED_LABEL,
RECEIVED_LABEL,
false,
@@ -76,7 +78,7 @@ export async function toEqual<T>(
} else {
printedDiff = this.utils.printDiffOrStringify(
expected,
- received,
+ receivedValue,
EXPECTED_LABEL,
RECEIVED_LABEL,
false,
@@ -96,6 +98,7 @@ export async function toEqual<T>(
printedDiff,
errorMessage,
log,
+ ariaSnapshot: received?.ariaSnapshot,
});
};
@@ -103,7 +106,7 @@ export async function toEqual<T>(
// could access them, for example in order to display a custom visual diff,
// or create a different error message
return {
- actual: received,
+ actual: receivedValue,
expected, message,
name: matcherName,
pass,
diff --git a/packages/playwright/src/matchers/toMatchAriaSnapshot.ts b/packages/playwright/src/matchers/toMatchAriaSnapshot.ts
index cbdfa0a16c..5194479f35 100644
--- a/packages/playwright/src/matchers/toMatchAriaSnapshot.ts
+++ b/packages/playwright/src/matchers/toMatchAriaSnapshot.ts
@@ -93,7 +93,7 @@ export async function toMatchAriaSnapshot(
const { matches: pass, received, log, timedOut, errorMessage } = locator ?
await (locator as LocatorEx)._expect('to.match.aria', expectParams) :
await ((receiver as Page).mainFrame() as FrameEx)._expect('to.match.aria', expectParams);
- const typedReceived = received as MatcherReceived;
+ const typedReceived = received?.value as MatcherReceived;
const message = () => {
let printedExpected: string | undefined;
@@ -159,7 +159,7 @@ export async function toMatchAriaSnapshot(
expected,
message,
pass,
- actual: received,
+ actual: typedReceived?.raw,
log,
timeout: timedOut ? timeout : undefined,
};
diff --git a/packages/playwright/src/matchers/toMatchText.ts b/packages/playwright/src/matchers/toMatchText.ts
index 65f46134fc..0984943a36 100644
--- a/packages/playwright/src/matchers/toMatchText.ts
+++ b/packages/playwright/src/matchers/toMatchText.ts
@@ -18,6 +18,7 @@ import { expectTypes, formatMatcherMessage, printReceivedStringContainExpectedRe
import type { MatcherResult } from './matcherHint';
import type { Page, Locator } from 'playwright-core';
+import type { ExpectResult } from 'playwright-core/lib/client/frame';
import type { ExpectMatcherStateInternal } from './matchers';
export async function toMatchText(
@@ -25,7 +26,7 @@ export async function toMatchText(
matcherName: string,
receiver: Locator | Page,
receiverType: 'Locator' | 'Page',
- query: (isNot: boolean, timeout: number) => Promise<{ matches: boolean, received?: string, log?: string[], timedOut?: boolean, errorMessage?: string }>,
+ query: (isNot: boolean, timeout: number) => Promise<ExpectResult>,
expected: string | RegExp,
options: { timeout?: number, matchSubstring?: boolean } = {},
): Promise<MatcherResult<string | RegExp, string>> {
@@ -55,7 +56,8 @@ export async function toMatchText(
const expectedSuffix = typeof expected === 'string' ? (options.matchSubstring ? ' substring' : '') : ' pattern';
const receivedSuffix = typeof expected === 'string' ? (options.matchSubstring ? ' string' : '') : ' string';
- const receivedString = received || '';
+ const receivedValue = received?.value as string | undefined;
+ const receivedString = receivedValue || '';
let printedReceived: string | undefined;
let printedExpected: string | undefined;
let printedDiff: string | undefined;
@@ -94,6 +96,7 @@ export async function toMatchText(
printedDiff,
log,
errorMessage,
+ ariaSnapshot: received?.ariaSnapshot,
});
};
@@ -102,7 +105,7 @@ export async function toMatchText(
expected,
message,
pass,
- actual: received,
+ actual: receivedValue,
log,
timeout: timedOut ? timeout : undefined,
};
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index 8125a83d92..f44c9f9517 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -3518,7 +3518,10 @@ export type FrameExpectOptions = {
};
export type FrameExpectResult = {
matches: boolean,
- received?: SerializedValue,
+ received?: {
+ value?: SerializedValue,
+ ariaSnapshot?: string,
+ },
timedOut?: boolean,
errorMessage?: string,
log?: string[],
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index 4ec62cb7f1..04384e56b6 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -3002,7 +3002,11 @@ Frame:
timeout: float
returns:
matches: boolean
- received: SerializedValue?
+ received:
+ type: object?
+ properties:
+ value: SerializedValue?
+ ariaSnapshot: string?
timedOut: boolean?
errorMessage: string?
log:
diff --git a/packages/trace-viewer/src/ui/callTab.tsx b/packages/trace-viewer/src/ui/callTab.tsx
index 943ec4a897..63ca7f567a 100644
--- a/packages/trace-viewer/src/ui/callTab.tsx
+++ b/packages/trace-viewer/src/ui/callTab.tsx
@@ -103,8 +103,17 @@ function propertyToString(event: ActionTraceEvent, name: string, value: any, sdk
return { text: '<files>', type: 'string', name };
if (name === 'eventInit' || name === 'expectedValue' || (name === 'arg' && isEval))
value = parseSerializedValue(value.value, new Array(10).fill({ handle: '<handle>' }));
- if ((name === 'value' && isEval) || (name === 'received' && event.method === 'expect'))
+ if (name === 'value' && isEval)
value = parseSerializedValue(value, new Array(10).fill({ handle: '<handle>' }));
+ if (name === 'received' && event.method === 'expect') {
+ // Older traces store received as a raw SerializedValue; newer traces wrap it
+ // as { value?: SerializedValue, ariaSnapshot?: string }. Support both.
+ const wrapped = value && typeof value === 'object' && ('value' in value || 'ariaSnapshot' in value);
+ const serialized = wrapped ? value.value : value;
+ value = serialized !== undefined
+ ? parseSerializedValue(serialized, new Array(10).fill({ handle: '<handle>' }))
+ : undefined;
+ }
if (name === 'selector')
return { text: asLocator(sdkLanguage || 'javascript', event.params.selector), type: 'locator', name: 'locator' };
const type = typeof value;
diff --git a/tests/page/expect-with-snapshot.spec.ts b/tests/page/expect-with-snapshot.spec.ts
new file mode 100644
index 0000000000..e16e2e52f7
--- /dev/null
+++ b/tests/page/expect-with-snapshot.spec.ts
@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { stripAnsi } from '../config/utils';
+import { test, expect } from './pageTest';
+
+test.describe('containment matchers print full element subtree', () => {
+ test('toHaveText failure includes full element subtree', async ({ page }) => {
+ await page.setContent(`<section id=node><h1>Title</h1><p>Body</p></section>`);
+ const error = await expect(page.locator('#node')).toHaveText('nope', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('heading "Title"');
+ expect(message).toContain('paragraph');
+ expect(message).toContain('Body');
+ });
+
+ test('toContainText failure includes full element subtree', async ({ page }) => {
+ await page.setContent(`<section id=node><h1>Title</h1><p>Body</p></section>`);
+ const error = await expect(page.locator('#node')).toContainText('nope', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('heading "Title"');
+ expect(message).toContain('Body');
+ });
+});
+
+test.describe('property matchers print only the element line', () => {
+ test('toBeChecked failure prints just the input', async ({ page }) => {
+ await page.setContent(`<label><input id=cb type=checkbox> a checkbox</label>`);
+ const error = await expect(page.locator('#cb')).toBeChecked({ timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('checkbox');
+ });
+
+ test('toHaveAttribute failure clips descendant subtree', async ({ page }) => {
+ await page.setContent(`<ul id=lst><li><h2>HeadingMarker</h2><p>BodyMarker</p></li></ul>`);
+ const error = await expect(page.locator('#lst')).toHaveAttribute('data-x', 'yes', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('list');
+ expect(message).toContain('listitem');
+ // Property matcher caps depth at 1 — content inside the listitem (depth 2) must not appear.
+ expect(message).not.toContain('HeadingMarker');
+ expect(message).not.toContain('BodyMarker');
+ });
+
+ test('toHaveRole failure prints just the element line', async ({ page }) => {
+ await page.setContent(`<button id=btn>Hi<span>nested</span></button>`);
+ const error = await expect(page.locator('#btn')).toHaveRole('link', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('button');
+ });
+
+ test('toHaveValue failure prints the input element', async ({ page }) => {
+ await page.setContent(`<input id=inp value="actual">`);
+ const error = await expect(page.locator('#inp')).toHaveValue('expected', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('textbox');
+ });
+
+ test('toHaveCSS failure prints the element line', async ({ page }) => {
+ await page.setContent(`<button id=btn style="color: red">Press</button>`);
+ const error = await expect(page.locator('#btn')).toHaveCSS('color', 'rgb(0, 0, 0)', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('button');
+ });
+});
+
+test.describe('hidden or missing elements print full page snapshot', () => {
+ test('toBeVisible on hidden element prints full page snapshot', async ({ page }) => {
+ await page.setContent(`
+ <div id=hidden style="display: none"><span>secret</span></div>
+ <main><h1>Page Heading</h1></main>
+ `);
+ const error = await expect(page.locator('#hidden')).toBeVisible({ timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ // Page-wide context, not the empty hidden element snapshot.
+ expect(message).toContain('heading "Page Heading"');
+ });
+
+ test('toBeVisible on missing element prints full page snapshot', async ({ page }) => {
+ await page.setContent(`<header><h1>Hello</h1></header>`);
+ const error = await expect(page.locator('#nope')).toBeVisible({ timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('heading "Hello"');
+ });
+
+ test('toHaveText on missing element prints full page snapshot', async ({ page }) => {
+ await page.setContent(`<main><h1>Hello</h1></main>`);
+ const error = await expect(page.locator('#missing')).toHaveText('x', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('heading "Hello"');
+ });
+
+ test('toHaveTitle failure prints full page snapshot', async ({ page }) => {
+ await page.setContent(`<title>Right</title><main><h1>Body Heading</h1></main>`);
+ const error = await expect(page).toHaveTitle('Wrong', { timeout: 1000 }).catch(e => e);
+ const message = stripAnsi(error.message);
+ expect(message).toContain('Aria snapshot:');
+ expect(message).toContain('heading "Body Heading"');
+ });
+});
+
+test.describe('matchers that should not include an aria snapshot', () => {
+ test('toHaveCount failure has no aria snapshot', async ({ page }) => {
+ await page.setContent(`<ul><li>a</li><li>b</li></ul>`);
+ const error = await expect(page.locator('li')).toHaveCount(5, { timeout: 1000 }).catch(e => e);
+ expect(stripAnsi(error.message)).not.toContain('Aria snapshot:');
+ });
+
+ test('toHaveText with array has no aria snapshot', async ({ page }) => {
+ await page.setContent(`<ul><li>x</li><li>y</li></ul>`);
+ const error = await expect(page.locator('li')).toHaveText(['a', 'b', 'c'], { timeout: 1000 }).catch(e => e);
+ expect(stripAnsi(error.message)).not.toContain('Aria snapshot:');
+ });
+
+ test('toMatchAriaSnapshot failure has no extra aria snapshot section', async ({ page }) => {
+ await page.setContent(`<button id=btn>Y</button>`);
+ const error = await expect(page.locator('#btn')).toMatchAriaSnapshot(`- button "X"`, { timeout: 1000 }).catch(e => e);
+ expect(stripAnsi(error.message)).not.toContain('Aria snapshot:');
+ });
+});