mcp-web-inspector 0.5.3 → 0.6.0

package/README.md

@@ -911,11 +911,11 @@ Quick check if an element exists on the page. Ultra-lightweight alternative to q
 
 ### Navigation
 
-#### `go_back`
-Navigate back in browser history
+#### `go_history`
+Navigate browser history (back/forward). Returns: 'Navigated <direction> in browser history', a quick network-idle note if available, 'URL: <current>', and 'Title: <current>' when set. If console errors occur after the navigation, returns an error like 'Console error after history navigation: <message>' including Title when available.
 
-#### `go_forward`
-Navigate forward in browser history
+- Parameters:
+  - direction (string, required): History direction to navigate
 
 #### `navigate`
 Navigate to a URL. Browser sessions (cookies, localStorage, sessionStorage) are automatically saved in ./.mcp-web-inspector/user-data directory and persist across restarts. To clear saved sessions, delete the directory.
@@ -1048,7 +1048,7 @@ Clears captured console logs and returns the number of entries cleared.
 Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
 
 - Parameters:
-  - type (string, optional): Type of logs to retrieve (all, error, warning, log, info, debug, exception)
+  - type (string, optional): Type filter (all, error, warning, log, info, debug, exception). Note: 'error' also includes 'exception' entries for convenience.
   - search (string, optional): Text to search for in logs (handles text with square brackets)
   - limit (number, optional): Maximum entries to return (groups when grouped, lines when raw). Default: 20
   - since (string, optional): Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.). Default: 'last-interaction'

package/dist/toolHandler.d.ts

@@ -79,6 +79,10 @@ export declare function getConsoleLogs(): string[];
  * Get console logs captured after the last navigation
  */
 export declare function getConsoleLogsSinceLastNavigation(): string[];
+/**
+ * Get console logs captured after the last interaction
+ */
+export declare function getConsoleLogsSinceLastInteraction(): string[];
 /**
  * Get screenshots
  */

package/dist/toolHandler.js

@@ -72,15 +72,30 @@ function getColorSchemeValue() {
     return colorSchemeOverride;
 }
 async function applyColorScheme(targetPage) {
-    if (!targetPage) {
+    if (!targetPage)
         return;
-    }
+    const scheme = getColorSchemeValue();
     try {
-        const scheme = getColorSchemeValue();
-        await targetPage.emulateMedia({ colorScheme: scheme ?? null });
+        // Some test environments or mocks may not implement emulateMedia
+        const anyPage = targetPage;
+        if (typeof anyPage.emulateMedia === 'function') {
+            await anyPage.emulateMedia({ colorScheme: scheme ?? null });
+            return;
+        }
+        // Fallback: if emulateMedia is unavailable, do a best-effort hint via CSS.
+        // This won't fully emulate prefers-color-scheme but avoids throwing in tests.
+        if (scheme) {
+            const css = scheme === 'dark' ? ':root{color-scheme: dark;}'
+                : scheme === 'light' ? ':root{color-scheme: light;}'
+                    : ':root{color-scheme: light dark;}';
+            if (typeof anyPage.addStyleTag === 'function') {
+                await anyPage.addStyleTag({ content: css });
+            }
+        }
     }
     catch (error) {
-        console.error("Failed to apply color scheme:", error);
+        // Swallow errors to keep color scheme application non-fatal
+        console.warn("Failed to apply color scheme (non-fatal):", error);
     }
 }
 export async function setColorSchemeOverride(scheme) {
@@ -258,13 +273,13 @@ async function getScreenSize() {
         await tempBrowser.close();
         // Validate the screen size values
         if (!screenSize || typeof screenSize.width !== 'number' || typeof screenSize.height !== 'number') {
-            console.error('Invalid screen size detected, using defaults');
+            console.warn('Invalid screen size detected, using defaults');
             return { width: 1280, height: 720 };
         }
         return screenSize;
     }
     catch (error) {
-        console.error('Failed to detect screen size, using defaults:', error);
+        console.warn('Failed to detect screen size, using defaults:', error);
         return { width: 1280, height: 720 };
     }
 }
