feat(extension): allow disabling controlled tab groups (#43814)

Co-authored-by: microsoft-playwright-automation[bot] <203992400+microsoft-playwright-automation[bot]@users.noreply.github.com>

Author: microsoft-playwright-automation[bot]

packages/extension/README.md

@@ -42,6 +42,8 @@ When the LLM interacts with the browser for the first time, it will load a page
 
 Several clients can be connected at the same time. Each one gets its own tab group, named after the client and colored apart from the other groups, and only sees the tabs in that group — a tab can belong to a single client at a time. Drag tabs in and out of a group to change what a client can reach, and use the extension's status page to see every connection and disconnect them individually.
 
+To disable automatic grouping, pass `--no-tab-group` alongside `--extension`, or set `PLAYWRIGHT_MCP_NO_TAB_GROUP=1`. Grouping stays enabled by default. With grouping disabled, the selected tab and tabs opened by the client stay in their existing groups, if any. This does not grant access to all existing tabs or change connection approval; each controlled tab still belongs to only one client. Use the status page to see controlled tabs and disconnect clients.
+
 ### Bypassing the Connection Approval Dialog
 
 By default, you'll need to approve each connection when the MCP server tries to connect to your browser. To bypass this approval dialog and allow automatic connections, you can use an authentication token.
@@ -93,4 +95,3 @@ If the extension is installed in several Chrome profiles, the connection is made
 
 The `PLAYWRIGHT_MCP_PROFILE_DIR_NAME` environment variable can be used instead of the option. The authentication token is specific to the profile, so use the one displayed in that profile.
 
-

packages/extension/src/background.ts

@@ -29,6 +29,7 @@ type PageMessage = {
   // selection happens.
   tab?: chrome.tabs.Tab;
   clientName?: string;
+  tabGroup?: boolean;
 } | {
   type: 'getConnectionStatus';
 } | {
@@ -74,7 +75,7 @@ class PlaywrightExtension {
         // sender.tab and UI-supplied tabs come from chrome.tabs.query / runtime
         // message sender, where `id` is always defined.
         const selectedTab = (message.tab ?? sender.tab!) as chrome.tabs.Tab & { id: number };
-        this._connectTab(sender.tab!.id!, selectedTab, message.clientName).then(
+        this._connectTab(sender.tab!.id!, selectedTab, message.clientName, message.tabGroup !== false).then(
             () => sendResponse({ success: true }),
             (error: any) => sendResponse({ success: false, error: error.message }));
         return true; // Return true to indicate that the response will be sent asynchronously
@@ -99,7 +100,7 @@ class PlaywrightExtension {
     }
   }
 
-  private async _connectTab(selectorTabId: number, tab: chrome.tabs.Tab & { id: number }, clientName: string | undefined): Promise<void> {
+  private async _connectTab(selectorTabId: number, tab: chrome.tabs.Tab & { id: number }, clientName: string | undefined, tabGroup: boolean): Promise<void> {
     try {
       await this._cleanupPromise;
       this._releaseTab(selectorTabId);
@@ -111,8 +112,8 @@ class PlaywrightExtension {
         throw new Error('Pending client connection closed');
 
       const id = ++this._lastConnectionId;
-      const taken = [...this._connections.values()].map(group => group.groupStyle);
-      const group = new ConnectedTabGroup(connection, tab, clientName, uniqueGroupStyle(clientName, taken), tabId => this._pendingConnections.has(tabId));
+      const taken = [...this._connections.values()].flatMap(group => group.groupStyle ? [group.groupStyle] : []);
+      const group = new ConnectedTabGroup(connection, tab, clientName, tabGroup ? uniqueGroupStyle(clientName, taken) : undefined, tabId => this._pendingConnections.has(tabId));
       group.onclose = () => this._connections.delete(id);
       this._connections.set(id, group);
 

packages/extension/src/connectedTabGroup.ts

@@ -61,17 +61,17 @@ export async function cleanupStalePlaywrightGroups(): Promise<void> {
   }
 }
 
-// The Playwright tab group for an active RelayConnection. The Chrome tab group
-// is the single source of truth for which tabs the client targets:
+// The controlled tabs for an active RelayConnection. When grouping is enabled,
+// the Chrome tab group is the single source of truth for which tabs the client targets:
 //  - User drags a tab in/out → `_onTabGroupChanged` attaches/detaches.
 //  - Relay attaches on its own (initial tab, popup, Target.createTarget) →
 //    `_onTabAttached` pulls the new tab into the group, whose onUpdated event
 //    flows back through `_onTabGroupChanged` for consistency.
-// `_groupTabIds` caches group membership from Chrome events so hot-path checks
-// in `_onTabUpdated` stay synchronous.
+// `_groupTabIds` tracks controlled tabs, caching group membership from Chrome
+// events when grouping is enabled.
 export class ConnectedTabGroup {
   readonly clientName: string | undefined;
-  readonly groupStyle: GroupStyle;
+  readonly groupStyle: GroupStyle | undefined;
   private _connection: RelayConnection;
   private _isTabReserved: (tabId: number) => boolean;
   private _groupId: number | null = null;
@@ -81,7 +81,7 @@ export class ConnectedTabGroup {
 
   onclose?: () => void;
 
-  constructor(connection: RelayConnection, selectedTab: chrome.tabs.Tab, clientName: string | undefined, groupStyle: GroupStyle, isTabReserved: (tabId: number) => boolean) {
+  constructor(connection: RelayConnection, selectedTab: chrome.tabs.Tab, clientName: string | undefined, groupStyle: GroupStyle | undefined, isTabReserved: (tabId: number) => boolean) {
     this.clientName = clientName;
     this.groupStyle = groupStyle;
     this._isTabReserved = isTabReserved;
@@ -117,7 +117,7 @@ export class ConnectedTabGroup {
   }
 
   private _onTabUpdated(tabId: number, changeInfo: chrome.tabs.OnUpdatedInfo, tab: chrome.tabs.Tab): void {
-    if (changeInfo.groupId !== undefined)
+    if (this.groupStyle && changeInfo.groupId !== undefined)
       this._onTabGroupChanged(tabId, tab);
     if (changeInfo.url === undefined)
       return;
@@ -160,13 +160,18 @@ export class ConnectedTabGroup {
 
   private _onTabAttached(tabId: number): void {
     void this._updateBadge(tabId, CONNECTED_BADGE);
-    void this._addTabToGroup(tabId);
+    if (this.groupStyle)
+      void this._addTabToGroup(tabId);
+    else
+      this._groupTabIds.add(tabId);
   }
 
   // The debugger detached (drag-out, tab close, or external action). Clear the
   // badge but leave the tab in the group — the user's intent is still there,
   // and a subsequent navigation will re-attach via _onTabUpdated.
   private _onTabDetached(tabId: number): void {
+    if (!this.groupStyle)
+      this._groupTabIds.delete(tabId);
     void this._updateBadge(tabId, { text: '' });
   }
 
@@ -175,7 +180,7 @@ export class ConnectedTabGroup {
     chrome.tabs.onRemoved.removeListener(this._onTabRemovedListener);
     const groupTabs = [...this._groupTabIds];
     this._groupTabIds.clear();
-    if (groupTabs.length)
+    if (this.groupStyle && groupTabs.length)
       void ungroupTabs(groupTabs);
     this.onclose?.();
   }
@@ -197,13 +202,14 @@ export class ConnectedTabGroup {
   // that arrives concurrently (`_groupId` still null, wasInGroup still false)
   // becomes a harmless no-op rather than taking the drag-out branch.
   private async _addTabToGroup(tabId: number): Promise<void> {
-    if (this._groupTabIds.has(tabId))
+    const groupStyle = this.groupStyle;
+    if (!groupStyle || this._groupTabIds.has(tabId))
       return;
     try {
       await retryOnDrag(async () => {
         if (this._groupId === null) {
           this._groupId = await chrome.tabs.group({ tabIds: [tabId] });
-          await chrome.tabGroups.update(this._groupId, this.groupStyle);
+          await chrome.tabGroups.update(this._groupId, groupStyle);
         } else {
           await chrome.tabs.group({ groupId: this._groupId, tabIds: [tabId] });
         }

packages/extension/src/ui/connect.tsx

@@ -26,6 +26,7 @@ type Status =
   | { type: 'error'; versionMismatch: { extensionVersion: string; } };
 
 const SUPPORTED_PROTOCOL_VERSION = 2;
+const tabGroup = new URLSearchParams(window.location.search).get('tabGroup') !== 'false';
 
 // Client name comes from the URL and never changes for the lifetime of this page.
 const clientInfo = (() => {
@@ -142,6 +143,7 @@ const ConnectApp: React.FC = () => {
         type: 'connectToTab',
         tab,
         clientName: clientInfo,
+        tabGroup,
       });
 
       if (response?.success) {
@@ -185,7 +187,7 @@ const ConnectApp: React.FC = () => {
         {showTabList && (
           <div>
             <div className='tab-section-title'>
-              You can drag tabs into the Playwright group later to make them accessible to the client.
+              {tabGroup && <>You can drag tabs into the Playwright group later to make them accessible to the client. </>}
               Optionally, select a tab to allow and immediately switch to it:
             </div>
             <div>

packages/playwright-core/src/tools/mcp/browserFactory.ts

@@ -76,7 +76,7 @@ async function createBrowser(config: FullConfig, clientInfo: ClientInfo, cliOpti
     ownership = 'own';
   } else if (config.extension) {
     const { channel, executablePath, profileDirName } = resolveExtensionOptions(cliOptions);
-    browser = await createExtensionBrowser(channel, executablePath, config.browser.userDataDir, profileDirName, clientInfo.clientName);
+    browser = await createExtensionBrowser(channel, executablePath, config.browser.userDataDir, profileDirName, clientInfo.clientName, config.tabGroup);
     ownership = 'attached';
   } else {
     browser = await createPersistentBrowser(config, clientInfo);

packages/playwright-core/src/tools/mcp/cdpRelay.ts

@@ -128,9 +128,9 @@ export class CDPRelayServer {
     return `${this._wsHost}${this._extensionPath}`;
   }
 
-  async establishExtensionConnection(clientName: string) {
+  async establishExtensionConnection(clientName: string, tabGroup = true) {
     debugLogger('Establishing extension connection');
-    await this._openConnectPageInBrowser(clientName);
+    await this._openConnectPageInBrowser(clientName, tabGroup);
     debugLogger('Waiting for incoming extension connection');
     // Without a token the user has to approve the connection in the browser, which can take arbitrarily long.
     const deadline = this._token ? monotonicTime() + extensionConnectionTimeout : 0;
@@ -145,7 +145,7 @@ export class CDPRelayServer {
     debugLogger('Extension connection established');
   }
 
-  private async _openConnectPageInBrowser(clientName: string) {
+  private async _openConnectPageInBrowser(clientName: string, tabGroup: boolean) {
     const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
     const url = new URL(`chrome-extension://${playwrightExtensionId}/connect.html`);
     url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
@@ -156,6 +156,8 @@ export class CDPRelayServer {
     };
     url.searchParams.set('client', JSON.stringify(client));
     url.searchParams.set('protocolVersion', this._protocolVersion.toString());
+    if (!tabGroup)
+      url.searchParams.set('tabGroup', 'false');
     if (this._token)
       url.searchParams.set('token', this._token);
     const href = url.toString();

packages/playwright-core/src/tools/mcp/config.d.ts

@@ -109,6 +109,11 @@ export type Config = {
    */
   extension?: boolean;
 
+  /**
+   * Group controlled tabs when using the extension. Defaults to true.
+   */
+  tabGroup?: boolean;
+
   server?: {
     /**
      * The port to listen on for SSE or MCP transport.

packages/playwright-core/src/tools/mcp/config.ts

@@ -78,6 +78,7 @@ export type CLIOptions = {
   snapshotBoxes?: boolean;
   snapshotMode?: 'full' | 'none';
   storageState?: string;
+  tabGroup?: boolean;
   testIdAttribute?: string;
   timeoutAction?: number;
   timeoutNavigation?: number;
@@ -373,6 +374,7 @@ function configFromCLIOptions(cliOptions: CLIOptions): Config & { configFile?: s
       remoteEndpoint: cliOptions.endpoint,
     },
     extension: cliOptions.extension,
+    tabGroup: cliOptions.tabGroup === false ? false : undefined,
     server: {
       port: cliOptions.port,
       host: cliOptions.host,
@@ -476,7 +478,11 @@ export function configFromEnv(env?: NodeJS.ProcessEnv): Config & { configFile?:
   options.webmcp = envToBoolean(e.PLAYWRIGHT_MCP_WEBMCP);
   options.userDataDir = envToString(e.PLAYWRIGHT_MCP_USER_DATA_DIR);
   options.viewportSize = resolutionParser('--viewport-size', e.PLAYWRIGHT_MCP_VIEWPORT_SIZE);
-  return configFromCLIOptions(options);
+  const config = configFromCLIOptions(options);
+  const noTabGroup = envToBoolean(e.PLAYWRIGHT_MCP_NO_TAB_GROUP);
+  if (noTabGroup !== undefined)
+    config.tabGroup = !noTabGroup;
+  return config;
 }
 
 export async function loadConfig(configFile: string | undefined): Promise<Config> {

packages/playwright-core/src/tools/mcp/configIni.ts

@@ -155,6 +155,7 @@ const longhandTypes: Record<string, LonghandType> = {
 
   // top-level
   'extension': 'boolean',
+  'tabGroup': 'boolean',
   'capabilities': 'string[]',
   'saveSession': 'boolean',
   'saveVideo': 'size',

packages/playwright-core/src/tools/mcp/extensionContextFactory.ts

@@ -26,7 +26,7 @@ import type * as playwrightTypes from '../../..';
 
 const debugLogger = debug('pw:mcp:relay');
 
-export async function createExtensionBrowser(channel: string, executablePath: string | undefined, customUserDataDir: string | undefined, profileDirName: string | undefined, clientName: string): Promise<playwrightTypes.Browser> {
+export async function createExtensionBrowser(channel: string, executablePath: string | undefined, customUserDataDir: string | undefined, profileDirName: string | undefined, clientName: string, tabGroup = true): Promise<playwrightTypes.Browser> {
   customUserDataDir ??= process.env.PWTEST_EXTENSION_USER_DATA_DIR;
   // Custom executablePath may target a browser in a different filesystem (e.g. Windows chrome.exe from WSL2), so the local profile path is not meaningful.
   const userDataDir = customUserDataDir ?? (executablePath ? undefined : defaultUserDataDirForChannel(channel));
@@ -39,7 +39,7 @@ export async function createExtensionBrowser(channel: string, executablePath: st
   debugLogger(`CDP relay server started, extension endpoint: ${relay.extensionEndpoint()}.`);
 
   try {
-    await relay.establishExtensionConnection(clientName);
+    await relay.establishExtensionConnection(clientName, tabGroup);
     const browser = await playwright.chromium.connectOverCDP(relay.cdpEndpoint(), { isLocal: true, timeout: 0, noDefaults: true });
     browser.on('disconnected', () => relay.stop());
     return browser;