chore: brush up the debug controller api (#18262)

packages/playwright-core/src/cli/driver.ts

@@ -83,7 +83,7 @@ class ProtocolHandler {
   constructor(playwright: Playwright) {
     this._controller = playwright.debugController;
     this._controller.setAutoCloseAllowed(true);
-    this._controller.setTrackHierarcy(true);
+    this._controller.setReportStateChanged(true);
     this._controller.on(DebugController.Events.BrowsersChanged, browsers => {
       process.send!({ method: 'browsersChanged', params: { browsers } });
     });

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

@@ -336,6 +336,9 @@ scheme.DebugControllerInspectRequestedEvent = tObject({
   selector: tString,
   locators: tArray(tType('NameValue')),
 });
+scheme.DebugControllerStateChangedEvent = tObject({
+  pageCount: tNumber,
+});
 scheme.DebugControllerBrowsersChangedEvent = tObject({
   browsers: tArray(tObject({
     contexts: tArray(tObject({
@@ -346,10 +349,10 @@ scheme.DebugControllerBrowsersChangedEvent = tObject({
 scheme.DebugControllerSourcesChangedEvent = tObject({
   sources: tArray(tType('RecorderSource')),
 });
-scheme.DebugControllerSetTrackHierarchyParams = tObject({
+scheme.DebugControllerSetReportStateChangedParams = tObject({
   enabled: tBoolean,
 });
-scheme.DebugControllerSetTrackHierarchyResult = tOptional(tObject({}));
+scheme.DebugControllerSetReportStateChangedResult = tOptional(tObject({}));
 scheme.DebugControllerResetForReuseParams = tOptional(tObject({}));
 scheme.DebugControllerResetForReuseResult = tOptional(tObject({}));
 scheme.DebugControllerNavigateAllParams = tObject({

packages/playwright-core/src/server/debugController.ts

@@ -32,6 +32,7 @@ const internalMetadata = serverSideCallMetadata();
 export class DebugController extends SdkObject {
   static Events = {
     BrowsersChanged: 'browsersChanged',
+    StateChanged: 'stateChanged',
     InspectRequested: 'inspectRequested',
     SourcesChanged: 'sourcesChanged',
   };
@@ -53,11 +54,11 @@ export class DebugController extends SdkObject {
   }
 
   dispose() {
-    this.setTrackHierarcy(false);
+    this.setReportStateChanged(false);
     this.setAutoCloseAllowed(false);
   }
 
-  setTrackHierarcy(enabled: boolean) {
+  setReportStateChanged(enabled: boolean) {
     if (enabled && !this._trackHierarchyListener) {
       this._trackHierarchyListener = {
         onPageOpen: () => this._emitSnapshot(),
@@ -154,6 +155,7 @@ export class DebugController extends SdkObject {
 
   private _emitSnapshot() {
     const browsers = [];
+    let pageCount = 0;
     for (const browser of this._playwright.allBrowsers()) {
       const b = {
         contexts: [] as any[]
@@ -166,9 +168,12 @@ export class DebugController extends SdkObject {
         b.contexts.push(c);
         for (const page of context.pages())
           c.pages.push(page.mainFrame().url());
+        pageCount += context.pages().length;
       }
     }
+    // TODO: browsers is deprecated, remove it.
     this.emit(DebugController.Events.BrowsersChanged, browsers);
+    this.emit(DebugController.Events.StateChanged, { pageCount });
   }
 
   private async _allRecorders(): Promise<Recorder[]> {

packages/playwright-core/src/server/dispatchers/debugControllerDispatcher.ts

@@ -25,8 +25,8 @@ export class DebugControllerDispatcher extends Dispatcher<DebugController, chann
   constructor(connection: DispatcherConnection, debugController: DebugController) {
     super(connection, debugController, 'DebugController', {});
     this._type_DebugController = true;
-    this._object.on(DebugController.Events.BrowsersChanged, browsers => {
+    this._object.on(DebugController.Events.StateChanged, params => {
-      this._dispatchEvent('browsersChanged', { browsers });
+      this._dispatchEvent('stateChanged', params);
     });
     this._object.on(DebugController.Events.InspectRequested, ({ selector, locators }) => {
       this._dispatchEvent('inspectRequested', { selector, locators });
@@ -36,8 +36,8 @@ export class DebugControllerDispatcher extends Dispatcher<DebugController, chann
     });
   }
 
-  async setTrackHierarchy(params: channels.DebugControllerSetTrackHierarchyParams) {
+  async setReportStateChanged(params: channels.DebugControllerSetReportStateChangedParams) {
-    this._object.setTrackHierarcy(params.enabled);
+    this._object.setReportStateChanged(params.enabled);
   }
 
   async resetForReuse() {

packages/protocol/src/channels.ts

@@ -593,12 +593,13 @@ export type RecorderSource = {
 export type DebugControllerInitializer = {};
 export interface DebugControllerEventTarget {
   on(event: 'inspectRequested', callback: (params: DebugControllerInspectRequestedEvent) => void): this;
+  on(event: 'stateChanged', callback: (params: DebugControllerStateChangedEvent) => void): this;
   on(event: 'browsersChanged', callback: (params: DebugControllerBrowsersChangedEvent) => void): this;
   on(event: 'sourcesChanged', callback: (params: DebugControllerSourcesChangedEvent) => void): this;
 }
 export interface DebugControllerChannel extends DebugControllerEventTarget, Channel {
   _type_DebugController: boolean;
-  setTrackHierarchy(params: DebugControllerSetTrackHierarchyParams, metadata?: Metadata): Promise<DebugControllerSetTrackHierarchyResult>;
+  setReportStateChanged(params: DebugControllerSetReportStateChangedParams, metadata?: Metadata): Promise<DebugControllerSetReportStateChangedResult>;
   resetForReuse(params?: DebugControllerResetForReuseParams, metadata?: Metadata): Promise<DebugControllerResetForReuseResult>;
   navigateAll(params: DebugControllerNavigateAllParams, metadata?: Metadata): Promise<DebugControllerNavigateAllResult>;
   setRecorderMode(params: DebugControllerSetRecorderModeParams, metadata?: Metadata): Promise<DebugControllerSetRecorderModeResult>;
@@ -611,6 +612,9 @@ export type DebugControllerInspectRequestedEvent = {
   selector: string,
   locators: NameValue[],
 };
+export type DebugControllerStateChangedEvent = {
+  pageCount: number,
+};
 export type DebugControllerBrowsersChangedEvent = {
   browsers: {
     contexts: {
@@ -621,13 +625,13 @@ export type DebugControllerBrowsersChangedEvent = {
 export type DebugControllerSourcesChangedEvent = {
   sources: RecorderSource[],
 };
-export type DebugControllerSetTrackHierarchyParams = {
+export type DebugControllerSetReportStateChangedParams = {
   enabled: boolean,
 };
-export type DebugControllerSetTrackHierarchyOptions = {
+export type DebugControllerSetReportStateChangedOptions = {
 
 };
-export type DebugControllerSetTrackHierarchyResult = void;
+export type DebugControllerSetReportStateChangedResult = void;
 export type DebugControllerResetForReuseParams = {};
 export type DebugControllerResetForReuseOptions = {};
 export type DebugControllerResetForReuseResult = void;
@@ -667,6 +671,7 @@ export type DebugControllerCloseAllBrowsersResult = void;
 
 export interface DebugControllerEvents {
   'inspectRequested': DebugControllerInspectRequestedEvent;
+  'stateChanged': DebugControllerStateChangedEvent;
   'browsersChanged': DebugControllerBrowsersChangedEvent;
   'sourcesChanged': DebugControllerSourcesChangedEvent;
 }

packages/protocol/src/protocol.yml

@@ -660,7 +660,7 @@ DebugController:
   type: interface
 
   commands:
-    setTrackHierarchy:
+    setReportStateChanged:
       parameters:
         enabled: boolean
 
@@ -699,6 +699,11 @@ DebugController:
           type: array
           items: NameValue
 
+    stateChanged:
+      parameters:
+        pageCount: number
+
+    # Deprecated
     browsersChanged:
       parameters:
         browsers: