Skip to content

Chrome DevTools for coding agents

refactor: extract worker logic into McpWorker (#2800)

Gunjan Jaswal77165c638284
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 1bb7bc8e..448bd41b 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -47,7 +47,7 @@ import type {
} from './tools/ToolDefinition.js';
import type {TraceResult} from './processors/PerformanceTrace.js';
import type {Logger} from './types.js';
-import type {ExtensionServiceWorker} from './types.js';
+import {McpWorker} from './McpWorker.js';
import {getTempFilePath, resolveCanonicalPath} from './utils/files.js';
import {escapeForLog} from './utils/logger.js';
import {isAllowedUrl} from './utils/url.js';
@@ -94,7 +94,9 @@ export class McpContext implements Context {
// Auto-generated name counter for when no name is provided.
#nextIsolatedContextId = 1;
- #extensionServiceWorkers: ExtensionServiceWorker[] = [];
+ // Cached McpWorker per target, reused across snapshots (mirrors #mcpPages) so
+ // referential identity holds and workers can carry per-worker state later.
+ #workers = new Map<Target, McpWorker>();
#mcpPages = new Map<Target, McpPage>();
#selectedPage?: McpPage;
@@ -108,9 +110,6 @@ export class McpContext implements Context {
#reconnectNotice = false;
- #extensionServiceWorkerMap = new WeakMap<Target, string>();
- #nextExtensionServiceWorkerId = 1;
-
#traceResults: TraceResult[] = [];
#locatorClass: typeof Locator;
@@ -145,7 +144,7 @@ export class McpContext implements Context {
async #init() {
await this.createPagesSnapshot();
- const workers = await this.createExtensionServiceWorkersSnapshot();
+ const workers = this.createWorkersSnapshot();
await this.#serviceWorkerConsoleCollector.init(workers);
this.browser.on('targetcreated', this.#onTargetCreated);
@@ -163,6 +162,7 @@ export class McpContext implements Context {
}
this.#selectedPage?.dispose();
this.#mcpPages.clear();
+ this.#workers.clear();
// Isolated contexts are intentionally not closed here.
// Either the entire browser will be closed or we disconnect
// without destroying browser state.
@@ -187,6 +187,7 @@ export class McpContext implements Context {
mcpPage.dispose();
this.#mcpPages.delete(target);
}
+ this.#workers.delete(target);
} catch (err) {
this.logger?.('Error handling targetdestroyed', err);
}
@@ -208,6 +209,10 @@ export class McpContext implements Context {
nextPageId = 1;
}
+ static resetWorkerIdsForTesting(): void {
+ McpWorker.resetIdsForTesting();
+ }
+
roots(): Root[] {
return [
...(this.#roots ?? []),
@@ -487,38 +492,35 @@ export class McpContext implements Context {
}
/**
- * Creates a snapshot of the extension service workers.
+ * Creates a snapshot of the tracked workers. Today this is limited to
+ * extension service workers; the McpWorker abstraction lets dedicated and
+ * shared workers join the same snapshot later without changing consumers.
*/
- async createExtensionServiceWorkersSnapshot(): Promise<
- ExtensionServiceWorker[]
- > {
- const allTargets = this.browser.targets();
-
- const serviceWorkers = allTargets.filter(target => {
+ createWorkersSnapshot(): McpWorker[] {
+ const serviceWorkers = this.browser.targets().filter(target => {
return (
target.type() === 'service_worker' &&
target.url().includes('chrome-extension://')
);
});
- for (const serviceWorker of serviceWorkers) {
- if (!this.#extensionServiceWorkerMap.has(serviceWorker)) {
- this.#extensionServiceWorkerMap.set(
- serviceWorker,
- 'sw-' + this.#nextExtensionServiceWorkerId++,
- );
+ // Reuse the existing McpWorker for a target; only mint one (and an id) for
+ // targets seen for the first time.
+ for (const target of serviceWorkers) {
+ if (!this.#workers.has(target)) {
+ this.#workers.set(target, McpWorker.create('service_worker', target));
}
}
- this.#extensionServiceWorkers = serviceWorkers.map(serviceWorker => {
- return {
- target: serviceWorker,
- id: this.#extensionServiceWorkerMap.get(serviceWorker)!,
- url: serviceWorker.url(),
- };
- });
+ // Prune workers whose target is gone (mirrors #mcpPages pruning).
+ const currentTargets = new Set(serviceWorkers);
+ for (const target of this.#workers.keys()) {
+ if (!currentTargets.has(target)) {
+ this.#workers.delete(target);
+ }
+ }
- return this.#extensionServiceWorkers;
+ return Array.from(this.#workers.values());
}
getServiceWorkerConsoleData(
@@ -649,14 +651,12 @@ export class McpContext implements Context {
return this.browser.targets().filter(target => this.#isPageTarget(target));
}
- getExtensionServiceWorkers(): ExtensionServiceWorker[] {
- return this.#extensionServiceWorkers;
+ getWorkers(): McpWorker[] {
+ return Array.from(this.#workers.values());
}
- getExtensionServiceWorkerId(
- extensionServiceWorker: ExtensionServiceWorker,
- ): string | undefined {
- return this.#extensionServiceWorkerMap.get(extensionServiceWorker.target);
+ getWorkerById(id: string): McpWorker | undefined {
+ return this.#workers.values().find(worker => worker.id === id);
}
async #writeFile(
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
index 74553e8a..3a9ff611 100644
--- a/src/McpResponse.ts
+++ b/src/McpResponse.ts
@@ -190,6 +190,10 @@ export class McpResponse implements Response {
}
}
+ setIncludeExtensionServiceWorkers(value: boolean): void {
+ this.#includeExtensionServiceWorkers = value;
+ }
+
includeSnapshot(params?: SnapshotParams): void {
this.#snapshotParams = params ?? {
verbose: false,
@@ -765,7 +769,7 @@ export class McpResponse implements Response {
]);
if (this.#includeExtensionServiceWorkers) {
- await context.createExtensionServiceWorkersSnapshot();
+ context.createWorkersSnapshot();
}
let extensions: Map<string, Extension> | undefined;
@@ -1068,23 +1072,27 @@ Call ${handleDialog(this.#args).name} to handle it before continuing.`);
}
if (this.#includeExtensionServiceWorkers) {
- if (context.getExtensionServiceWorkers().length) {
+ const extensionServiceWorkers = context
+ .getWorkers()
+ .filter(worker => worker.type === 'service_worker');
+
+ if (extensionServiceWorkers.length) {
response.push(`## Extension Service Workers`);
}
- for (const extensionServiceWorker of context.getExtensionServiceWorkers()) {
+ for (const extensionServiceWorker of extensionServiceWorkers) {
response.push(
`${extensionServiceWorker.id}: ${extensionServiceWorker.url}`,
);
}
- structuredContent.extensionServiceWorkers = context
- .getExtensionServiceWorkers()
- .map(extensionServiceWorker => {
+ structuredContent.extensionServiceWorkers = extensionServiceWorkers.map(
+ extensionServiceWorker => {
return {
id: extensionServiceWorker.id,
url: extensionServiceWorker.url,
};
- });
+ },
+ );
}
if (this.#tabId) {
diff --git a/src/McpWorker.ts b/src/McpWorker.ts
new file mode 100644
index 00000000..1e125bec
--- /dev/null
+++ b/src/McpWorker.ts
@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Target, WebWorker} from './third_party/index.js';
+
+/**
+ * The kinds of worker target the browser exposes. Only `service_worker` is
+ * surfaced today; the others let the abstraction cover dedicated and shared
+ * workers without changing shape.
+ */
+export type WorkerType =
+ 'service_worker' | 'dedicated_worker' | 'shared_worker';
+
+/**
+ * Short id prefix that labels a worker's type in its id, e.g. `sw-1` for a
+ * service worker. The numeric part comes from a single shared counter, so the
+ * prefix is a readable type tag rather than a per-type sequence.
+ */
+const WORKER_ID_PREFIX: Record<WorkerType, string> = {
+ service_worker: 'sw',
+ dedicated_worker: 'dw',
+ shared_worker: 'shw',
+};
+
+export function workerIdPrefix(type: WorkerType): string {
+ return WORKER_ID_PREFIX[type];
+}
+
+// Single shared counter across worker types. Ids are not reused across
+// reconnects, mirroring the page id counter in McpContext; the type prefix is
+// what distinguishes the kinds, not a per-type sequence.
+let nextWorkerId = 1;
+
+/**
+ * Wraps a Puppeteer worker {@link Target}, mirroring {@link McpPage}: it owns the
+ * target and the stable id assigned to it and lazily resolves the underlying
+ * {@link WebWorker}. Generalizes the former plain `ExtensionServiceWorker` type so
+ * dedicated and service workers share a single representation.
+ */
+export class McpWorker {
+ readonly id: string;
+ readonly type: WorkerType;
+ #target: Target;
+
+ constructor(id: string, type: WorkerType, target: Target) {
+ this.id = id;
+ this.type = type;
+ this.#target = target;
+ }
+
+ /**
+ * Creates a worker with a freshly minted id derived from its type (e.g.
+ * `sw-1`). Keeps id composition in one place so callers only supply the type.
+ */
+ static create(type: WorkerType, target: Target): McpWorker {
+ return new McpWorker(
+ `${workerIdPrefix(type)}-${nextWorkerId++}`,
+ type,
+ target,
+ );
+ }
+
+ /**
+ * Resets the shared id counter. For tests only, mirroring
+ * McpContext.resetPageIdsForTesting().
+ */
+ static resetIdsForTesting(): void {
+ nextWorkerId = 1;
+ }
+
+ get target(): Target {
+ return this.#target;
+ }
+
+ get url(): string {
+ return this.#target.url();
+ }
+
+ /**
+ * Resolves the worker's execution context, or `undefined` when the target
+ * does not expose one (e.g. it closed before the session attached).
+ */
+ async worker(): Promise<WebWorker | undefined> {
+ return (await this.#target.worker()) ?? undefined;
+ }
+}
diff --git a/src/collectors/ServiceWorkerCollector.ts b/src/collectors/ServiceWorkerCollector.ts
index b1a847f2..bbdd0553 100644
--- a/src/collectors/ServiceWorkerCollector.ts
+++ b/src/collectors/ServiceWorkerCollector.ts
@@ -13,7 +13,7 @@ import type {
Protocol,
Browser,
} from '../third_party/index.js';
-import type {ExtensionServiceWorker} from '../types.js';
+import type {McpWorker} from '../McpWorker.js';
import type {WithSymbolId} from '../utils/id.js';
import {createIdGenerator, stableIdSymbol} from '../utils/id.js';
@@ -81,7 +81,7 @@ export class ServiceWorkerConsoleCollector {
this.#maxLogs = maxLogs;
}
- async init(workers: ExtensionServiceWorker[]) {
+ async init(workers: McpWorker[]) {
if (!this.#browser) {
return;
}
diff --git a/src/third_party/index.ts b/src/third_party/index.ts
index fb20d7c8..5aa71302 100644
--- a/src/third_party/index.ts
+++ b/src/third_party/index.ts
@@ -54,6 +54,7 @@ export {
Target,
TargetType,
TimeoutError,
+ WebWorker,
} from 'puppeteer-core';
export {default as puppeteer} from 'puppeteer-core';
export type * from 'puppeteer-core';
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index ec978cdc..99859c54 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -37,9 +37,9 @@ import type {InsightName, TraceResult} from '../processors/PerformanceTrace.js';
import type {
TextSnapshotNode,
GeolocationOptions,
- ExtensionServiceWorker,
CD4ACommentThread,
} from '../types.js';
+import type {McpWorker} from '../McpWorker.js';
import type {PaginationOptions} from '../types.js';
import type {
WaitForEventsResult,
@@ -293,10 +293,8 @@ export type Context = Readonly<{
listExtensions(): Promise<Map<string, Extension>>;
getExtension(id: string): Promise<Extension | undefined>;
getSelectedMcpPage(): McpPage;
- getExtensionServiceWorkers(): ExtensionServiceWorker[];
- getExtensionServiceWorkerId(
- extensionServiceWorker: ExtensionServiceWorker,
- ): string | undefined;
+ getWorkers(): McpWorker[];
+ getWorkerById(id: string): McpWorker | undefined;
getHeapSnapshotAggregates(
filePath: string,
filterName?: string,
diff --git a/src/tools/script.ts b/src/tools/script.ts
index 5f3584c4..3e6e197c 100644
--- a/src/tools/script.ts
+++ b/src/tools/script.ts
@@ -9,7 +9,6 @@ import {pathToFileURL} from 'node:url';
import type {ParsedArguments} from '../config/ConfigParser.js';
import {zod} from '../third_party/index.js';
import type {Frame, JSHandle, Page, WebWorker} from '../third_party/index.js';
-import type {ExtensionServiceWorker} from '../types.js';
import {ToolCategory} from './categories.js';
import type {Context, Response} from './ToolDefinition.js';
@@ -285,22 +284,16 @@ const getWebWorker = async (
context: Context,
serviceWorkerId: string,
): Promise<WebWorker> => {
- const serviceWorkers = context.getExtensionServiceWorkers();
+ const serviceWorker = context.getWorkerById(serviceWorkerId);
- const serviceWorker = serviceWorkers.find(
- (sw: ExtensionServiceWorker) =>
- context.getExtensionServiceWorkerId(sw) === serviceWorkerId,
- );
-
- if (serviceWorker && serviceWorker.target) {
- const worker = await serviceWorker.target.worker();
-
- if (!worker) {
- throw new Error('Service worker target not found.');
- }
-
- return worker;
- } else {
+ if (!serviceWorker || serviceWorker.type !== 'service_worker') {
throw new Error('Service worker not found.');
}
+
+ const worker = await serviceWorker.worker();
+ if (!worker) {
+ throw new Error('Service worker target not found.');
+ }
+
+ return worker;
};
diff --git a/src/types.ts b/src/types.ts
index 8e0d0600..16e4e8d7 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -7,16 +7,9 @@
import type {
SerializedAXNode,
Viewport,
- Target,
DevTools,
} from './third_party/index.js';
-export interface ExtensionServiceWorker {
- url: string;
- target: Target;
- id: string;
-}
-
export interface TextSnapshotNode extends SerializedAXNode {
id: string;
backendNodeId?: number;
diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.ts
index 77c21f08..32ef695d 100644
--- a/tests/McpResponse.test.ts
+++ b/tests/McpResponse.test.ts
@@ -47,6 +47,7 @@ import {
createMockHeapSnapshotStats,
createMockHeapSnapshotStaticData,
createMockMcpContext,
+ createMockMcpWorker,
createMockObjectInfo,
createMockParsedArguments,
} from './mocks.js';
@@ -1594,4 +1595,38 @@ describe('McpResponse heap snapshot formatting', () => {
assert.ok(!text.includes('Context @102'));
assert.ok('heapSnapshotContextAnalysis' in structuredContent);
});
+
+ describe('extension service workers', () => {
+ it('lists only service workers, excluding dedicated and shared workers', async () => {
+ const response = new McpResponse(createMockParsedArguments());
+ response.setIncludeExtensionServiceWorkers(true);
+
+ const context = createMockMcpContext();
+ context.getWorkers.returns([
+ createMockMcpWorker({
+ id: 'sw-1',
+ type: 'service_worker',
+ url: 'chrome-extension://abc/sw.js',
+ }),
+ createMockMcpWorker({id: 'dw-2', type: 'dedicated_worker'}),
+ createMockMcpWorker({id: 'shw-3', type: 'shared_worker'}),
+ ]);
+
+ const {content, structuredContent} = await response.handle(context);
+ const text = getTextContent(content[0]);
+
+ assert.ok(text.includes('## Extension Service Workers'));
+ assert.ok(text.includes('sw-1: chrome-extension://abc/sw.js'));
+ assert.ok(!text.includes('dw-2'));
+ assert.ok(!text.includes('shw-3'));
+ assert.deepEqual(
+ (
+ structuredContent as {
+ extensionServiceWorkers?: Array<{id: string}>;
+ }
+ ).extensionServiceWorkers,
+ [{id: 'sw-1', url: 'chrome-extension://abc/sw.js'}],
+ );
+ });
+ });
});
diff --git a/tests/McpWorker.test.ts b/tests/McpWorker.test.ts
new file mode 100644
index 00000000..1abea573
--- /dev/null
+++ b/tests/McpWorker.test.ts
@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {afterEach, describe, it} from 'node:test';
+
+import sinon from 'sinon';
+
+import {McpWorker, workerIdPrefix} from '../src/McpWorker.js';
+
+import {createMockTarget, createMockWebWorker} from './mocks.js';
+
+describe('McpWorker', () => {
+ afterEach(() => {
+ sinon.restore();
+ });
+
+ it('labels ids by worker type', () => {
+ assert.equal(workerIdPrefix('service_worker'), 'sw');
+ assert.equal(workerIdPrefix('dedicated_worker'), 'dw');
+ assert.equal(workerIdPrefix('shared_worker'), 'shw');
+ });
+
+ it('exposes the id and type it was created with', () => {
+ const worker = new McpWorker('sw-3', 'service_worker', createMockTarget());
+ assert.equal(worker.id, 'sw-3');
+ assert.equal(worker.type, 'service_worker');
+ });
+
+ it('reads url from the target rather than a cached copy', () => {
+ const target = createMockTarget();
+ target.url
+ .onFirstCall()
+ .returns('chrome-extension://abc/first.js')
+ .onSecondCall()
+ .returns('chrome-extension://abc/second.js');
+ const worker = new McpWorker('sw-1', 'service_worker', target);
+ assert.equal(worker.url, 'chrome-extension://abc/first.js');
+ assert.equal(worker.url, 'chrome-extension://abc/second.js');
+ });
+
+ it('coerces a missing worker execution context to undefined', async () => {
+ const target = createMockTarget();
+ target.worker.resolves(null);
+ const worker = new McpWorker('sw-1', 'service_worker', target);
+ assert.equal(await worker.worker(), undefined);
+ });
+
+ it('returns the underlying WebWorker when the target has one', async () => {
+ const webWorker = createMockWebWorker();
+ const target = createMockTarget();
+ target.worker.resolves(webWorker);
+ const worker = new McpWorker('sw-1', 'service_worker', target);
+ assert.equal(await worker.worker(), webWorker);
+ });
+});
diff --git a/tests/mocks.ts b/tests/mocks.ts
index becd2a07..323ca984 100644
--- a/tests/mocks.ts
+++ b/tests/mocks.ts
@@ -32,6 +32,7 @@ import {
import {McpContext} from '../src/McpContext.js';
import {McpPage} from '../src/McpPage.js';
import {McpResponse} from '../src/McpResponse.js';
+import {McpWorker, type WorkerType} from '../src/McpWorker.js';
import type {
AggregatedInfoWithId,
DuplicateStringGroup,
@@ -51,6 +52,7 @@ import {
Locator,
Target,
TargetType,
+ WebWorker,
} from '../src/third_party/index.js';
import type {
Browser,
@@ -59,6 +61,7 @@ import type {
Extension,
Page,
Protocol,
+ Realm,
Result,
RunnerResult,
} from '../src/third_party/index.js';
@@ -321,6 +324,47 @@ export function createMockElementHandle(): {
return {handle, locator};
}
+export function createMockTarget(): sinon.SinonStubbedInstance<MockTarget> {
+ return createMockPuppeteerTarget();
+}
+
+// Concrete subclass of Puppeteer's abstract WebWorker so sinon.createStubInstance
+// can stub it without an `as unknown as` cast, mirroring MockTarget above.
+class MockWebWorker extends WebWorker {
+ mainRealm(): Realm {
+ throw new Error('Not implemented');
+ }
+ get client(): CDPSession {
+ throw new Error('Not implemented');
+ }
+}
+
+export function createMockWebWorker(): sinon.SinonStubbedInstance<MockWebWorker> {
+ return sinon.createStubInstance(MockWebWorker);
+}
+
+export function createMockMcpWorker(
+ options: {
+ id?: string;
+ type?: WorkerType;
+ url?: string;
+ worker?: WebWorker;
+ } = {},
+): McpWorker {
+ // A real McpWorker over a stubbed Target, so `url`/`worker()` resolve through
+ // the same code paths as in production rather than through stubbed getters.
+ const target = createMockTarget();
+ target.url.returns(
+ options.url ?? 'chrome-extension://mock-extension-id/sw.js',
+ );
+ target.worker.resolves(options.worker ?? null);
+ return new McpWorker(
+ options.id ?? 'sw-1',
+ options.type ?? 'service_worker',
+ target,
+ );
+}
+
export function createMockMcpContext(
options: {selectedPage?: MockMcpPage} = {},
): MockMcpContext {
diff --git a/tests/tools/console.test.ts b/tests/tools/console.test.ts
index d1084413..a7bd2562 100644
--- a/tests/tools/console.test.ts
+++ b/tests/tools/console.test.ts
@@ -58,7 +58,7 @@ describe('console', () => {
t => t.type() === 'service_worker' && t.url().includes(extensionId),
);
- const swList = await context.createExtensionServiceWorkersSnapshot();
+ const swList = context.createWorkersSnapshot();
const sw = swList.find(s => s.target === swTarget);
assert(sw, 'Service worker not found in context list');
diff --git a/tests/tools/script.test.ts b/tests/tools/script.test.ts
index d428c8ce..0625fb3d 100644
--- a/tests/tools/script.test.ts
+++ b/tests/tools/script.test.ts
@@ -531,15 +531,15 @@ describe('script', () => {
t => t.type() === 'service_worker' && t.url().includes(extensionId),
);
- await context.createExtensionServiceWorkersSnapshot();
- const swList = context.getExtensionServiceWorkers();
+ context.createWorkersSnapshot();
+ const swList = context.getWorkers();
const sw = swList.find(s => s.target === swTarget);
if (!sw) {
assert.fail('Service worker not found in context list');
}
- const swId = context.getExtensionServiceWorkerId(sw);
+ const swId = sw.id;
await context.triggerExtensionAction(extensionId);
@@ -609,7 +609,7 @@ describe('script', () => {
message: 'specify either a pageId or a serviceWorkerId.',
},
);
- sinon.assert.notCalled(context.getExtensionServiceWorkers);
+ sinon.assert.notCalled(context.getWorkers);
sinon.assert.notCalled(context.getSelectedMcpPage);
sinon.assert.notCalled(context.getPageById);
sinon.assert.notCalled(page.waitForEventsAfterAction);
@@ -639,7 +639,7 @@ describe('script', () => {
'args (element uids) cannot be used when evaluating in a service worker.',
},
);
- sinon.assert.notCalled(context.getExtensionServiceWorkers);
+ sinon.assert.notCalled(context.getWorkers);
sinon.assert.notCalled(context.getSelectedMcpPage);
sinon.assert.notCalled(context.getPageById);
sinon.assert.notCalled(page.getElementByUid);
@@ -668,7 +668,7 @@ describe('script', () => {
message: 'specify either a pageId or a serviceWorkerId.',
},
);
- sinon.assert.notCalled(context.getExtensionServiceWorkers);
+ sinon.assert.notCalled(context.getWorkers);
sinon.assert.notCalled(context.getSelectedMcpPage);
sinon.assert.notCalled(context.getPageById);
sinon.assert.notCalled(page.waitForEventsAfterAction);
diff --git a/tests/utils.ts b/tests/utils.ts
index 6f7bbea2..60d8b336 100644
--- a/tests/utils.ts
+++ b/tests/utils.ts
@@ -184,6 +184,7 @@ export async function withMcpContext(
await withBrowser(async browser => {
TextSnapshot.resetCounter();
McpContext.resetPageIdsForTesting();
+ McpContext.resetWorkerIdsForTesting();
const parsedArgs = createMockParsedArguments(args);
const response = new McpResponse(parsedArgs);
if (context) {