chore: update debugger api

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.

packages/playwright-client/types/types.d.ts

@@ -19418,9 +19418,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 {
   /**
@@ -19453,6 +19450,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.
    */
@@ -19469,31 +19485,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>;
 }
 

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;
   }

packages/playwright-core/src/protocol/validator.ts

@@ -2508,17 +2508,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,

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)

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();
   }
 }

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;
   },
 });

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', }],

packages/playwright-core/types/types.d.ts

@@ -19418,9 +19418,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 {
   /**
@@ -19453,6 +19450,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.
    */
@@ -19469,31 +19485,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>;
 }
 

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;
 }