feat(mcp-tools): add hover element tool

* feat(mcp-tools): add hover element tool

* feat(mcp-tools): add hover element tool # add tests

---------

Co-authored-by: rocketraccoon <[email protected]>

Author: sonic16x

.gitignore

@@ -3,3 +3,4 @@ build
 testplane-mcp-*.tgz
 tmp
 .vscode
+.idea

src/tools/hover-element.ts

@@ -0,0 +1,44 @@
+import { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ToolDefinition } from "../types.js";
+import { contextProvider } from "../context-provider.js";
+import { createElementStateResponse, createErrorResponse } from "../responses/index.js";
+import { elementSelectorSchema, findElement } from "./utils/element-selector.js";
+
+export const elementHoverSchema = elementSelectorSchema;
+
+const hoverElementCb: ToolCallback<typeof elementHoverSchema> = async args => {
+    try {
+        const context = contextProvider.getContext();
+        const browser = await context.browser.get();
+
+        const { element, queryDescription, testplaneCode } = await findElement(browser, args.locator);
+
+        await element.moveTo();
+
+        console.error(`Successfully hovered element with ${queryDescription}`);
+
+        return await createElementStateResponse(element, {
+            action: `Successfully hovered element found by ${queryDescription}`,
+            testplaneCode: testplaneCode.startsWith("await")
+                ? `await (${testplaneCode}).moveTo();`
+                : `await ${testplaneCode}.moveTo();`,
+        });
+    } catch (error) {
+        console.error("Error hover element:", error);
+
+        if (error instanceof Error && error.message.includes("Unable to find")) {
+            return createErrorResponse(
+                "Element not found. Try using a different query strategy or check if the element exists on the page.",
+            );
+        }
+
+        return createErrorResponse("Error hover element", error instanceof Error ? error : undefined);
+    }
+};
+
+export const hoverElement: ToolDefinition<typeof elementHoverSchema> = {
+    name: "hoverElement",
+    description: "Hover an element on the page.",
+    schema: elementHoverSchema,
+    cb: hoverElementCb,
+};

src/tools/index.ts

@@ -2,6 +2,7 @@ import { ToolDefinition } from "../types.js";
 import { navigate } from "./navigate.js";
 import { closeBrowser } from "./close-browser.js";
 import { clickOnElement } from "./click-on-element.js";
+import { hoverElement } from "./hover-element.js";
 import { typeIntoElement } from "./type-into-element.js";
 import { takePageSnapshot } from "./take-page-snapshot.js";
 import { listTabs } from "./list-tabs.js";
@@ -14,6 +15,7 @@ export const tools = [
     navigate,
     closeBrowser,
     clickOnElement,
+    hoverElement,
     typeIntoElement,
     takePageSnapshot,
     listTabs,

test/tools/hover-element.test.ts

@@ -0,0 +1,126 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { describe, it, expect, beforeAll, beforeEach, afterEach, afterAll } from "vitest";
+import { startClient } from "../utils";
+import { INTEGRATION_TEST_TIMEOUT } from "../constants";
+import { PlaygroundServer } from "../test-server";
+import { LocatorStrategy } from "../../src/tools/utils/element-selector";
+
+describe(
+    "tools/hoverElement",
+    () => {
+        let client: Client;
+        let playgroundUrl: string;
+        let testServer: PlaygroundServer;
+
+        beforeAll(async () => {
+            testServer = new PlaygroundServer();
+            playgroundUrl = await testServer.start();
+        }, 20000);
+
+        afterAll(async () => {
+            if (testServer) {
+                await testServer.stop();
+            }
+        });
+
+        beforeEach(async () => {
+            client = await startClient();
+            await client.callTool({ name: "navigate", arguments: { url: playgroundUrl } });
+        });
+
+        afterEach(async () => {
+            if (client) {
+                await client.close();
+            }
+        });
+
+        describe("tool availability", () => {
+            it("should list hoverElement tool in available tools", async () => {
+                const tools = await client.listTools();
+
+                const elementHoverTool = tools.tools.find(tool => tool.name === "hoverElement");
+
+                expect(elementHoverTool).toBeDefined();
+            });
+        });
+
+        describe("hover functionality", () => {
+            it("should hover an element using semantic query", async () => {
+                const result = await client.callTool({
+                    name: "hoverElement",
+                    arguments: {
+                        locator: {
+                            strategy: LocatorStrategy.TestingLibrary,
+                            queryType: "role",
+                            queryValue: "button",
+                            queryOptions: { name: "Submit Form" },
+                        },
+                    },
+                });
+
+                expect(result.isError).toBe(false);
+                const content = result.content as Array<{ type: string; text: string }>;
+                expect(content[0].text).toContain("Successfully hovered element");
+                expect(content[0].text).toContain("button#submit-btn[@hover]");
+            });
+
+            it("should hover an element using CSS selector", async () => {
+                const result = await client.callTool({
+                    name: "hoverElement",
+                    arguments: {
+                        locator: {
+                            strategy: LocatorStrategy.Wdio,
+                            selector: "#unique-element",
+                        },
+                    },
+                });
+
+                expect(result.isError).toBe(false);
+                const content = result.content as Array<{ type: string; text: string }>;
+                expect(content[0].text).toContain("Successfully hovered element");
+                expect(content[0].text).toContain("div#unique-element[@hover]");
+            });
+
+            it("should return correct testplane code for hovered element", async () => {
+                const result = await client.callTool({
+                    name: "hoverElement",
+                    arguments: {
+                        locator: {
+                            strategy: LocatorStrategy.TestingLibrary,
+                            queryType: "role",
+                            queryValue: "button",
+                            queryOptions: { name: "Submit Form" },
+                        },
+                    },
+                });
+
+                expect(result.isError).toBe(false);
+                const content = result.content as Array<{ type: string; text: string }>;
+                expect(content[0].text).toContain(
+                    'await (await browser.findByRole("button", {"name":"Submit Form"})).moveTo()',
+                );
+            });
+        });
+
+        describe("error handling specific to hover", () => {
+            it("should provide helpful error messages for hover failures", async () => {
+                const result = await client.callTool({
+                    name: "hoverElement",
+                    arguments: {
+                        locator: {
+                            strategy: LocatorStrategy.TestingLibrary,
+                            queryType: "role",
+                            queryValue: "button",
+                            queryOptions: { name: "Non-existent Button" },
+                        },
+                    },
+                });
+
+                expect(result.isError).toBe(true);
+                const content = result.content as Array<{ type: string; text: string }>;
+                expect(content[0].text).toContain("Element not found");
+            });
+        });
+    },
+    INTEGRATION_TEST_TIMEOUT,
+);