@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-patch.0

package/dist/esm/tests/timeout-handlers.test.js

@@ -0,0 +1,850 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ActHandler } from "../lib/v3/handlers/actHandler.js";
+import { ExtractHandler } from "../lib/v3/handlers/extractHandler.js";
+import { ObserveHandler } from "../lib/v3/handlers/observeHandler.js";
+import { createTimeoutGuard } from "../lib/v3/handlers/handlerUtils/timeoutGuard.js";
+import { waitForDomNetworkQuiet } from "../lib/v3/handlers/handlerUtils/actHandlerUtils.js";
+import { captureHybridSnapshot } from "../lib/v3/understudy/a11y/snapshot/index.js";
+import {
+  ActTimeoutError,
+  ExtractTimeoutError,
+  ObserveTimeoutError
+} from "../lib/v3/types/public/sdkErrors.js";
+import {
+  act as actInference,
+  extract as extractInference,
+  observe as observeInference
+} from "../lib/inference.js";
+import { V3FunctionName } from "../lib/v3/types/public/methods.js";
+vi.mock("../lib/v3/handlers/handlerUtils/timeoutGuard", () => ({
+  createTimeoutGuard: vi.fn()
+}));
+vi.mock("../lib/v3/handlers/handlerUtils/actHandlerUtils", () => ({
+  waitForDomNetworkQuiet: vi.fn(),
+  performUnderstudyMethod: vi.fn()
+}));
+vi.mock("../lib/v3/understudy/a11y/snapshot", () => ({
+  captureHybridSnapshot: vi.fn(),
+  diffCombinedTrees: vi.fn()
+}));
+vi.mock("../lib/inference", () => ({
+  act: vi.fn(),
+  extract: vi.fn(),
+  observe: vi.fn()
+}));
+describe("ActHandler timeout guard", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("throws ActTimeoutError when timeout expires before snapshot", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.act({
+        instruction: "do something",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ActTimeoutError);
+    expect(waitForDomNetworkQuietMock).toHaveBeenCalledTimes(1);
+    expect(captureHybridSnapshotMock).not.toHaveBeenCalled();
+  });
+  it("throws ActTimeoutError when timeout expires before LLM call", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const actInferenceMock = vi.mocked(actInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return vi.fn(() => {
+          calls += 1;
+          if (calls >= 3) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.act({
+        instruction: "do something",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ActTimeoutError);
+    expect(captureHybridSnapshotMock).toHaveBeenCalledTimes(1);
+    expect(actInferenceMock).not.toHaveBeenCalled();
+  });
+  it("throws ActTimeoutError with correct message format", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const timeoutMs = 100;
+    vi.mocked(createTimeoutGuard).mockImplementation((ms, errorFactory) => {
+      return vi.fn(() => {
+        throw errorFactory ? errorFactory(ms) : new ActTimeoutError(ms);
+      });
+    });
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    try {
+      await handler.act({
+        instruction: "do something",
+        page: fakePage,
+        timeout: timeoutMs
+      });
+      throw new Error("Expected ActTimeoutError to be thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ActTimeoutError);
+      expect(error.message).toContain("act()");
+      expect(error.message).toContain(`${timeoutMs}ms`);
+      expect(error.name).toBe("ActTimeoutError");
+    }
+  });
+});
+describe("ActHandler two-step timeout", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("throws ActTimeoutError during step 2; step 2 action does not run", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = vi.mocked(actInference);
+    actInferenceMock.mockResolvedValueOnce({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: true,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    const diffCombinedTreesMock = vi.mocked(
+      (await import("../lib/v3/understudy/a11y/snapshot/index.js")).diffCombinedTrees
+    );
+    diffCombinedTreesMock.mockReturnValue("diff tree");
+    let callCount = 0;
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return vi.fn(() => {
+          callCount += 1;
+          if (callCount >= 7) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.act({
+        instruction: "click then type",
+        page: fakePage,
+        timeout: 50
+      })
+    ).rejects.toThrow(ActTimeoutError);
+    expect(performUnderstudyMethodMock).toHaveBeenCalledTimes(1);
+    expect(actInferenceMock).toHaveBeenCalledTimes(1);
+  });
+});
+describe("ActHandler self-heal timeout", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("throws ActTimeoutError during self-heal snapshot; no retry action executes", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockRejectedValueOnce(
+      new Error("Element not found")
+    );
+    const actInferenceMock = vi.mocked(actInference);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    let callCount = 0;
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return vi.fn(() => {
+          callCount += 1;
+          if (callCount >= 7) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler({ selfHeal: true });
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.act({
+        instruction: "click button",
+        page: fakePage,
+        timeout: 50
+      })
+    ).rejects.toThrow(ActTimeoutError);
+    expect(performUnderstudyMethodMock).toHaveBeenCalledTimes(1);
+    expect(actInferenceMock).toHaveBeenCalledTimes(1);
+    expect(captureHybridSnapshotMock).toHaveBeenCalled();
+  });
+  it("throws ActTimeoutError during self-heal LLM inference; no retry action executes", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockRejectedValueOnce(
+      new Error("Element not found")
+    );
+    const actInferenceMock = vi.mocked(actInference);
+    actInferenceMock.mockResolvedValueOnce({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    let callCount = 0;
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return vi.fn(() => {
+          callCount += 1;
+          if (callCount >= 8) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler({ selfHeal: true });
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.act({
+        instruction: "click button",
+        page: fakePage,
+        timeout: 50
+      })
+    ).rejects.toThrow(ActTimeoutError);
+    expect(captureHybridSnapshotMock).toHaveBeenCalledTimes(2);
+    expect(actInferenceMock).toHaveBeenCalledTimes(1);
+  });
+});
+describe("ExtractHandler timeout guard", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("throws ExtractTimeoutError when timeout expires before snapshot", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const extractInferenceMock = vi.mocked(extractInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return vi.fn(() => {
+          throw errorFactory ? errorFactory(timeoutMs) : new ExtractTimeoutError(timeoutMs);
+        });
+      }
+    );
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.extract({
+        instruction: "extract title",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ExtractTimeoutError);
+    expect(captureHybridSnapshotMock).not.toHaveBeenCalled();
+    expect(extractInferenceMock).not.toHaveBeenCalled();
+  });
+  it("throws ExtractTimeoutError when timeout expires before LLM call", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const extractInferenceMock = vi.mocked(extractInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ExtractTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.extract({
+        instruction: "extract title",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ExtractTimeoutError);
+    expect(captureHybridSnapshotMock).toHaveBeenCalledTimes(1);
+    expect(extractInferenceMock).not.toHaveBeenCalled();
+  });
+  it("throws ExtractTimeoutError with correct message format", async () => {
+    const timeoutMs = 200;
+    vi.mocked(createTimeoutGuard).mockImplementation((ms, errorFactory) => {
+      return vi.fn(() => {
+        throw errorFactory ? errorFactory(ms) : new ExtractTimeoutError(ms);
+      });
+    });
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    try {
+      await handler.extract({
+        instruction: "extract title",
+        page: fakePage,
+        timeout: timeoutMs
+      });
+      throw new Error("Expected ExtractTimeoutError to be thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ExtractTimeoutError);
+      expect(error.message).toContain("extract()");
+      expect(error.message).toContain(
+        `${timeoutMs}ms`
+      );
+      expect(error.name).toBe("ExtractTimeoutError");
+    }
+  });
+  it("stops LLM and post-processing when timeout expires", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: { "1-0": "https://example.com" }
+    });
+    const extractInferenceMock = vi.mocked(extractInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ExtractTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.extract({
+        instruction: "extract links",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ExtractTimeoutError);
+    expect(extractInferenceMock).not.toHaveBeenCalled();
+  });
+});
+describe("ObserveHandler timeout guard", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("throws ObserveTimeoutError when timeout expires before snapshot", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = vi.mocked(observeInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return vi.fn(() => {
+          throw errorFactory ? errorFactory(timeoutMs) : new ObserveTimeoutError(timeoutMs);
+        });
+      }
+    );
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.observe({
+        instruction: "find buttons",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ObserveTimeoutError);
+    expect(captureHybridSnapshotMock).not.toHaveBeenCalled();
+    expect(observeInferenceMock).not.toHaveBeenCalled();
+  });
+  it("throws ObserveTimeoutError when timeout expires before LLM call", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = vi.mocked(observeInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ObserveTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.observe({
+        instruction: "find buttons",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ObserveTimeoutError);
+    expect(captureHybridSnapshotMock).toHaveBeenCalledTimes(1);
+    expect(observeInferenceMock).not.toHaveBeenCalled();
+  });
+  it("throws ObserveTimeoutError with correct message format", async () => {
+    const timeoutMs = 150;
+    vi.mocked(createTimeoutGuard).mockImplementation((ms, errorFactory) => {
+      return vi.fn(() => {
+        throw errorFactory ? errorFactory(ms) : new ObserveTimeoutError(ms);
+      });
+    });
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    try {
+      await handler.observe({
+        instruction: "find buttons",
+        page: fakePage,
+        timeout: timeoutMs
+      });
+      throw new Error("Expected ObserveTimeoutError to be thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ObserveTimeoutError);
+      expect(error.message).toContain("observe()");
+      expect(error.message).toContain(
+        `${timeoutMs}ms`
+      );
+      expect(error.name).toBe("ObserveTimeoutError");
+    }
+  });
+  it("aborts result processing when timeout expires", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = vi.mocked(observeInference);
+    vi.mocked(createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new ObserveTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    await expect(
+      handler.observe({
+        instruction: "find all interactive elements",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(ObserveTimeoutError);
+    expect(observeInferenceMock).not.toHaveBeenCalled();
+  });
+});
+describe("No-timeout success paths", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("act() completes successfully without timeout and records metrics", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = vi.mocked(actInference);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      reasoning_tokens: 10,
+      cached_input_tokens: 5,
+      inference_time_ms: 500
+    });
+    vi.mocked(createTimeoutGuard).mockImplementation(() => {
+      return vi.fn(() => {
+      });
+    });
+    const metricsCallback = vi.fn();
+    const handler = buildActHandler({ onMetrics: metricsCallback });
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    const result = await handler.act({
+      instruction: "click button",
+      page: fakePage
+      // No timeout specified
+    });
+    expect(result.success).toBe(true);
+    expect(metricsCallback).toHaveBeenCalledWith(
+      V3FunctionName.ACT,
+      100,
+      50,
+      10,
+      5,
+      500
+    );
+  });
+  it("extract() completes successfully without timeout and records metrics", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const extractInferenceMock = vi.mocked(extractInference);
+    extractInferenceMock.mockResolvedValue({
+      title: "Test Title",
+      metadata: { completed: true, progress: "100%" },
+      prompt_tokens: 200,
+      completion_tokens: 100,
+      reasoning_tokens: 20,
+      cached_input_tokens: 10,
+      inference_time_ms: 800
+    });
+    vi.mocked(createTimeoutGuard).mockImplementation(() => {
+      return vi.fn(() => {
+      });
+    });
+    const metricsCallback = vi.fn();
+    const handler = buildExtractHandler({ onMetrics: metricsCallback });
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    const result = await handler.extract({
+      instruction: "extract title",
+      page: fakePage
+      // No timeout specified
+    });
+    expect(result).toHaveProperty("title", "Test Title");
+    expect(metricsCallback).toHaveBeenCalledWith(
+      V3FunctionName.EXTRACT,
+      200,
+      100,
+      20,
+      10,
+      800
+    );
+  });
+  it("observe() completes successfully without timeout and records metrics", async () => {
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = vi.mocked(observeInference);
+    observeInferenceMock.mockResolvedValue({
+      elements: [
+        {
+          elementId: "1-0",
+          description: "Submit button"
+        }
+      ],
+      prompt_tokens: 150,
+      completion_tokens: 75,
+      reasoning_tokens: 15,
+      cached_input_tokens: 8,
+      inference_time_ms: 600
+    });
+    vi.mocked(createTimeoutGuard).mockImplementation(() => {
+      return vi.fn(() => {
+      });
+    });
+    const metricsCallback = vi.fn();
+    const handler = buildObserveHandler({ onMetrics: metricsCallback });
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    const result = await handler.observe({
+      instruction: "find buttons",
+      page: fakePage
+      // No timeout specified
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]).toHaveProperty("description", "Submit button");
+    expect(metricsCallback).toHaveBeenCalledWith(
+      V3FunctionName.OBSERVE,
+      150,
+      75,
+      15,
+      8,
+      600
+    );
+  });
+  it("act() with zero timeout behaves as no timeout", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = vi.mocked(actInference);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    vi.mocked(createTimeoutGuard).mockImplementation((timeoutMs) => {
+      if (!timeoutMs || timeoutMs <= 0) {
+        return vi.fn(() => {
+        });
+      }
+      return vi.fn(() => {
+        throw new ActTimeoutError(timeoutMs);
+      });
+    });
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    const result = await handler.act({
+      instruction: "click button",
+      page: fakePage,
+      timeout: 0
+      // Zero timeout should be treated as "no timeout"
+    });
+    expect(result.success).toBe(true);
+  });
+  it("act() with negative timeout behaves as no timeout", async () => {
+    const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = vi.mocked(actInference);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    vi.mocked(createTimeoutGuard).mockImplementation((timeoutMs) => {
+      if (!timeoutMs || timeoutMs <= 0) {
+        return vi.fn(() => {
+        });
+      }
+      return vi.fn(() => {
+        throw new ActTimeoutError(timeoutMs);
+      });
+    });
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: vi.fn().mockReturnValue({})
+    };
+    const result = await handler.act({
+      instruction: "click button",
+      page: fakePage,
+      timeout: -100
+      // Negative timeout should be treated as "no timeout"
+    });
+    expect(result.success).toBe(true);
+  });
+});
+function buildActHandler(options = {}) {
+  const defaultClientOptions = {};
+  const fakeClient = {
+    type: "openai",
+    modelName: "gpt-4o",
+    clientOptions: defaultClientOptions
+  };
+  const resolveLlmClient = vi.fn().mockReturnValue(fakeClient);
+  return new ActHandler(
+    fakeClient,
+    "gpt-4o",
+    defaultClientOptions,
+    resolveLlmClient,
+    void 0,
+    false,
+    options.selfHeal ?? false,
+    options.onMetrics,
+    void 0
+  );
+}
+function buildExtractHandler(options = {}) {
+  const defaultClientOptions = {};
+  const fakeClient = {
+    type: "openai",
+    modelName: "gpt-4o",
+    clientOptions: defaultClientOptions
+  };
+  const resolveLlmClient = vi.fn().mockReturnValue(fakeClient);
+  return new ExtractHandler(
+    fakeClient,
+    "gpt-4o",
+    defaultClientOptions,
+    resolveLlmClient,
+    void 0,
+    false,
+    false,
+    options.onMetrics
+  );
+}
+function buildObserveHandler(options = {}) {
+  const defaultClientOptions = {};
+  const fakeClient = {
+    type: "openai",
+    modelName: "gpt-4o",
+    clientOptions: defaultClientOptions
+  };
+  const resolveLlmClient = vi.fn().mockReturnValue(fakeClient);
+  return new ObserveHandler(
+    fakeClient,
+    "gpt-4o",
+    defaultClientOptions,
+    resolveLlmClient,
+    void 0,
+    false,
+    false,
+    options.onMetrics
+  );
+}
+//# sourceMappingURL=timeout-handlers.test.js.map