testdriverai 7.3.4 → 7.3.6

package/docs/v7/examples/launch-vscode-linux.mdx

@@ -0,0 +1,101 @@
+---
+title: "Launching VS Code Example"
+sidebarTitle: "Launch VS Code"
+description: "Example test demonstrating how to launch VS Code and install extensions on Linux."
+icon: "play"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* launch-vscode-linux.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7cb811cc20acdd4ac83e/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="launch-vscode-linux.test.mjs" {13,27-29}
+/**
+ * TestDriver SDK - Launch VS Code Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+const isLinux = (process.env.TD_OS || "linux") === "linux";
+
+describe("Launch VS Code on Linux", () => {
+  it.skipIf(!isLinux)(
+    "should launch VS Code on Debian/Ubuntu",
+    async (context) => {
+      const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+      
+      // provision.vscode() automatically calls ready() and starts dashcam
+      await testdriver.provision.vscode();
+
+      // Wait for VS Code to launch (polls every 5s until found or timeout)
+      const vsCodeWindow = await testdriver.find(
+        "Visual Studio Code window",
+        { timeout: 60000 }
+      );
+      expect(vsCodeWindow.found()).toBeTruthy();
+    },
+  );
+
+  it.skipIf(!isLinux)(
+    "should install and use a VS Code extension",
+    async (context) => {
+      const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+      
+      // Launch VS Code with the Prettier extension installed
+      await testdriver.provision.vscode({
+        extensions: ["esbenp.prettier-vscode"],
+      });
+
+      const vsCodeWindow = await testdriver.find(
+        "Visual Studio Code window",
+        { timeout: 60000 }
+      );
+
+      expect(vsCodeWindow.found()).toBeTruthy();
+
+      // Open the extensions panel to verify Prettier is installed
+      await testdriver.pressKeys(["ctrl", "shift", "x"]);
+      
+      // Wait for extensions panel to open
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      // Assert that Prettier extension is visible in the installed extensions
+      const prettierVisible = await testdriver.assert(
+        "Prettier extension is visible in the extensions panel or sidebar",
+      );
+      expect(prettierVisible).toBeTruthy();
+    },
+  );
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/launch-vscode-linux.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/match-image.mdx

@@ -0,0 +1,96 @@
+---
+title: "Matching an Image By Pixel"
+sidebarTitle: "Pixel Based Match"
+description: "Example test demonstrating pixel-based image matching to locate UI elements."
+icon: "image"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* match-image.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7bd7297b1f49cee2a560/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="match-image.test.mjs" {42}
+/**
+ * TestDriver SDK - Match Image Test
+ */
+
+import path, { dirname } from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+/**
+ * Perform login flow for SauceLabs demo app
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} username - Username (default: 'standard_user')
+ */
+async function performLogin(client, username = "standard_user") {
+  await client.focusApplication("Google Chrome");
+  const password = await client.extract("the password");
+  const usernameField = await client.find(
+    "username input",
+  );
+  await usernameField.click();
+  await client.type(username);
+  await client.pressKeys(["tab"]);
+  await client.type(password, { secret: true });
+  await client.pressKeys(["tab"]);
+  await client.pressKeys(["enter"]);
+}
+
+// Get the directory of the current module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe("Match Image Test", () => {
+  it.skip("should match shopping cart image and verify empty cart", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    //
+    // Perform login first
+    await performLogin(testdriver);
+
+    // Match and click the shopping cart icon
+    const cartImagePath = path.resolve(
+      __dirname,
+      "../../_testdriver/acceptance/screenshots/cart.png",
+    );
+    await testdriver.matchImage(cartImagePath, "click");
+
+    // Assert that you see an empty shopping cart
+    const result = await testdriver.assert("Your cart is empty");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/match-image.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/press-keys.mdx

@@ -0,0 +1,92 @@
+---
+title: "Pressing Keys Test"
+sidebarTitle: "Pressing Keys"
+description: "Example test demonstrating keyboard shortcuts and key combinations for browser navigation."
+icon: "keyboard"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* press-keys.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7cf911cc20acdd4ac84a/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="press-keys.test.mjs" {17,24,36}
+/**
+ * TestDriver SDK - Press Keys Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Press Keys Test", () => {
+  it("should create tabs and navigate using keyboard shortcuts", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    const signInButton = await testdriver.find(
+      "Sign In, black button below the password field",
+    );
+    await signInButton.click();
+
+    // Open new tab
+    await testdriver.pressKeys(["ctrl", "t"]);
+
+    // Poll for "Learn more" to appear
+    let learnMore = await testdriver.find("Learn more");
+    for (let i = 0; i < 10; i++) {
+      learnMore = await learnMore.find();
+      if (learnMore.found()) break;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    // Open DevTools
+    await testdriver.pressKeys(["ctrl", "shift", "i"]);
+
+    // Poll for "Elements" to appear
+    let elements = await testdriver.find("Elements");
+    for (let i = 0; i < 10; i++) {
+      elements = await elements.find();
+      if (elements.found()) break;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    // Open another tab and navigate
+    await testdriver.pressKeys(["ctrl", "t"]);
+    await testdriver.type("google.com");
+    await testdriver.pressKeys(["enter"]);
+
+    // Assert Google appears
+    const result = await testdriver.assert("google appears");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/press-keys.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/scroll-keyboard.mdx

@@ -0,0 +1,79 @@
+---
+title: "Scrolling with Keyboard Test"
+sidebarTitle: "Scrolling with Keyboard"
+description: "Example test demonstrating page scrolling using keyboard-based scroll controls."
+icon: "scroll"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* scroll-keyboard.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7d92297b1f49cee2a5b2/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="scroll-keyboard.test.mjs" {26}
+/**
+ * TestDriver SDK - Scroll Keyboard Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Scroll Keyboard Test", () => {
+  it("should navigate to webhamster.com and scroll with keyboard", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    //
+    // Navigate to https://www.webhamster.com/
+    await testdriver.focusApplication("Google Chrome");
+    const urlBar = await testdriver.find(
+      "testdriver-sandbox.vercel.app/login, the URL in the omnibox showing the current page",
+    );
+    await urlBar.click();
+    await testdriver.pressKeys(["ctrl", "a"]);
+    await testdriver.type("https://www.webhamster.com/");
+    await testdriver.pressKeys(["enter"]);
+
+    // Scroll down with keyboard 1000 pixels
+    const heading = await testdriver.find(
+      "The Hamster Dance, large heading at top of page",
+    );
+    await heading.click();
+    await testdriver.scroll("down", { amount: 1000 });
+
+    // Assert the page is scrolled down
+    const result = await testdriver.assert("The text 'The Hamster Dance' is not visible on the webpage content. It's ok if it's visible in the tab title.");
+
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/scroll-keyboard.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/scroll-until-image.mdx

@@ -0,0 +1,81 @@
+---
+title: "Scroll Until Image Test"
+sidebarTitle: "Scroll Until Image"
+description: "Example test demonstrating how to scroll a page until a specific image becomes visible."
+icon: "scroll"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* scroll-until-image.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7d76297b1f49cee2a5b0/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="scroll-until-image.test.mjs" {26}
+/**
+ * TestDriver SDK - Scroll Until Image Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Scroll Until Image Test", () => {
+  it.skip("should scroll until brown colored house image appears", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    //
+    // Navigate to Wikipedia page
+    await testdriver.pressKeys(["ctrl", "l"]);
+    await testdriver.type("https://en.wikipedia.org/wiki/Leonardo_da_Vinci");
+    await testdriver.pressKeys(["enter"]);
+
+    // sleep for 5 seconds
+    await new Promise((r) => setTimeout(r, 5000));
+
+    // Click on heading
+    const heading = await testdriver.find(
+      "Leonardo Da Vinci, the page heading",
+      0,
+    );
+    await heading.click();
+
+    // Scroll until image appears
+    await testdriver.scrollUntilImage("a brown colored house", "down", 10000);
+
+    // Assert image of brown colored house appears on screen
+    const result = await testdriver.assert(
+      "image of brown colored house appears on screen",
+    );
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/scroll-until-image.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/scroll-until-text.mdx

@@ -0,0 +1,109 @@
+---
+title: "Scroll Until Text Test"
+sidebarTitle: "Scroll Until Text"
+description: "Example test demonstrating how to scroll a page until specific text becomes visible."
+icon: "scroll"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* scroll-until-text.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7c4d4f24dc8fa701f5ba/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="scroll-until-text.test.mjs" {41-51}
+/**
+ * TestDriver SDK - Scroll Until Text Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+/**
+ * Perform login flow for SauceLabs demo app
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} username - Username (default: 'standard_user')
+ */
+async function performLogin(client, username = "standard_user") {
+  await client.focusApplication("Google Chrome");
+  const password = await client.extract("the password");
+  const usernameField = await client.find(
+    "username input",
+  );
+  await usernameField.click();
+  await client.type(username);
+  await client.pressKeys(["tab"]);
+  await client.type(password, { secret: true });
+  await client.pressKeys(["tab"]);
+  await client.pressKeys(["enter"]);
+}
+
+describe("Scroll Until Text Test", () => {
+  it('should scroll until "testdriver socks" appears', async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    //
+    // Perform login first
+    await performLogin(testdriver);
+
+    // Scroll until text appears
+    await testdriver.focusApplication("Google Chrome");
+
+    await testdriver.find('TestDriver.ai Sandbox heading').click();
+
+    // Scroll until text appears
+    let found = false;
+    let scrollCount = 0;
+    const maxScrolls = 10;
+    
+    while (!found && scrollCount < maxScrolls) {
+      const findResult = await testdriver.find("testdriver socks product text is fully visible");
+
+      if (findResult.found()) {
+        found = true;
+      } else {
+        await testdriver.scroll();
+        scrollCount++;
+      }
+    }
+    
+    if (!found) {
+      throw new Error(`Failed to find "testdriver socks" after ${maxScrolls} scrolls`);
+    }
+
+    // Assert testdriver socks appears on screen
+    await testdriver.focusApplication("Google Chrome");
+    const result = await testdriver.assert("TestDriver Socks appears on screen");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/scroll-until-text.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>

package/docs/v7/examples/scroll.mdx

@@ -0,0 +1,81 @@
+---
+title: "Scrolling Test Example"
+sidebarTitle: "Scrolling"
+description: "Example test demonstrating page scrolling with configurable direction and scroll amount."
+icon: "scroll"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* scroll.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/698b7d39297b1f49cee2a5a7/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="scroll.test.mjs" {29}
+/**
+ * TestDriver SDK - Scroll Test
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Scroll Test", () => {
+  it("should navigate and scroll down the page", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    // Give Chrome a moment to fully render the UI
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    // Navigate to webhamster.com - just look for the domain, not the full path
+    const urlBar = await testdriver.find(
+      "testdriver-sandbox.vercel.app, the URL in the address bar",
+    );
+    await urlBar.click();
+    await testdriver.pressKeys(["ctrl", "a"]);
+    await testdriver.type("https://www.webhamster.com/");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load and click heading
+    const heading = await testdriver.find(
+      "The Hamster Dance, large heading at top of page",
+    );
+    await heading.click();
+
+    // Scroll down
+    await testdriver.scroll("down", { amount: 1000 });
+
+    // Assert page is scrolled
+    const result = await testdriver.assert("The text 'The Hamster Dance' is not visible on the webpage content. It's ok if it's visible in the tab title.");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Running This Example
+
+```bash
+# Clone the TestDriver repository
+git clone https://github.com/testdriverai/testdriverai
+
+# Install dependencies
+cd testdriverai
+npm install
+
+# Run this specific example
+npx vitest run examples/scroll.test.mjs
+```
+
+<Note>
+  Make sure you have `TD_API_KEY` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
+</Note>