@@ -279,15 +294,15 @@ export async function ensureBrowser(browserSettings) {
             const browserCheck = checkBrowsersInstalled();
             if (!browserCheck.installed) {
                 // Try to install browsers automatically
-                console.error('🎭 Playwright browsers not found. Installing automatically...');
-                console.error('⏳ This will download ~1GB of browser binaries. Please wait...');
+                console.warn('🎭 Playwright browsers not found. Installing automatically...');
+                console.warn('⏳ This will download ~1GB of browser binaries. Please wait...');
                 try {
                     const { execSync } = await import('child_process');
                     execSync('npx playwright install chromium firefox webkit', {
                         stdio: 'inherit',
                         encoding: 'utf8'
                     });
-                    console.error('✅ Browsers installed successfully! Starting browser...');
+                    console.log('✅ Browsers installed successfully! Starting browser...');
                     // Note: browser variable is still undefined here, which is correct.
                     // The code below (line 342) will launch the browser after installation.
                 }
@@ -300,7 +315,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Check if browser exists but is disconnected
         if (browser && !browser.isConnected()) {
-            console.error("Browser exists but is disconnected. Cleaning up...");
+            console.warn("Browser exists but is disconnected. Cleaning up...");
             try {
                 await browser.close().catch(err => console.error("Error closing disconnected browser:", err));
             }
@@ -312,7 +327,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Check if device preset has changed (requires browser restart)
         if (browser && browserSettings?.device && browserSettings.device !== currentDevice) {
-            console.error(`Device preset changed from ${currentDevice || 'none'} to ${browserSettings.device}. Restarting browser...`);
+            console.warn(`Device preset changed from ${currentDevice || 'none'} to ${browserSettings.device}. Restarting browser...`);
             try {
                 await browser.close().catch(err => console.error("Error closing browser on device change:", err));
             }
@@ -331,7 +346,7 @@ export async function ensureBrowser(browserSettings) {
                 const targetHeight = height ?? currentViewport?.height ?? 720;
                 // Check if viewport size actually changed
                 if (!currentViewport || currentViewport.width !== targetWidth || currentViewport.height !== targetHeight) {
-                    console.error(`Resizing viewport to ${targetWidth}x${targetHeight}`);
+                    console.log(`Resizing viewport to ${targetWidth}x${targetHeight}`);
                     await page.setViewportSize({ width: targetWidth, height: targetHeight });
                 }
             }
@@ -356,18 +371,18 @@ export async function ensureBrowser(browserSettings) {
                 // Check custom configs first, then Playwright's built-in devices
                 deviceConfig = CUSTOM_DEVICE_CONFIGS[playwrightDeviceName] || devices[playwrightDeviceName];
                 if (deviceConfig) {
-                    console.error(`Using device preset: ${device} (${playwrightDeviceName})`);
+                    console.log(`Using device preset: ${device} (${playwrightDeviceName})`);
                     currentDevice = device;
                 }
                 else {
-                    console.error(`Warning: Device preset ${playwrightDeviceName} not found`);
+                    console.warn(`Warning: Device preset ${playwrightDeviceName} not found`);
                     currentDevice = undefined;
                 }
             }
             else {
                 currentDevice = undefined;
             }
-            console.error(`Launching new ${browserType} browser instance...`);
+            console.warn(`Launching new ${browserType} browser instance...`);
             // Use the appropriate browser engine
             let browserInstance;
             switch (browserType) {
@@ -397,7 +412,7 @@ export async function ensureBrowser(browserSettings) {
                 viewportWidth = screenSize?.width ?? 1280;
                 viewportHeight = screenSize?.height ?? 720;
                 if (screenSize && screenSize.width > 0 && screenSize.height > 0) {
-                    console.error(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
+                    console.log(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
                 }
             }
             // Prepare context options
@@ -421,14 +436,14 @@ export async function ensureBrowser(browserSettings) {
             }
             // Use persistent context if session saving is enabled
             if (sessionConfig.saveSession) {
-                console.error(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir}...`);
+                console.warn(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir}...`);
                 const context = await browserInstance.launchPersistentContext(sessionConfig.userDataDir, contextOptions);
                 // Get the browser instance from the context
                 browser = context.browser();
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
                 browser.on('disconnected', () => {
-                    console.error("Browser disconnected event triggered");
+                    console.warn("Browser disconnected event triggered");
                     browser = undefined;
                     page = undefined;
                 });
@@ -444,7 +459,7 @@ export async function ensureBrowser(browserSettings) {
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
                 browser.on('disconnected', () => {
-                    console.error("Browser disconnected event triggered");
+                    console.warn("Browser disconnected event triggered");
                     browser = undefined;
                     page = undefined;
                 });
@@ -473,7 +488,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Verify page is still valid
         if (!page || page.isClosed()) {
-            console.error("Page is closed or invalid. Creating new page...");
+            console.warn("Page is closed or invalid. Creating new page...");
             // Create a new page if the current one is invalid
             const context = browser.contexts()[0] || await browser.newContext();
             page = await context.newPage();
@@ -565,12 +580,12 @@ export async function ensureBrowser(browserSettings) {
         }
         // Use persistent context if session saving is enabled
         if (sessionConfig.saveSession) {
-            console.error(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir} (retry)...`);
+            console.warn(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir} (retry)...`);
             const context = await browserInstance.launchPersistentContext(sessionConfig.userDataDir, retryContextOptions);
             browser = context.browser();
             currentBrowserType = browserType;
             browser.on('disconnected', () => {
-                console.error("Browser disconnected event triggered (retry)");
+                console.warn("Browser disconnected event triggered (retry)");
                 browser = undefined;
                 page = undefined;
             });
@@ -584,7 +599,7 @@ export async function ensureBrowser(browserSettings) {
             });
             currentBrowserType = browserType;
             browser.on('disconnected', () => {
-                console.error("Browser disconnected event triggered (retry)");
+                console.warn("Browser disconnected event triggered (retry)");
                 browser = undefined;
                 page = undefined;
             });
@@ -650,7 +665,7 @@ export async function handleToolCall(name, args, server) {
         const requiresBrowser = isBrowserTool(name);
         // Check if we have a disconnected browser that needs cleanup
         if (browser && !browser.isConnected() && requiresBrowser) {
-            console.error("Detected disconnected browser before tool execution, cleaning up...");
+            console.warn("Detected disconnected browser before tool execution, cleaning up...");
             try {
                 await browser.close().catch(() => { }); // Ignore errors
             }
@@ -739,6 +754,16 @@ export function getConsoleLogsSinceLastNavigation() {
         return [];
     return consoleLogsTool.getLogsSinceLastNavigation();
 }
+/**
+ * Get console logs captured after the last interaction
+ */
+export function getConsoleLogsSinceLastInteraction() {
+    const consoleLogsTool = getToolInstance("get_console_logs", null);
+    if (!consoleLogsTool)
+        return [];
+    // Expose a compact accessor mirroring navigation-based retrieval
+    return consoleLogsTool.getLogsSinceLastInteraction?.() ?? [];
+}
 /**
  * Get screenshots
  */

package/dist/tools/browser/base.d.ts

@@ -121,4 +121,10 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * @param totalCount Total number of matches
      */
     protected buildNthSelectorHint(selector: string, totalCount: number): string;
+    /**
+     * Describe matched elements in a compact, copyable format for disambiguation errors.
+     * Shows: index, tag, trimmed text, nearest parent marker, and a suggested selector.
+     * Suggests testid:VALUE when present; otherwise falls back to id=VALUE or original >> nth=i.
+     */
+    protected describeMatchedElements(locator: any, originalSelector: string, count: number): Promise<string>;
 }

package/dist/tools/browser/base.js

@@ -233,8 +233,8 @@ export class BrowserToolBase {
         // Check for multiple elements with errorOnMultiple flag
         if (options?.errorOnMultiple && count > 1) {
             const selector = options.originalSelector || 'selector';
-            const nthHint = this.buildNthSelectorHint(selector, count).trimEnd();
-            const warning = this.getDuplicateTestIdWarning(selector, count).trimEnd();
+            const nthHint = ''.trimEnd();
+            const warning = ''.trimEnd();
             let message = `Selector "${selector}" matched ${count} elements. Please use a more specific selector.`;
             if (nthHint) {
                 message += `\n${nthHint}`;
@@ -242,7 +242,15 @@ export class BrowserToolBase {
             if (warning) {
                 message += `\n${warning}`;
             }
-            throw new Error(message);
+            {
+                const guidance = [
+                    `1) Preferred: add a unique data-testid and select it directly (e.g., testid:submit).`,
+                    `2) If you cannot change markup: append \`>> nth=<index>\` to target a specific match.`,
+                ];
+                const matchesDetails = await this.describeMatchedElements(locator, selector, count);
+                message += `\n${guidance.join('\n')}\n\nMatches:\n${matchesDetails}`;
+                throw new Error(message);
+            }
         }
         // Handle explicit element index (1-based)
         if (options?.elementIndex !== undefined) {
@@ -358,4 +366,68 @@ export class BrowserToolBase {
             `Note: nth selectors are brittle and may break with layout/content changes.\n` +
             `Prefer unique data-testid attributes for long-term stability.`);
     }
+    /**
+     * Describe matched elements in a compact, copyable format for disambiguation errors.
+     * Shows: index, tag, trimmed text, nearest parent marker, and a suggested selector.
+     * Suggests testid:VALUE when present; otherwise falls back to id=VALUE or original >> nth=i.
+     */
+    async describeMatchedElements(locator, originalSelector, count) {
+        const maxItems = Math.min(count, 5);
+        const lines = [];
+        for (let i = 0; i < maxItems; i++) {
+            const nth = locator.nth(i);
+            try {
+                const info = await nth.evaluate((el) => {
+                    const tag = (el.tagName || '').toLowerCase();
+                    let text = el.innerText || el.textContent || '';
+                    text = (text || '').replace(/\s+/g, ' ').trim();
+                    const testid = el.getAttribute?.('data-testid') || el.getAttribute?.('data-test') || el.getAttribute?.('data-cy') || null;
+                    const id = el.id || null;
+                    let parentLabel = null;
+                    let p = el.parentElement;
+                    while (p && !parentLabel) {
+                        const ptid = p.getAttribute?.('data-testid');
+                        const ptest = p.getAttribute?.('data-test');
+                        const pcy = p.getAttribute?.('data-cy');
+                        const pid = p.id || null;
+                        if (ptid)
+                            parentLabel = `[data-testid="${ptid}"]`;
+                        else if (ptest)
+                            parentLabel = `[data-test="${ptest}"]`;
+                        else if (pcy)
+                            parentLabel = `[data-cy="${pcy}"]`;
+                        else if (pid)
+                            parentLabel = `#${pid}`;
+                        p = p.parentElement;
+                    }
+                    return { tag, text, testid, id, parentLabel };
+                });
+                const truncatedText = info.text && info.text.length > 80 ? `${info.text.slice(0, 77)}...` : info.text;
+                let selectorSuggestion = `${originalSelector} >> nth=${i}`;
+                let altSuggestion;
+                if (info?.testid) {
+                    selectorSuggestion = `testid:${info.testid}`;
+                    altSuggestion = `${originalSelector} >> nth=${i}`;
+                }
+                else if (info?.id) {
+                    selectorSuggestion = `id=${info.id}`;
+                    altSuggestion = `${originalSelector} >> nth=${i}`;
+                }
+                const parts = [
+                    `[${i}] <${info.tag}>${truncatedText ? ` "${truncatedText}"` : ''}`,
+                    info.parentLabel ? `    parent: ${info.parentLabel}` : undefined,
+                    `    selector: ${selectorSuggestion}`,
+                    altSuggestion ? `    alt: ${altSuggestion}` : undefined,
+                ].filter(Boolean);
+                lines.push(parts.join('\n'));
+            }
+            catch {
+                lines.push(`[${i}] (element)\n    selector: ${originalSelector} >> nth=${i}`);
+            }
+        }
+        if (count > maxItems) {
+            lines.push(`… and ${count - maxItems} more matches (use >> nth=<index> to target).`);
+        }
+        return lines.join('\n');
+    }
 }

package/dist/tools/browser/common/postAction.d.ts

@@ -0,0 +1,7 @@
+import type { Page } from 'playwright';
+export declare function gatherConsoleErrorsSince(since: 'navigation' | 'interaction'): Promise<string[]>;
+export declare function quickNetworkIdleNote(page: Page): Promise<string>;
+export declare function titleUrlChangeLines(page: Page, initial?: {
+    url?: string;
+    title?: string;
+}): Promise<string[]>;

package/dist/tools/browser/common/postAction.js

@@ -0,0 +1,46 @@
+// Gather console error/exception logs since a baseline event
+export async function gatherConsoleErrorsSince(since) {
+    const { getConsoleLogsSinceLastNavigation, getConsoleLogsSinceLastInteraction } = await import('../../../toolHandler.js');
+    const logs = since === 'navigation'
+        ? getConsoleLogsSinceLastNavigation()
+        : getConsoleLogsSinceLastInteraction();
+    return logs.filter(l => l.startsWith('[error]') || l.startsWith('[exception]'));
+}
+// Provide a compact, best-effort network idle note
+export async function quickNetworkIdleNote(page) {
+    try {
+        const start = Date.now();
+        const anyPage = page;
+        const wait = anyPage?.waitForLoadState?.bind(page);
+        if (typeof wait === 'function') {
+            await wait('networkidle', { timeout: 500 });
+            const ms = Date.now() - start;
+            return `✓ Network idle after ${ms}ms, 0 pending requests`;
+        }
+    }
+    catch {
+        // fall through to no-activity note
+    }
+    return 'No new network activity detected (quick check)';
+}
+// Compute concise lines for title/URL when changed
+export async function titleUrlChangeLines(page, initial = {}) {
+    const lines = [];
+    let newUrl = '';
+    let newTitle = '';
+    try {
+        newUrl = page.url();
+    }
+    catch { }
+    try {
+        newTitle = await page.title();
+    }
+    catch { }
+    if (initial.url && newUrl && initial.url !== newUrl) {
+        lines.push(`URL changed: ${newUrl}`);
+    }
+    if (initial.title && newTitle && initial.title !== newTitle) {
+        lines.push(`Title changed: ${newTitle}`);
+    }
+    return lines;
+}

package/dist/tools/browser/console/__tests__/console.test.js

@@ -237,4 +237,13 @@ describe('GetConsoleLogsTool', () => {
         // Should include one of the first 20 grouped messages
         expect(fullText).toContain('GROUP-LONG-0');
     });
+    test('type: error should include exception entries', async () => {
+        consoleLogsTool.registerConsoleMessage('exception', 'Hook failed');
+        consoleLogsTool.registerConsoleMessage('error', 'Console error');
+        const result = await consoleLogsTool.execute({ type: 'error' }, mockContext);
+        expect(result.isError).toBe(false);
+        const text = result.content.map(c => c.text).join('\n');
+        expect(text).toContain('[exception] Hook failed');
+        expect(text).toContain('[error] Console error');
+    });
 });

package/dist/tools/browser/console/get_console_logs.d.ts

@@ -36,6 +36,10 @@ export declare class GetConsoleLogsTool extends BrowserToolBase {
      * Return messages for logs captured after the last recorded navigation
      */
     getLogsSinceLastNavigation(): string[];
+    /**
+     * Return messages for logs captured after the last recorded interaction
+     */
+    getLogsSinceLastInteraction(): string[];
 }
 /**
  * Tool for clearing console logs (atomic operation)

package/dist/tools/browser/console/get_console_logs.js

@@ -23,7 +23,7 @@ export class GetConsoleLogsTool extends BrowserToolBase {
                 properties: {
                     type: {
                         type: "string",
-                        description: "Type of logs to retrieve (all, error, warning, log, info, debug, exception)",
+                        description: "Type filter (all, error, warning, log, info, debug, exception). Note: 'error' also includes 'exception' entries for convenience.",
                         enum: ["all", "error", "warning", "log", "info", "debug", "exception"]
                     },
                     search: {
@@ -100,7 +100,10 @@ export class GetConsoleLogsTool extends BrowserToolBase {
         this.lastCallTimestamp = Date.now();
         // Filter by type if specified
         if (args.type && args.type !== 'all') {
-            logs = logs.filter(log => log.message.startsWith(`[${args.type}]`));
+            const wanted = args.type;
+            // Treat 'error' as including both console errors and exceptions captured via pageerror/unhandledrejection
+            const prefixes = wanted === 'error' ? ['[error]', '[exception]'] : [`[${wanted}]`];
+            logs = logs.filter(log => prefixes.some(p => log.message.startsWith(p)));
         }
         // Filter by search text if specified
         if (args.search) {
@@ -193,6 +196,15 @@ export class GetConsoleLogsTool extends BrowserToolBase {
             .filter(log => log.timestamp > since)
             .map(log => log.message);
     }
+    /**
+     * Return messages for logs captured after the last recorded interaction
+     */
+    getLogsSinceLastInteraction() {
+        const since = this.lastInteractionTimestamp;
+        return this.consoleLogs
+            .filter(log => log.timestamp > since)
+            .map(log => log.message);
+    }
 }
 // Track latest instance for sibling tool access (module-level singleton pattern)
 GetConsoleLogsTool.latestInstance = null;

package/dist/tools/browser/interaction/__tests__/duplicateClickErrorFormatting.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/browser/interaction/__tests__/duplicateClickErrorFormatting.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, test, beforeEach, jest } from '@jest/globals';
+import { ClickTool } from '../click.js';
+function makeFakeLocator() {
+    const elements = [
+        {
+            tagName: 'BUTTON',
+            innerText: 'Cancel',
+            textContent: 'Cancel',
+            id: '',
+            attrs: { 'data-testid': 'modal-cancel' },
+            parent: { tagName: 'DIV', id: 'modal-footer', attrs: {}, parent: null },
+        },
+        {
+            tagName: 'BUTTON',
+            innerText: 'Cancel',
+            textContent: 'Cancel',
+            id: 'toolbar-cancel',
+            attrs: {},
+            parent: { tagName: 'DIV', id: 'toolbar', attrs: {}, parent: null },
+        },
+        {
+            tagName: 'BUTTON',
+            innerText: 'Cancel third',
+            textContent: 'Cancel third',
+            id: '',
+            attrs: {},
+            parent: { tagName: 'DIV', id: '', attrs: { 'data-test': 'footer' }, parent: null },
+        },
+    ];
+    const wrap = (el) => ({
+        evaluate: (fn) => {
+            const toDomEl = (src) => ({
+                tagName: src.tagName,
+                innerText: src.innerText,
+                textContent: src.textContent,
+                id: src.id,
+                getAttribute: (name) => src.attrs[name] ?? null,
+                parentElement: src.parent
+                    ? {
+                        tagName: src.parent.tagName,
+                        id: src.parent.id,
+                        getAttribute: (name) => src.parent.attrs[name] ?? null,
+                        parentElement: src.parent.parent,
+                    }
+                    : null,
+            });
+            return fn(toDomEl(el));
+        },
+    });
+    return {
+        count: async () => elements.length,
+        nth: (i) => wrap(elements[i]),
+    };
+}
+describe('ClickTool duplicate selection error formatting (integration)', () => {
+    let clickTool;
+    let mockPage;
+    let mockBrowser;
+    let mockContext;
+    const mockIsClosed = jest.fn().mockReturnValue(false);
+    const mockIsConnected = jest.fn().mockReturnValue(true);
+    const mockPageLocator = jest.fn();
+    beforeEach(() => {
+        jest.clearAllMocks();
+        clickTool = new ClickTool({});
+        mockPage = {
+            locator: mockPageLocator,
+            isClosed: mockIsClosed,
+        };
+        mockBrowser = {
+            isConnected: mockIsConnected,
+        };
+        mockContext = {
+            page: mockPage,
+            browser: mockBrowser,
+            server: {},
+        };
+    });
+    test('returns concise guidance and match options when multiple elements match', async () => {
+        const fakeLocator = makeFakeLocator();
+        mockPageLocator.mockReturnValue(fakeLocator);
+        const res = await clickTool.execute({ selector: 'text=Cancel' }, mockContext);
+        expect(res.isError).toBe(true);
+        const text = res.content.map(c => c.text).join('\n');
+        // Prefixed by "Operation failed: ..."
+        expect(text).toContain('matched 3 elements');
+        expect(text).toContain('1) Preferred: add a unique data-testid');
+        expect(text).toContain('2) If you cannot change markup');
+        expect(text).toContain('Matches:');
+        expect(text).toContain('selector: testid:modal-cancel');
+        expect(text).toContain('selector: id=toolbar-cancel');
+        expect(text).toContain('selector: text=Cancel >> nth=2');
+        // Ensure old verbose hints are not duplicated here
+        expect(text).not.toContain('Primary fix: add a unique data-testid');
+        expect(text).not.toContain('Workaround: Append');
+    });
+});

package/dist/tools/browser/interaction/click.js

@@ -1,5 +1,6 @@
 import { BrowserToolBase } from '../base.js';
-import { createSuccessResponse } from '../../common/types.js';
+import { createSuccessResponse, createErrorResponse } from '../../common/types.js';
+import { gatherConsoleErrorsSince, quickNetworkIdleNote, titleUrlChangeLines } from '../common/postAction.js';
 /**
  * Tool for clicking elements on the page
  */
@@ -27,8 +28,51 @@ export class ClickTool extends BrowserToolBase {
                 errorOnMultiple: true,
                 originalSelector: args.selector,
             });
+            // Capture initial state for change detection
+            let initialUrl = '';
+            let initialTitle = '';
+            try {
+                initialUrl = page.url();
+            }
+            catch { }
+            try {
+                initialTitle = await page.title();
+            }
+            catch { }
             await element.click();
-            return createSuccessResponse(`Clicked element: ${args.selector}`);
+            const lines = [`Clicked element: ${args.selector}`];
+            // First, a quick network-idle hint to allow errors to flush
+            try {
+                const note = await quickNetworkIdleNote(page);
+                if (note)
+                    lines.push(note);
+            }
+            catch { }
+            // Then, surface console errors triggered by the interaction
+            try {
+                const errs = await gatherConsoleErrorsSince('interaction');
+                if (errs.length > 0) {
+                    let titleInfo = '';
+                    try {
+                        const t = await page.title();
+                        if (t)
+                            titleInfo = `\nTitle: ${t}`;
+                    }
+                    catch { }
+                    return createErrorResponse(`Console error after click: ${errs[0]}${titleInfo}`);
+                }
+            }
+            catch {
+                // ignore log retrieval errors
+            }
+            // Title / URL changes
+            try {
+                const changeLines = await titleUrlChangeLines(page, { url: initialUrl, title: initialTitle });
+                if (changeLines.length > 0)
+                    lines.push(...changeLines);
+            }
+            catch { }
+            return createSuccessResponse(lines);
         });
     }
 }

package/dist/tools/browser/navigation/__tests__/goNavigation.test.js

@@ -1,5 +1,4 @@
-import { GoBackTool } from '../go_back.js';
-import { GoForwardTool } from '../go_forward.js';
+import { GoHistoryTool } from '../history.js';
 import { jest } from '@jest/globals';
 // Mock page functions
 const mockGoBack = jest.fn().mockImplementation(() => Promise.resolve());
@@ -26,63 +25,52 @@ const mockContext = {
     browser: mockBrowser,
     server: mockServer
 };
-describe('Browser Navigation History Tools', () => {
-    let goBackTool;
-    let goForwardTool;
+describe('Browser Navigation History Tool', () => {
+    let historyTool;
     beforeEach(() => {
         jest.clearAllMocks();
-        goBackTool = new GoBackTool(mockServer);
-        goForwardTool = new GoForwardTool(mockServer);
+        historyTool = new GoHistoryTool(mockServer);
         // Reset browser and page mocks
         mockIsConnected.mockReturnValue(true);
         mockIsClosed.mockReturnValue(false);
     });
-    describe('GoBackTool', () => {
+    describe('HistoryTool', () => {
         test('should navigate back in browser history', async () => {
-            const args = {};
-            const result = await goBackTool.execute(args, mockContext);
+            const args = { direction: 'back' };
+            const result = await historyTool.execute(args, mockContext);
             expect(mockGoBack).toHaveBeenCalled();
             expect(result.isError).toBe(false);
             expect(result.content[0].text).toContain('Navigated back');
         });
+        test('should navigate forward in browser history', async () => {
+            const args = { direction: 'forward' };
+            const result = await historyTool.execute(args, mockContext);
+            expect(mockGoForward).toHaveBeenCalled();
+            expect(result.isError).toBe(false);
+            expect(result.content[0].text).toContain('Navigated forward');
+        });
         test('should handle navigation back errors', async () => {
-            const args = {};
+            const args = { direction: 'back' };
             // Mock a navigation error
             mockGoBack.mockImplementationOnce(() => Promise.reject(new Error('Navigation back failed')));
-            const result = await goBackTool.execute(args, mockContext);
+            const result = await historyTool.execute(args, mockContext);
             expect(mockGoBack).toHaveBeenCalled();
             expect(result.isError).toBe(true);
             expect(result.content[0].text).toContain('Operation failed');
         });
-        test('should handle missing page', async () => {
-            const args = {};
-            const result = await goBackTool.execute(args, { server: mockServer });
-            expect(mockGoBack).not.toHaveBeenCalled();
-            expect(result.isError).toBe(true);
-            expect(result.content[0].text).toContain('Browser page not initialized');
-        });
-    });
-    describe('GoForwardTool', () => {
-        test('should navigate forward in browser history', async () => {
-            const args = {};
-            const result = await goForwardTool.execute(args, mockContext);
-            expect(mockGoForward).toHaveBeenCalled();
-            expect(result.isError).toBe(false);
-            expect(result.content[0].text).toContain('Navigated forward');
-        });
         test('should handle navigation forward errors', async () => {
-            const args = {};
+            const args = { direction: 'forward' };
             // Mock a navigation error
             mockGoForward.mockImplementationOnce(() => Promise.reject(new Error('Navigation forward failed')));
-            const result = await goForwardTool.execute(args, mockContext);
+            const result = await historyTool.execute(args, mockContext);
             expect(mockGoForward).toHaveBeenCalled();
             expect(result.isError).toBe(true);
             expect(result.content[0].text).toContain('Operation failed');
         });
         test('should handle missing page', async () => {
-            const args = {};
-            const result = await goForwardTool.execute(args, { server: mockServer });
-            expect(mockGoForward).not.toHaveBeenCalled();
+            const args = { direction: 'back' };
+            const result = await historyTool.execute(args, { server: mockServer });
+            expect(mockGoBack).not.toHaveBeenCalled();
             expect(result.isError).toBe(true);
             expect(result.content[0].text).toContain('Browser page not initialized');
         });

package/dist/tools/browser/navigation/history.d.ts

@@ -0,0 +1,9 @@
+import { BrowserToolBase } from '../base.js';
+import { ToolContext, ToolResponse, ToolMetadata, SessionConfig } from '../../common/types.js';
+/**
+ * Tool for navigating browser history (back/forward)
+ */
+export declare class GoHistoryTool extends BrowserToolBase {
+    static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/navigation/history.js

@@ -0,0 +1,86 @@
+import { BrowserToolBase } from '../base.js';
+import { createSuccessResponse, createErrorResponse } from '../../common/types.js';
+import { gatherConsoleErrorsSince, quickNetworkIdleNote } from '../common/postAction.js';
+/**
+ * Tool for navigating browser history (back/forward)
+ */
+export class GoHistoryTool extends BrowserToolBase {
+    static getMetadata(sessionConfig) {
+        return {
+            name: 'go_history',
+            description: "Navigate browser history (back/forward). Returns: 'Navigated <direction> in browser history', a quick network-idle note if available, 'URL: <current>', and 'Title: <current>' when set. If console errors occur after the navigation, returns an error like 'Console error after history navigation: <message>' including Title when available.",
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    direction: {
+                        type: 'string',
+                        description: "History direction to navigate",
+                        enum: ['back', 'forward']
+                    },
+                },
+                required: ['direction'],
+            },
+        };
+    }
+    async execute(args, context) {
+        this.recordNavigation();
+        return this.safeExecute(context, async (page) => {
+            const dir = args.direction === 'forward' ? 'forward' : 'back';
+            // Capture initial state
+            let initialUrl = '';
+            let initialTitle = '';
+            try {
+                initialUrl = page.url();
+            }
+            catch { }
+            try {
+                initialTitle = await page.title();
+            }
+            catch { }
+            // Perform history navigation
+            if (dir === 'back') {
+                await page.goBack();
+            }
+            else {
+                await page.goForward();
+            }
+            const verb = dir === 'back' ? 'back' : 'forward';
+            const lines = [`Navigated ${verb} in browser history`];
+            // Allow network to settle briefly first (best-effort)
+            try {
+                const note = await quickNetworkIdleNote(page);
+                if (note)
+                    lines.push(note);
+            }
+            catch { }
+            // After the brief wait, surface console errors since navigation
+            try {
+                const errs = await gatherConsoleErrorsSince('navigation');
+                if (errs.length > 0) {
+                    let titleInfo = '';
+                    try {
+                        const t = await page.title();
+                        if (t)
+                            titleInfo = `\nTitle: ${t}`;
+                    }
+                    catch { }
+                    return createErrorResponse(`Console error after history navigation: ${errs[0]}${titleInfo}`);
+                }
+            }
+            catch { }
+            // Report new URL and Title explicitly
+            try {
+                const newUrl = page.url();
+                lines.push(`URL: ${newUrl}`);
+            }
+            catch { }
+            try {
+                const newTitle = await page.title();
+                if (newTitle)
+                    lines.push(`Title: ${newTitle}`);
+            }
+            catch { }
+            return createSuccessResponse(lines);
+        });
+    }
+}

package/dist/tools/browser/navigation/index.d.ts

@@ -1,5 +1,4 @@
 export { NavigateTool } from './navigate.js';
-export { GoBackTool } from './go_back.js';
-export { GoForwardTool } from './go_forward.js';
+export { GoHistoryTool } from './history.js';
 export { ScrollToElementTool } from './scroll_to_element.js';
 export { ScrollByTool } from './scroll_by.js';

package/dist/tools/browser/navigation/index.js

@@ -1,5 +1,4 @@
 export { NavigateTool } from './navigate.js';
-export { GoBackTool } from './go_back.js';
-export { GoForwardTool } from './go_forward.js';
+export { GoHistoryTool } from './history.js';
 export { ScrollToElementTool } from './scroll_to_element.js';
 export { ScrollByTool } from './scroll_by.js';

package/dist/tools/browser/navigation/navigate.js

@@ -1,5 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse, createErrorResponse } from '../../common/types.js';
+import { gatherConsoleErrorsSince, quickNetworkIdleNote } from '../common/postAction.js';
 async function resetState() {
     const { resetBrowserState } = await import('../../../toolHandler.js');
     resetBrowserState();
@@ -105,7 +106,45 @@ export class NavigateTool extends BrowserToolBase {
                 catch {
                     // Best-effort detection; ignore and proceed
                 }
-                return createSuccessResponse(`Navigated to ${args.url}`);
+                // First, perform a quick network-idle check to allow any errors to flush
+                // before we examine console errors. Keep it best-effort with small timeout.
+                const messages = [`Navigated to ${args.url}`];
+                try {
+                    const note = await quickNetworkIdleNote(page);
+                    if (note)
+                        messages.push(note);
+                }
+                catch {
+                    // Ignore failures in the quick check
+                }
+                // After waiting briefly, surface hard page errors if any
+                try {
+                    const errs = await gatherConsoleErrorsSince('navigation');
+                    if (errs.length > 0) {
+                        // Include page title (best-effort) to aid debugging
+                        let titleInfo = '';
+                        try {
+                            const t = await page.title();
+                            if (t)
+                                titleInfo = `\nTitle: ${t}`;
+                        }
+                        catch { }
+                        return createErrorResponse(`Console error after navigation: ${errs[0]}${titleInfo}`);
+                    }
+                }
+                catch {
+                    // If log retrieval fails, continue normally
+                }
+                // Add page title to help the agent orient itself
+                try {
+                    const title = await page.title();
+                    if (title)
+                        messages.push(`Title: ${title}`);
+                }
+                catch {
+                    // Ignore title failures
+                }
+                return createSuccessResponse(messages);
             }
             catch (error) {
                 const errorMessage = error.message;

package/dist/tools/browser/register.js

@@ -1,7 +1,6 @@
 // Navigation
 import { NavigateTool } from './navigation/navigate.js';
-import { GoBackTool } from './navigation/go_back.js';
-import { GoForwardTool } from './navigation/go_forward.js';
+import { GoHistoryTool } from './navigation/history.js';
 import { ScrollToElementTool } from './navigation/scroll_to_element.js';
 import { ScrollByTool } from './navigation/scroll_by.js';
 // Lifecycle
@@ -43,8 +42,7 @@ import { WaitForNetworkIdleTool } from './waiting/wait_for_network_idle.js';
 export const BROWSER_TOOL_CLASSES = [
     // Navigation (5)
     NavigateTool,
-    GoBackTool,
-    GoForwardTool,
+    GoHistoryTool,
     ScrollToElementTool,
     ScrollByTool,
     // Lifecycle (2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-web-inspector",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Web Inspector MCP: Give LLMs visual superpowers to see, debug, and test any web page.",
   "license": "MIT",
   "author": "Anton",
@@ -28,14 +28,13 @@
     "url": "https://github.com/antonzherdev/mcp-web-inspector.git"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.11.1",
-    "@playwright/browser-chromium": "1.53.1",
-    "@playwright/browser-firefox": "1.53.1",
-    "@playwright/browser-webkit": "1.53.1",
-    "@playwright/test": "^1.53.1",
-    "mcp-evals": "^1.0.18",
-    "playwright": "1.53.1",
-    "uuid": "11.1.0"
+    "@modelcontextprotocol/sdk": "1.21.0",
+    "@playwright/browser-chromium": "1.56.1",
+    "@playwright/browser-firefox": "1.56.1",
+    "@playwright/browser-webkit": "1.56.1",
+    "@playwright/test": "^1.56.1",
+    "playwright": "1.56.1",
+    "uuid": "13.0.0"
   },
   "keywords": [
     "mcp",
@@ -51,11 +50,11 @@
   ],
   "devDependencies": {
     "@types/jest": "^29.5.14",
-    "@types/node": "^20.10.5",
+    "@types/node": "^24.10.0",
     "jest": "^29.7.0",
     "jest-playwright-preset": "4.0.0",
-    "shx": "^0.3.4",
-    "ts-jest": "^29.2.6",
-    "typescript": "^5.8.3"
+    "shx": "^0.4.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3"
   }
 }