Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
chore: update debugger api after review (#39875)
Dmitry Gozman7fbb21ee10bf
diff --git a/docs/src/api/class-debugger.md b/docs/src/api/class-debugger.mdindex f7d66d4d17..6334a4ab67 100644--- a/docs/src/api/class-debugger.md+++ b/docs/src/api/class-debugger.md@@ -11,23 +11,23 @@ Emitted when the debugger pauses or resumes.## method: Debugger.pausedDetails* since: v1.59-- returns: <[Array]<[Object]>>+- returns: <[null]|[Object]>- `location` <[Object]>- `file` <[string]>- `line` ?<[int]>- `column` ?<[int]>- `title` <[string]>-Returns details about the currently paused calls. Returns an empty array if the debugger is not paused.+Returns details about the currently paused call. Returns `null` if the debugger is not paused.-## async method: Debugger.pause+## async method: Debugger.requestPause* since: v1.59Configures the debugger to pause before the next action is executed.Throws if the debugger is already paused. Use [`method: Debugger.next`] or [`method: Debugger.runTo`] to step while paused.-Note that [`method: Page.pause`] is equivalent to a "debugger" statement — it pauses execution at the call site immediately. On the contrary, [`method: Debugger.pause`] is equivalent to "pause on next statement" — it configures the debugger to pause before the next action is executed.+Note that [`method: Page.pause`] is equivalent to a "debugger" statement — it pauses execution at the call site immediately. On the contrary, [`method: Debugger.requestPause`] is equivalent to "pause on next statement" — it configures the debugger to pause before the next action is executed.## async method: Debugger.resume* since: v1.59diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 9dc845812c..190426946d 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -19531,23 +19531,9 @@ export interface Debugger {next(): Promise<void>;/**- * Configures the debugger to pause before the next action is executed.- *- * Throws if the debugger is already paused. Use- * [debugger.next()](https://playwright.dev/docs/api/class-debugger#debugger-next) or- * [debugger.runTo(location)](https://playwright.dev/docs/api/class-debugger#debugger-run-to) to step while paused.- *- * Note that [page.pause()](https://playwright.dev/docs/api/class-page#page-pause) is equivalent to a "debugger"- * statement — it pauses execution at the call site immediately. On the contrary,- * [debugger.pause()](https://playwright.dev/docs/api/class-debugger#debugger-pause) is equivalent to "pause on next- * statement" — it configures the debugger to pause before the next action is executed.- */- pause(): Promise<void>;-- /**- * Returns details about the currently paused calls. Returns an empty array if the debugger is not paused.+ * Returns details about the currently paused call. Returns `null` if the debugger is not paused.*/- pausedDetails(): Array<{+ pausedDetails(): null|{location: {file: string;@@ -19557,7 +19543,21 @@ export interface Debugger {};title: string;- }>;+ };++ /**+ * Configures the debugger to pause before the next action is executed.+ *+ * Throws if the debugger is already paused. Use+ * [debugger.next()](https://playwright.dev/docs/api/class-debugger#debugger-next) or+ * [debugger.runTo(location)](https://playwright.dev/docs/api/class-debugger#debugger-run-to) to step while paused.+ *+ * Note that [page.pause()](https://playwright.dev/docs/api/class-page#page-pause) is equivalent to a "debugger"+ * statement — it pauses execution at the call site immediately. On the contrary,+ * [debugger.requestPause()](https://playwright.dev/docs/api/class-debugger#debugger-request-pause) is equivalent to+ * "pause on next statement" — it configures the debugger to pause before the next action is executed.+ */+ requestPause(): Promise<void>;/*** Resumes script execution. Throws if the debugger is not paused.diff --git a/packages/playwright-core/src/client/debugger.ts b/packages/playwright-core/src/client/debugger.tsindex bc2a018018..b83427bdb0 100644--- a/packages/playwright-core/src/client/debugger.ts+++ b/packages/playwright-core/src/client/debugger.ts@@ -20,10 +20,10 @@ import { Events } from './events';import type * as api from '../../types/types';import type * as channels from '@protocol/channels';-type PausedDetail = { location: { file: string, line?: number, column?: number }, title: string };+type PausedDetails = { location: { file: string, line?: number, column?: number }, title: string, stack?: string };export class Debugger extends ChannelOwner<channels.DebuggerChannel> implements api.Debugger {- private _pausedDetails: PausedDetail[] = [];+ private _pausedDetails: PausedDetails | null = null;static from(channel: channels.DebuggerChannel): Debugger {return (channel as any)._object;@@ -32,13 +32,13 @@ export class Debugger extends ChannelOwner<channels.DebuggerChannel> implementsconstructor(parent: ChannelOwner, type: string, guid: string, initializer: channels.DebuggerInitializer) {super(parent, type, guid, initializer);this._channel.on('pausedStateChanged', ({ pausedDetails }) => {- this._pausedDetails = pausedDetails;+ this._pausedDetails = pausedDetails ?? null;this.emit(Events.Debugger.PausedStateChanged);});}- async pause(): Promise<void> {- await this._channel.pause();+ async requestPause(): Promise<void> {+ await this._channel.requestPause();}async resume(): Promise<void> {@@ -53,7 +53,7 @@ export class Debugger extends ChannelOwner<channels.DebuggerChannel> implementsawait this._channel.runTo({ location });}- pausedDetails(): PausedDetail[] {+ pausedDetails(): PausedDetails | null {return this._pausedDetails;}}diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex 038293fec4..f4b82348d0 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -2524,17 +2524,18 @@ scheme.BindingCallResolveParams = tObject({scheme.BindingCallResolveResult = tOptional(tObject({}));scheme.DebuggerInitializer = tOptional(tObject({}));scheme.DebuggerPausedStateChangedEvent = tObject({- pausedDetails: tArray(tObject({+ pausedDetails: tOptional(tObject({location: tObject({file: tString,line: tOptional(tInt),column: tOptional(tInt),}),title: tString,+ stack: tOptional(tString),})),});-scheme.DebuggerPauseParams = tOptional(tObject({}));-scheme.DebuggerPauseResult = tOptional(tObject({}));+scheme.DebuggerRequestPauseParams = tOptional(tObject({}));+scheme.DebuggerRequestPauseResult = tOptional(tObject({}));scheme.DebuggerResumeParams = tOptional(tObject({}));scheme.DebuggerResumeResult = tOptional(tObject({}));scheme.DebuggerNextParams = tOptional(tObject({}));diff --git a/packages/playwright-core/src/server/debugger.ts b/packages/playwright-core/src/server/debugger.tsindex 54d45fd3aa..0e20b61c5c 100644--- a/packages/playwright-core/src/server/debugger.ts+++ b/packages/playwright-core/src/server/debugger.ts@@ -27,7 +27,7 @@ type PauseAt = { next?: boolean, location?: { file: string, line?: number, columexport class Debugger extends SdkObject implements InstrumentationListener {private _pauseAt: PauseAt = {};- private _pausedCallsMetadata = new Map<CallMetadata, { resolve: () => void, sdkObject: SdkObject }>();+ private _pausedCall: { metadata: CallMetadata, sdkObject: SdkObject, resolve: () => void } | undefined;private _enabled = false;private _pauseBeforeWaitingActions = false; // instead of inside input actionsprivate _context: BrowserContext;@@ -74,25 +74,24 @@ export class Debugger extends SdkObject implements InstrumentationListener {private async _pause(sdkObject: SdkObject, metadata: CallMetadata) {if (this._muted || metadata.internal)return;+ if (this._pausedCall)+ return;this._pauseAt = {};metadata.pauseStartTime = monotonicTime();const result = new Promise<void>(resolve => {- this._pausedCallsMetadata.set(metadata, { resolve, sdkObject });+ this._pausedCall = { metadata, sdkObject, resolve };});this.emit(Debugger.Events.PausedStateChanged);return result;}resume() {- if (!this.isPaused())+ if (!this._pausedCall)return;- const endTime = monotonicTime();- for (const [metadata, { resolve }] of this._pausedCallsMetadata) {- metadata.pauseEndTime = endTime;- resolve();- }- this._pausedCallsMetadata.clear();+ this._pausedCall.metadata.pauseEndTime = monotonicTime();+ this._pausedCall.resolve();+ this._pausedCall = undefined;this.emit(Debugger.Events.PausedStateChanged);}@@ -107,15 +106,12 @@ export class Debugger extends SdkObject implements InstrumentationListener {isPaused(metadata?: CallMetadata): boolean {if (metadata)- return this._pausedCallsMetadata.has(metadata);- return !!this._pausedCallsMetadata.size;+ return this._pausedCall?.metadata === metadata;+ return !!this._pausedCall;}- pausedDetails(): { metadata: CallMetadata, sdkObject: SdkObject }[] {- const result: { metadata: CallMetadata, sdkObject: SdkObject }[] = [];- for (const [metadata, { sdkObject }] of this._pausedCallsMetadata)- result.push({ metadata, sdkObject });- return result;+ pausedDetails(): { metadata: CallMetadata, sdkObject: SdkObject } | undefined {+ return this._pausedCall;}}diff --git a/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts b/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.tsindex b1c9499901..36cb85c0f9 100644--- a/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts@@ -40,17 +40,21 @@ export class DebuggerDispatcher extends Dispatcher<Debugger, channels.DebuggerCh}private _serializePausedDetails(): channels.DebuggerPausedStateChangedEvent['pausedDetails'] {- return this._object.pausedDetails().map(({ metadata, sdkObject }) => ({+ const details = this._object.pausedDetails();+ if (!details)+ return undefined;+ const { metadata } = details;+ return {location: {file: metadata.location?.file ?? '<unknown>',line: metadata.location?.line,column: metadata.location?.column,},title: renderTitleForCall(metadata),- }));+ };}- async pause(params: channels.DebuggerPauseParams, progress: Progress): Promise<void> {+ async requestPause(params: channels.DebuggerRequestPauseParams, progress: Progress): Promise<void> {if (this._object.isPaused())throw new Error('Debugger is already paused');this._object.setPauseBeforeWaitingActions();diff --git a/packages/playwright-core/src/server/recorder.ts b/packages/playwright-core/src/server/recorder.tsindex 7eff6de95f..1d71377458 100644--- a/packages/playwright-core/src/server/recorder.ts+++ b/packages/playwright-core/src/server/recorder.ts@@ -243,10 +243,9 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrumeprivate _pausedStateChanged() {// If we are called upon page.pause, we don't have metadatas, populate them.- for (const { metadata, sdkObject } of this._debugger.pausedDetails()) {- if (!this._currentCallsMetadata.has(metadata))- this.onBeforeCall(sdkObject, metadata);- }+ const pausedDetails = this._debugger.pausedDetails();+ if (pausedDetails && !this._currentCallsMetadata.has(pausedDetails.metadata))+ this.onBeforeCall(pausedDetails.sdkObject, pausedDetails.metadata);this.emit(RecorderEvent.PausedStateChanged, this._debugger.isPaused());this._updateUserSources();this.updateCallLog([...this._currentCallsMetadata.keys()]);@@ -356,13 +355,11 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume}pausedSourceId() {- for (const { metadata } of this._debugger.pausedDetails()) {- if (!metadata.location)- continue;- const source = this._userSources.get(metadata.location.file);- if (!source)- continue;- return source.id;+ const pausedDetails = this._debugger.pausedDetails();+ if (pausedDetails?.metadata.location) {+ const source = this._userSources.get(pausedDetails.metadata.location.file);+ if (source)+ return source.id;}}diff --git a/packages/playwright-core/src/tools/backend/devtools.ts b/packages/playwright-core/src/tools/backend/devtools.tsindex 6803c27c17..0db0a83664 100644--- a/packages/playwright-core/src/tools/backend/devtools.ts+++ b/packages/playwright-core/src/tools/backend/devtools.ts@@ -35,7 +35,7 @@ const resume = defineTool({const browserContext = await context.ensureBrowserContext();const pausedPromise = new Promise<void>(resolve => {const listener = () => {- if (browserContext.debugger.pausedDetails().length > 0) {+ if (browserContext.debugger.pausedDetails()) {browserContext.debugger.off('pausedstatechanged', listener);resolve();}diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.tsindex 8b681daeb5..1e3514ae4e 100644--- a/packages/playwright-core/src/tools/backend/response.ts+++ b/packages/playwright-core/src/tools/backend/response.ts@@ -244,9 +244,9 @@ export class Response {addSection('Events', text);const pausedDetails = this._context.debugger().pausedDetails();- if (pausedDetails.length) {+ if (pausedDetails) {addSection('Paused', [- ...pausedDetails.map(call => `- ${call.title} at ${this._computRelativeTo(call.location.file)}${call.location.line ? ':' + call.location.line : ''}`),+ `- ${pausedDetails.title} at ${this._computRelativeTo(pausedDetails.location.file)}${pausedDetails.location.line ? ':' + pausedDetails.location.line : ''}`,'- Use any tools to explore and interact, resume by calling resume/step-over/pause-at',]);}diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.tsindex 70e91bff28..bdbf457ede 100644--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts@@ -277,7 +277,7 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([['Response.sizes', { internal: true, }],['BindingCall.reject', { internal: true, }],['BindingCall.resolve', { internal: true, }],- ['Debugger.pause', { title: 'Pause on next call', group: 'configuration', }],+ ['Debugger.requestPause', { title: 'Pause on next call', group: 'configuration', }],['Debugger.resume', { title: 'Resume', group: 'configuration', }],['Debugger.next', { title: 'Step to next call', group: 'configuration', }],['Debugger.runTo', { title: 'Run to location', group: 'configuration', }],diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 9dc845812c..190426946d 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -19531,23 +19531,9 @@ export interface Debugger {next(): Promise<void>;/**- * Configures the debugger to pause before the next action is executed.- *- * Throws if the debugger is already paused. Use- * [debugger.next()](https://playwright.dev/docs/api/class-debugger#debugger-next) or- * [debugger.runTo(location)](https://playwright.dev/docs/api/class-debugger#debugger-run-to) to step while paused.- *- * Note that [page.pause()](https://playwright.dev/docs/api/class-page#page-pause) is equivalent to a "debugger"- * statement — it pauses execution at the call site immediately. On the contrary,- * [debugger.pause()](https://playwright.dev/docs/api/class-debugger#debugger-pause) is equivalent to "pause on next- * statement" — it configures the debugger to pause before the next action is executed.- */- pause(): Promise<void>;-- /**- * Returns details about the currently paused calls. Returns an empty array if the debugger is not paused.+ * Returns details about the currently paused call. Returns `null` if the debugger is not paused.*/- pausedDetails(): Array<{+ pausedDetails(): null|{location: {file: string;@@ -19557,7 +19543,21 @@ export interface Debugger {};title: string;- }>;+ };++ /**+ * Configures the debugger to pause before the next action is executed.+ *+ * Throws if the debugger is already paused. Use+ * [debugger.next()](https://playwright.dev/docs/api/class-debugger#debugger-next) or+ * [debugger.runTo(location)](https://playwright.dev/docs/api/class-debugger#debugger-run-to) to step while paused.+ *+ * Note that [page.pause()](https://playwright.dev/docs/api/class-page#page-pause) is equivalent to a "debugger"+ * statement — it pauses execution at the call site immediately. On the contrary,+ * [debugger.requestPause()](https://playwright.dev/docs/api/class-debugger#debugger-request-pause) is equivalent to+ * "pause on next statement" — it configures the debugger to pause before the next action is executed.+ */+ requestPause(): Promise<void>;/*** Resumes script execution. Throws if the debugger is not paused.diff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.tsindex 90ae8c00e5..6bc72c0c15 100644--- a/packages/playwright/src/index.ts+++ b/packages/playwright/src/index.ts@@ -321,7 +321,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({},runAfterCreateBrowserContext: async (context: BrowserContextImpl) => {context.debugger.on('pausedstatechanged', () => {- const paused = context.debugger.pausedDetails().length > 0;+ const paused = !!context.debugger.pausedDetails();if (pausedContexts.has(context) && !paused) {pausedContexts.delete(context);(testInfo as TestInfoImpl)._setIgnoreTimeouts(false);diff --git a/packages/playwright/src/mcp/test/browserBackend.ts b/packages/playwright/src/mcp/test/browserBackend.tsindex 86104ccba4..9097254c3e 100644--- a/packages/playwright/src/mcp/test/browserBackend.ts+++ b/packages/playwright/src/mcp/test/browserBackend.ts@@ -125,6 +125,6 @@ export async function runDaemonForContext(testInfo: TestInfoImpl, context: playw`- Run "playwright-cli attach ${sessionName}" to attach to this test`,].join('\n'));- await context.debugger.pause();+ await context.debugger.requestPause();return true;}diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex 867c32d43a..4297025496 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -4365,24 +4365,25 @@ export interface DebuggerEventTarget {}export interface DebuggerChannel extends DebuggerEventTarget, EventTargetChannel {_type_Debugger: boolean;- pause(params?: DebuggerPauseParams, progress?: Progress): Promise<DebuggerPauseResult>;+ requestPause(params?: DebuggerRequestPauseParams, progress?: Progress): Promise<DebuggerRequestPauseResult>;resume(params?: DebuggerResumeParams, progress?: Progress): Promise<DebuggerResumeResult>;next(params?: DebuggerNextParams, progress?: Progress): Promise<DebuggerNextResult>;runTo(params: DebuggerRunToParams, progress?: Progress): Promise<DebuggerRunToResult>;}export type DebuggerPausedStateChangedEvent = {- pausedDetails: {+ pausedDetails?: {location: {file: string,line?: number,column?: number,},title: string,- }[],+ stack?: string,+ },};-export type DebuggerPauseParams = {};-export type DebuggerPauseOptions = {};-export type DebuggerPauseResult = void;+export type DebuggerRequestPauseParams = {};+export type DebuggerRequestPauseOptions = {};+export type DebuggerRequestPauseResult = void;export type DebuggerResumeParams = {};export type DebuggerResumeOptions = {};export type DebuggerResumeResult = void;diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex 1997744d2e..e732a24c8d 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -3901,7 +3901,7 @@ Debugger:commands:- pause:+ requestPause:title: Pause on next callgroup: configuration@@ -3929,17 +3929,16 @@ Debugger:pausedStateChanged:parameters:pausedDetails:- type: array- items:- type: object- properties:- location:- type: object- properties:- file: string- line: int?- column: int?- title: string+ type: object?+ properties:+ location:+ type: object+ properties:+ file: string+ line: int?+ column: int?+ title: string+ stack: string?Dialog:diff --git a/tests/library/debugger.spec.ts b/tests/library/debugger.spec.tsindex bf04c2365a..172de6bcdb 100644--- a/tests/library/debugger.spec.ts+++ b/tests/library/debugger.spec.ts@@ -20,46 +20,46 @@ it('should pause at next and resume', async ({ context, server }) => {const page = await context.newPage();await page.setContent('<div>click me</div>');const dbg = context.debugger;- expect(dbg.pausedDetails()).toEqual([]);+ expect(dbg.pausedDetails()).toBeNull();- await dbg.pause();+ await dbg.requestPause();const clickPromise = page.click('div');await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));- expect(dbg.pausedDetails()).toEqual([- expect.objectContaining({- title: expect.stringContaining('Click'),- location: expect.objectContaining({- file: expect.stringContaining('debugger.spec'),- line: expect.any(Number),- column: expect.any(Number),+ expect(dbg.pausedDetails()).toEqual(+ expect.objectContaining({+ title: expect.stringContaining('Click'),+ location: expect.objectContaining({+ file: expect.stringContaining('debugger.spec'),+ line: expect.any(Number),+ column: expect.any(Number),+ }),}),- }),- ]);+ );await Promise.all([dbg.resume(),new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve)),clickPromise,]);- expect(dbg.pausedDetails()).toEqual([]);+ expect(dbg.pausedDetails()).toBeNull();});it('should pause at pause call', async ({ context, server }) => {const page = await context.newPage();await page.setContent('<div>click me</div>');const dbg = context.debugger;- expect(dbg.pausedDetails()).toEqual([]);+ expect(dbg.pausedDetails()).toBeNull();- await dbg.pause();+ await dbg.requestPause();const pausePromise = page.pause();await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));- expect(dbg.pausedDetails()).toEqual([- expect.objectContaining({- title: expect.stringContaining('Pause'),- }),- ]);+ expect(dbg.pausedDetails()).toEqual(+ expect.objectContaining({+ title: expect.stringContaining('Pause'),+ }),+ );await dbg.resume();await pausePromise;@@ -69,10 +69,10 @@ it('should run to location', async ({ context, server }) => {const page = await context.newPage();await page.setContent('<div>click me</div>');const dbg = context.debugger;- expect(dbg.pausedDetails()).toEqual([]);+ expect(dbg.pausedDetails()).toBeNull();// First, pause on next action.- await dbg.pause();+ await dbg.requestPause();page.click('div').catch(() => {});await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));@@ -84,11 +84,11 @@ it('should run to location', async ({ context, server }) => {const clickPromise = page.click('div'); // should pause hereawait new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));- expect(dbg.pausedDetails()).toEqual([- expect.objectContaining({- title: expect.stringContaining('Click'),- }),- ]);+ expect(dbg.pausedDetails()).toEqual(+ expect.objectContaining({+ title: expect.stringContaining('Click'),+ }),+ );await dbg.resume();await clickPromise;diff --git a/tests/playwright-test/playwright.spec.ts b/tests/playwright-test/playwright.spec.tsindex 668b5a1567..e390970afc 100644--- a/tests/playwright-test/playwright.spec.ts+++ b/tests/playwright-test/playwright.spec.ts@@ -970,7 +970,7 @@ test('should pause test timeout while on pause', async ({ runInlineTest }) => {import { test, expect } from '@playwright/test';test('test', async ({ page, context }) => {- await context.debugger.pause();+ await context.debugger.requestPause();const paused = new Promise(f => context.debugger.once('pausedstatechanged', f));const contentPromise = page.setContent('<div>hello</div>');await paused;