Merge branch 'main' into fix/screenshot-mime-type-config

Author: marcandreuf

package-lock.json

@@ -52,15 +52,15 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1544076",
-    "core-js": "3.46.0",
+    "chrome-devtools-frontend": "1.0.1547147",
+    "core-js": "3.47.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.30.0",
+    "puppeteer": "24.31.0",
     "rollup": "4.53.2",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",

package.json

@@ -42,6 +42,10 @@ export interface TextSnapshot {
   idToNode: Map<string, TextSnapshotNode>;
   snapshotId: string;
   selectedElementUid?: string;
+  // It might happen that there is a selected element, but it is not part of the
+  // snapshot. This flag indicates if there is any selected element.
+  hasSelectedElement: boolean;
+  verbose: boolean;
 }
 
 interface McpContextOptions {
@@ -535,9 +539,12 @@ export class McpContext implements Context {
       root: rootNodeWithId,
       snapshotId: String(snapshotId),
       idToNode,
+      hasSelectedElement: false,
+      verbose,
     };
     const data = devtoolsData ?? (await this.getDevToolsData());
     if (data?.cdpBackendNodeId) {
+      this.#textSnapshot.hasSelectedElement = true;
       this.#textSnapshot.selectedElementUid = this.resolveCdpElementId(
         data?.cdpBackendNodeId,
       );

src/McpContext.ts

@@ -10,7 +10,20 @@ export function formatSnapshotNode(
   snapshot?: TextSnapshot,
   depth = 0,
 ): string {
-  let result = '';
+  const chunks: string[] = [];
+
+  if (depth === 0) {
+    // Top-level content of the snapshot.
+    if (
+      snapshot?.verbose &&
+      snapshot?.hasSelectedElement &&
+      !snapshot.selectedElementUid
+    ) {
+      chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
+    }
+  }
+
   const attributes = getAttributes(root);
   const line =
     ' '.repeat(depth * 2) +
@@ -19,13 +32,13 @@ export function formatSnapshotNode(
       ? ' [selected in the DevTools Elements panel]'
       : '') +
     '\n';
-  result += line;
+  chunks.push(line);
 
   for (const child of root.children) {
-    result += formatSnapshotNode(child, snapshot, depth + 1);
+    chunks.push(formatSnapshotNode(child, snapshot, depth + 1));
   }
 
-  return result;
+  return chunks.join('');
 }
 
 function getAttributes(serializedAXNodeRoot: TextSnapshotNode): string[] {

src/formatters/snapshotFormatter.ts

@@ -68,7 +68,7 @@ export const screenshot = defineTool({
     const screenshot = await pageOrHandle.screenshot({
       type: format,
       fullPage: request.params.fullPage,
-      quality: request.params.quality,
+      quality,
       optimizeForSpeed: true, // Bonus: optimize encoding for speed
     });
 

src/tools/screenshot.ts

@@ -0,0 +1,20 @@
+exports[`snapshotFormatter > does not include a note if the snapshot is already verbose 1`] = `
+Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.
+
+uid=1_1 checkbox "checkbox" checked
+  uid=1_2 statictext "text"
+
+`;
+
+exports[`snapshotFormatter > formats with DevTools data included into a snapshot 1`] = `
+uid=1_1 checkbox "checkbox" checked [selected in the DevTools Elements panel]
+  uid=1_2 statictext "text"
+
+`;
+
+exports[`snapshotFormatter > formats with DevTools data not included into a snapshot 1`] = `
+uid=1_1 checkbox "checkbox" checked
+  uid=1_2 statictext "text"
+
+`;

tests/formatters/snapshotFormatter.test.js.snapshot

@@ -148,4 +148,104 @@ describe('snapshotFormatter', () => {
 `,
     );
   });
+
+  it('formats with DevTools data not included into a snapshot', t => {
+    const node: TextSnapshotNode = {
+      id: '1_1',
+      role: 'checkbox',
+      name: 'checkbox',
+      checked: true,
+      children: [
+        {
+          id: '1_2',
+          role: 'statictext',
+          name: 'text',
+          children: [],
+          elementHandle: async (): Promise<ElementHandle<Element> | null> => {
+            return null;
+          },
+        },
+      ],
+      elementHandle: async (): Promise<ElementHandle<Element> | null> => {
+        return null;
+      },
+    };
+
+    const formatted = formatSnapshotNode(node, {
+      snapshotId: '1',
+      root: node,
+      idToNode: new Map(),
+      hasSelectedElement: true,
+      verbose: false,
+    });
+
+    t.assert.snapshot?.(formatted);
+  });
+
+  it('does not include a note if the snapshot is already verbose', t => {
+    const node: TextSnapshotNode = {
+      id: '1_1',
+      role: 'checkbox',
+      name: 'checkbox',
+      checked: true,
+      children: [
+        {
+          id: '1_2',
+          role: 'statictext',
+          name: 'text',
+          children: [],
+          elementHandle: async (): Promise<ElementHandle<Element> | null> => {
+            return null;
+          },
+        },
+      ],
+      elementHandle: async (): Promise<ElementHandle<Element> | null> => {
+        return null;
+      },
+    };
+
+    const formatted = formatSnapshotNode(node, {
+      snapshotId: '1',
+      root: node,
+      idToNode: new Map(),
+      hasSelectedElement: true,
+      verbose: true,
+    });
+
+    t.assert.snapshot?.(formatted);
+  });
+
+  it('formats with DevTools data included into a snapshot', t => {
+    const node: TextSnapshotNode = {
+      id: '1_1',
+      role: 'checkbox',
+      name: 'checkbox',
+      checked: true,
+      children: [
+        {
+          id: '1_2',
+          role: 'statictext',
+          name: 'text',
+          children: [],
+          elementHandle: async (): Promise<ElementHandle<Element> | null> => {
+            return null;
+          },
+        },
+      ],
+      elementHandle: async (): Promise<ElementHandle<Element> | null> => {
+        return null;
+      },
+    };
+
+    const formatted = formatSnapshotNode(node, {
+      snapshotId: '1',
+      root: node,
+      idToNode: new Map(),
+      hasSelectedElement: true,
+      selectedElementUid: '1_1',
+      verbose: false,
+    });
+
+    t.assert.snapshot?.(formatted);
+  });
 });

tests/formatters/snapshotFormatter.test.ts

@@ -109,7 +109,7 @@ Information on performance traces may contain main thread activity represented a
 
 Each call frame is presented in the following format:
 
-'id;eventKey;name;duration;selfTime;urlIndex;childRange;[S]'
+'id;eventKey;name;duration;selfTime;urlIndex;childRange;[line];[column];[S]'
 
 Key definitions:
 
@@ -120,15 +120,17 @@ Key definitions:
 * selfTime: The time spent directly within the call frame, excluding its children's execution.
 * urlIndex: Index referencing the "All URLs" list. Empty if no specific script URL is associated.
 * childRange: Specifies the direct children of this node using their IDs. If empty ('' or 'S' at the end), the node has no children. If a single number (e.g., '4'), the node has one child with that ID. If in the format 'firstId-lastId' (e.g., '4-5'), it indicates a consecutive range of child IDs from 'firstId' to 'lastId', inclusive.
+* line: An optional field for a call frame's line number. This is where the function is defined.
+* column: An optional field for a call frame's column number. This is where the function is defined.
 * S: _Optional_. The letter 'S' terminates the line if that call frame was selected by the user.
 
 Example Call Tree:
 
-1;r-123;main;500;100;;
-2;r-124;update;200;50;;3
-3;p-49575-15428179-2834-374;animate;150;20;0;4-5;S
-4;p-49575-15428179-3505-1162;calculatePosition;80;80;;
-5;p-49575-15428179-5391-2767;applyStyles;50;50;;
+1;r-123;main;500;100;0;1;;
+2;r-124;update;200;50;;3;0;1;
+3;p-49575-15428179-2834-374;animate;150;20;0;4-5;0;1;S
+4;p-49575-15428179-3505-1162;calculatePosition;80;80;0;1;;
+5;p-49575-15428179-5391-2767;applyStyles;50;50;0;1;;
 
 
 Network requests are formatted like this:

tests/tools/performance.test.js.snapshot

@@ -30,6 +30,25 @@ describe('screenshot', () => {
         );
       });
     });
+    it('ignores quality', async () => {
+      await withBrowser(async (response, context) => {
+        const fixture = screenshots.basic;
+        const page = context.getSelectedPage();
+        await page.setContent(fixture.html);
+        await screenshot.handler(
+          {params: {format: 'png', quality: 0}},
+          response,
+          context,
+        );
+
+        assert.equal(response.images.length, 1);
+        assert.equal(response.images[0].mimeType, 'image/png');
+        assert.equal(
+          response.responseLines.at(0),
+          "Took a screenshot of the current page's viewport.",
+        );
+      });
+    });
     it('with jpeg', async () => {
       await withBrowser(async (response, context) => {
         await screenshot.handler({params: {format: 'jpeg'}}, response, context);