Skip to content

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

chore: update debugger api (#39741)

Dmitry Gozman41613e55b9f4
diff --git a/docs/src/api/class-debugger.md b/docs/src/api/class-debugger.md
index 4f3068f7cc..044d1acfa9 100644
--- a/docs/src/api/class-debugger.md
+++ b/docs/src/api/class-debugger.md
@@ -5,8 +5,6 @@
API for controlling the Playwright debugger. The debugger allows pausing script execution and inspecting the page.
Obtain the debugger instance via [`property: BrowserContext.debugger`].
-See also [`method: Page.pause`] for a simple way to pause script execution.
-
## event: Debugger.pausedStateChanged
* since: v1.59
@@ -23,28 +21,35 @@ Emitted when the debugger pauses or resumes.
Returns details about the currently paused calls. Returns an empty array if the debugger is not paused.
+## async method: Debugger.pause
+* since: v1.59
+
+Configures 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.
+
## async method: Debugger.resume
* since: v1.59
-Resumes script execution if the debugger is paused.
+Resumes script execution. Throws if the debugger is not paused.
-## async method: Debugger.setPauseAt
+## async method: Debugger.next
* since: v1.59
-Configures the debugger to pause at the next action or at a specific source location.
-Call without arguments to reset the pausing behavior.
+Resumes script execution and pauses again before the next action. Throws if the debugger is not paused.
-### option: Debugger.setPauseAt.next
+## async method: Debugger.runTo
* since: v1.59
-- `next` <[boolean]>
-When `true`, the debugger will pause before the next action.
+Resumes script execution and pauses when an action originates from the given source location. Throws if the debugger is not paused.
-### option: Debugger.setPauseAt.location
+### param: Debugger.runTo.location
* since: v1.59
- `location` <[Object]>
- `file` <[string]>
- `line` ?<[int]>
- `column` ?<[int]>
-When specified, the debugger will pause when the action originates from the given source location.
+The source location to pause at.
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index c754d27e56..98132f06fd 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -19428,9 +19428,6 @@ export interface Coverage {
* API for controlling the Playwright debugger. The debugger allows pausing script execution and inspecting the page.
* Obtain the debugger instance via
* [browserContext.debugger](https://playwright.dev/docs/api/class-browsercontext#browser-context-debugger).
- *
- * See also [page.pause()](https://playwright.dev/docs/api/class-page#page-pause) for a simple way to pause script
- * execution.
*/
export interface Debugger {
/**
@@ -19463,6 +19460,25 @@ export interface Debugger {
*/
prependListener(event: 'pausedstatechanged', listener: () => any): this;
+ /**
+ * Resumes script execution and pauses again before the next action. Throws if the debugger is not paused.
+ */
+ 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.
*/
@@ -19479,31 +19495,21 @@ export interface Debugger {
}>;
/**
- * Resumes script execution if the debugger is paused.
+ * Resumes script execution. Throws if the debugger is not paused.
*/
resume(): Promise<void>;
/**
- * Configures the debugger to pause at the next action or at a specific source location. Call without arguments to
- * reset the pausing behavior.
- * @param options
+ * Resumes script execution and pauses when an action originates from the given source location. Throws if the
+ * debugger is not paused.
+ * @param location The source location to pause at.
*/
- setPauseAt(options?: {
- /**
- * When specified, the debugger will pause when the action originates from the given source location.
- */
- location?: {
- file: string;
-
- line?: number;
+ runTo(location: {
+ file: string;
- column?: number;
- };
+ line?: number;
- /**
- * When `true`, the debugger will pause before the next action.
- */
- next?: boolean;
+ column?: number;
}): Promise<void>;
}
diff --git a/packages/playwright-core/src/client/debugger.ts b/packages/playwright-core/src/client/debugger.ts
index 013e3c4173..bc2a018018 100644
--- a/packages/playwright-core/src/client/debugger.ts
+++ b/packages/playwright-core/src/client/debugger.ts
@@ -37,14 +37,22 @@ export class Debugger extends ChannelOwner<channels.DebuggerChannel> implements
});
}
- async setPauseAt(options: { next?: boolean, location?: { file: string, line?: number, column?: number } } = {}) {
- await this._channel.setPauseAt(options);
+ async pause(): Promise<void> {
+ await this._channel.pause();
}
async resume(): Promise<void> {
await this._channel.resume();
}
+ async next(): Promise<void> {
+ await this._channel.next();
+ }
+
+ async runTo(location: { file: string, line?: number, column?: number }): Promise<void> {
+ await this._channel.runTo({ location });
+ }
+
pausedDetails(): PausedDetail[] {
return this._pausedDetails;
}
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index 8c1109dceb..86a14ab62b 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -2509,17 +2509,20 @@ scheme.DebuggerPausedStateChangedEvent = tObject({
title: tString,
})),
});
-scheme.DebuggerSetPauseAtParams = tObject({
- next: tOptional(tBoolean),
- location: tOptional(tObject({
+scheme.DebuggerPauseParams = tOptional(tObject({}));
+scheme.DebuggerPauseResult = tOptional(tObject({}));
+scheme.DebuggerResumeParams = tOptional(tObject({}));
+scheme.DebuggerResumeResult = tOptional(tObject({}));
+scheme.DebuggerNextParams = tOptional(tObject({}));
+scheme.DebuggerNextResult = tOptional(tObject({}));
+scheme.DebuggerRunToParams = tObject({
+ location: tObject({
file: tString,
line: tOptional(tInt),
column: tOptional(tInt),
- })),
+ }),
});
-scheme.DebuggerSetPauseAtResult = tOptional(tObject({}));
-scheme.DebuggerResumeParams = tOptional(tObject({}));
-scheme.DebuggerResumeResult = tOptional(tObject({}));
+scheme.DebuggerRunToResult = tOptional(tObject({}));
scheme.DialogInitializer = tObject({
page: tOptional(tChannel(['Page'])),
type: tString,
diff --git a/packages/playwright-core/src/server/debugger.ts b/packages/playwright-core/src/server/debugger.ts
index a28d45e351..541f877717 100644
--- a/packages/playwright-core/src/server/debugger.ts
+++ b/packages/playwright-core/src/server/debugger.ts
@@ -54,7 +54,7 @@ export class Debugger extends SdkObject implements InstrumentationListener {
async onBeforeCall(sdkObject: SdkObject, metadata: CallMetadata): Promise<void> {
if (this._muted)
return;
- const pauseOnPauseCall = this._enabled && metadata.method === 'pause';
+ const pauseOnPauseCall = this._enabled && metadata.type === 'BrowserContext' && metadata.method === 'pause';
const pauseOnNextStep = !!this._pauseAt.next && shouldPauseBeforeStep(metadata, this._pauseBeforeInputActions);
const pauseOnLocation = !!this._pauseAt.location && matchesLocation(metadata, this._pauseAt.location);
if (pauseOnPauseCall || pauseOnNextStep || pauseOnLocation)
diff --git a/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts b/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts
index 2cfc43fe8f..43f69eb915 100644
--- a/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/debuggerDispatcher.ts
@@ -50,12 +50,32 @@ export class DebuggerDispatcher extends Dispatcher<Debugger, channels.DebuggerCh
}));
}
- async setPauseAt(params: channels.DebuggerSetPauseAtParams, progress: Progress): Promise<void> {
+ async pause(params: channels.DebuggerPauseParams, progress: Progress): Promise<void> {
+ if (this._object.isPaused())
+ throw new Error('Debugger is already paused');
this._object.setPauseBeforeInputActions();
- this._object.setPauseAt(params);
+ this._object.setPauseAt({ next: true });
}
async resume(params: channels.DebuggerResumeParams, progress: Progress): Promise<void> {
+ if (!this._object.isPaused())
+ throw new Error('Debugger is not paused');
+ this._object.resume();
+ }
+
+ async next(params: channels.DebuggerNextParams, progress: Progress): Promise<void> {
+ if (!this._object.isPaused())
+ throw new Error('Debugger is not paused');
+ this._object.setPauseBeforeInputActions();
+ this._object.setPauseAt({ next: true });
+ this._object.resume();
+ }
+
+ async runTo(params: channels.DebuggerRunToParams, progress: Progress): Promise<void> {
+ if (!this._object.isPaused())
+ throw new Error('Debugger is not paused');
+ this._object.setPauseBeforeInputActions();
+ this._object.setPauseAt({ location: params.location });
this._object.resume();
}
}
diff --git a/packages/playwright-core/src/tools/backend/devtools.ts b/packages/playwright-core/src/tools/backend/devtools.ts
index 7b61b0d021..6803c27c17 100644
--- a/packages/playwright-core/src/tools/backend/devtools.ts
+++ b/packages/playwright-core/src/tools/backend/devtools.ts
@@ -43,9 +43,9 @@ const resume = defineTool({
browserContext.debugger.on('pausedstatechanged', listener);
});
- let location;
if (params.location) {
const [file, lineStr] = params.location.split(':');
+ let location;
if (lineStr) {
const line = Number(lineStr);
if (isNaN(line))
@@ -54,10 +54,12 @@ const resume = defineTool({
} else {
location = { file: params.location };
}
+ await browserContext.debugger.runTo(location);
+ } else if (params.step) {
+ await browserContext.debugger.next();
+ } else {
+ await browserContext.debugger.resume();
}
-
- await browserContext.debugger.setPauseAt({ next: !!params.step, location });
- await browserContext.debugger.resume();
await pausedPromise;
},
});
diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
index a8d7ee1f9d..951b109102 100644
--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
@@ -272,8 +272,10 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri
['Response.sizes', { internal: true, }],
['BindingCall.reject', { internal: true, }],
['BindingCall.resolve', { internal: true, }],
- ['Debugger.setPauseAt', { title: 'Configure pause behavior', group: 'configuration', }],
+ ['Debugger.pause', { 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', }],
['Dialog.accept', { title: 'Accept dialog', }],
['Dialog.dismiss', { title: 'Dismiss dialog', }],
['Tracing.tracingStart', { title: 'Start tracing', group: 'configuration', }],
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index c754d27e56..98132f06fd 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -19428,9 +19428,6 @@ export interface Coverage {
* API for controlling the Playwright debugger. The debugger allows pausing script execution and inspecting the page.
* Obtain the debugger instance via
* [browserContext.debugger](https://playwright.dev/docs/api/class-browsercontext#browser-context-debugger).
- *
- * See also [page.pause()](https://playwright.dev/docs/api/class-page#page-pause) for a simple way to pause script
- * execution.
*/
export interface Debugger {
/**
@@ -19463,6 +19460,25 @@ export interface Debugger {
*/
prependListener(event: 'pausedstatechanged', listener: () => any): this;
+ /**
+ * Resumes script execution and pauses again before the next action. Throws if the debugger is not paused.
+ */
+ 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.
*/
@@ -19479,31 +19495,21 @@ export interface Debugger {
}>;
/**
- * Resumes script execution if the debugger is paused.
+ * Resumes script execution. Throws if the debugger is not paused.
*/
resume(): Promise<void>;
/**
- * Configures the debugger to pause at the next action or at a specific source location. Call without arguments to
- * reset the pausing behavior.
- * @param options
+ * Resumes script execution and pauses when an action originates from the given source location. Throws if the
+ * debugger is not paused.
+ * @param location The source location to pause at.
*/
- setPauseAt(options?: {
- /**
- * When specified, the debugger will pause when the action originates from the given source location.
- */
- location?: {
- file: string;
-
- line?: number;
+ runTo(location: {
+ file: string;
- column?: number;
- };
+ line?: number;
- /**
- * When `true`, the debugger will pause before the next action.
- */
- next?: boolean;
+ column?: number;
}): Promise<void>;
}
diff --git a/packages/playwright/src/mcp/test/browserBackend.ts b/packages/playwright/src/mcp/test/browserBackend.ts
index 36b5cbeba4..0b3ac3718e 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.setPauseAt({ next: true });
+ await context.debugger.pause();
return true;
}
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index 1af10f89a8..d205475ae7 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -4322,8 +4322,10 @@ export interface DebuggerEventTarget {
}
export interface DebuggerChannel extends DebuggerEventTarget, EventTargetChannel {
_type_Debugger: boolean;
- setPauseAt(params: DebuggerSetPauseAtParams, progress?: Progress): Promise<DebuggerSetPauseAtResult>;
+ pause(params?: DebuggerPauseParams, progress?: Progress): Promise<DebuggerPauseResult>;
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: {
@@ -4335,26 +4337,26 @@ export type DebuggerPausedStateChangedEvent = {
title: string,
}[],
};
-export type DebuggerSetPauseAtParams = {
- next?: boolean,
- location?: {
+export type DebuggerPauseParams = {};
+export type DebuggerPauseOptions = {};
+export type DebuggerPauseResult = void;
+export type DebuggerResumeParams = {};
+export type DebuggerResumeOptions = {};
+export type DebuggerResumeResult = void;
+export type DebuggerNextParams = {};
+export type DebuggerNextOptions = {};
+export type DebuggerNextResult = void;
+export type DebuggerRunToParams = {
+ location: {
file: string,
line?: number,
column?: number,
},
};
-export type DebuggerSetPauseAtOptions = {
- next?: boolean,
- location?: {
- file: string,
- line?: number,
- column?: number,
- },
+export type DebuggerRunToOptions = {
+
};
-export type DebuggerSetPauseAtResult = void;
-export type DebuggerResumeParams = {};
-export type DebuggerResumeOptions = {};
-export type DebuggerResumeResult = void;
+export type DebuggerRunToResult = void;
export interface DebuggerEvents {
'pausedStateChanged': DebuggerPausedStateChangedEvent;
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index f037fa3312..c7f20e761a 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -3804,22 +3804,29 @@ Debugger:
commands:
- setPauseAt:
- title: Configure pause behavior
+ pause:
+ title: Pause on next call
+ group: configuration
+
+ resume:
+ title: Resume
+ group: configuration
+
+ next:
+ title: Step to next call
+ group: configuration
+
+ runTo:
+ title: Run to location
group: configuration
parameters:
- next: boolean?
location:
- type: object?
+ type: object
properties:
file: string
line: int?
column: int?
- resume:
- title: Resume
- group: configuration
-
events:
pausedStateChanged:
diff --git a/tests/library/debugger.spec.ts b/tests/library/debugger.spec.ts
index 65d460cc50..bf04c2365a 100644
--- a/tests/library/debugger.spec.ts
+++ b/tests/library/debugger.spec.ts
@@ -22,7 +22,7 @@ it('should pause at next and resume', async ({ context, server }) => {
const dbg = context.debugger;
expect(dbg.pausedDetails()).toEqual([]);
- await dbg.setPauseAt({ next: true });
+ await dbg.pause();
const clickPromise = page.click('div');
await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));
@@ -51,7 +51,7 @@ it('should pause at pause call', async ({ context, server }) => {
const dbg = context.debugger;
expect(dbg.pausedDetails()).toEqual([]);
- await dbg.setPauseAt();
+ await dbg.pause();
const pausePromise = page.pause();
await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));
@@ -65,15 +65,21 @@ it('should pause at pause call', async ({ context, server }) => {
await pausePromise;
});
-it('should pause at location', async ({ context, server }) => {
+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([]);
+ // First, pause on next action.
+ await dbg.pause();
+ page.click('div').catch(() => {});
+ await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));
+
+ // Now run to a specific location.
const line = +(() => { return new Error('').stack.match(/debugger.spec.ts:(\d+)/)[1]; })();
// Note: careful with the line offset below.
- await dbg.setPauseAt({ location: { file: 'debugger.spec', line: line + 4 } });
+ await dbg.runTo({ file: 'debugger.spec', line: line + 4 });
await page.content(); // should not pause here
const clickPromise = page.click('div'); // should pause here
await new Promise<void>(resolve => dbg.once('pausedstatechanged', resolve));
diff --git a/tests/playwright-test/playwright.spec.ts b/tests/playwright-test/playwright.spec.ts
index 1d2fd3b665..668b5a1567 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.setPauseAt({ next: true });
+ await context.debugger.pause();
const paused = new Promise(f => context.debugger.once('pausedstatechanged', f));
const contentPromise = page.setContent('<div>hello</div>');
await paused;