testdriverai 7.3.2 → 7.3.4

package/eslint.config.js

@@ -0,0 +1,67 @@
+const globals = require("globals");
+const pluginJs = require("@eslint/js");
+
+module.exports = [
+  pluginJs.configs.recommended,
+  {
+    // Base config for all JavaScript files - provides Node.js globals
+    languageOptions: {
+      sourceType: "commonjs",
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    // Specific config for interface and agent files - adds browser globals
+    files: ["./interfaces/**/*.js", "./agent/**/*.js"],
+    languageOptions: {
+      sourceType: "commonjs",
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+  },
+  {
+    // Specific config for test files - adds Jest and Mocha globals
+    files: ["test/**/*.js"],
+    languageOptions: {
+      sourceType: "commonjs",
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+        ...globals.mocha,
+      },
+    },
+  },
+  {
+    // Config for ES Module files (.mjs) - used in SDK tests
+    files: ["**/*.mjs"],
+    languageOptions: {
+      sourceType: "module",
+      ecmaVersion: 2022,
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      // Warn about floating promises (unawaited async calls)
+      // This catches missing `await` on async methods like click(), assert(), etc.
+      // Note: For TypeScript projects, use @typescript-eslint/no-floating-promises instead
+      "require-await": "warn",
+    },
+  },
+  {
+    // this needs to be it's own object for some reason
+    // https://github.com/eslint/eslint/issues/17400
+    ignores: [
+      "agent/lib/subimage/**",
+      "node_modules/**",
+      ".git",
+      "test-results/**",
+      "examples/test-recording-example.test.js",
+      "vitest.config.example.js",
+    ],
+  },
+];

package/examples/ai.test.mjs

@@ -0,0 +1,30 @@
+/**
+ * TestDriver SDK - AI Test (Vitest)
+ * Tests the AI exploratory loop (ai) functionality
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("AI Test", () => {
+  it("should use ai to search for testdriver on Google", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+    
+    // provision.chrome() automatically calls ready() and starts dashcam
+    await testdriver.provision.chrome({
+      url: 'https://duckduckgo.com',
+    });
+
+    // Use ai to search for testdriver
+    let aiRes = await testdriver.ai("click on the empty search box, type 'testdriver', and hit enter.");
+
+    console.log("AI response:", aiRes);
+
+    // Assert the search results are displayed
+    const result = await testdriver.assert(
+      "search results for testdriver are visible",
+    );
+
+    expect(result).toBeTruthy();
+  });
+});

package/examples/assert.test.mjs

@@ -0,0 +1,47 @@
+/**
+ * TestDriver SDK - Assert Test (Vitest)
+ * Converted from: testdriver/acceptance/assert.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Assert Test", () => {
+  it("should assert the testdriver login page shows", async (context) => {
+    const testdriver = TestDriver(context, {
+      preview: 'ide',
+      ip: context.ip || process.env.TD_IP,
+    });
+    
+    // provision.chrome() automatically calls ready() and starts dashcam
+    await testdriver.provision.chrome({
+      url: 'http://testdriver-sandbox.vercel.app/login',
+    });
+
+    // Take a screenshot
+    await testdriver.screenshot();
+
+    // Assert the TestDriver.ai Sandbox login page is displayed
+    const result = await testdriver.assert(
+      "the TestDriver.ai Sandbox login page is displayed",
+    );
+
+    expect(result).toBeTruthy();
+  });
+  // it("should assert the testdriver login page shows 2", async (context) => {
+  //   const testdriver = TestDriver(context);
+    
+  //   // provision.chrome() automatically calls ready() and starts dashcam
+  //   await testdriver.provision.chrome({
+  //     url: 'http://testdriver-sandbox.vercel.app/login',
+  //   });
+
+  //   // Assert the TestDriver.ai Sandbox login page is displayed
+  //   const result = await testdriver.assert(
+  //     "the TestDriver.ai Sandbox login page is displayed",
+  //   );
+
+  //   expect(result).toBeTruthy();
+  // });
+});
+

package/examples/captcha-api.test.mjs

@@ -0,0 +1,50 @@
+/**
+ * Test for testdriver.captcha() API
+ * Clean, simple API for solving captchas
+ */
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+console.log("DEBUG: process.env.TD_OS:", process.env.TD_OS);
+
+describe("testdriver.captcha() API", () => {
+  it("should solve reCAPTCHA v3 with auto-detect", async (context) => {
+    const testdriver = TestDriver(context);
+
+    // Launch Chrome (remote debugging is enabled automatically on Linux)
+    await testdriver.provision.chrome({
+      url: "https://2captcha.com/demo/recaptcha-v3",
+    });
+
+    await testdriver.screenshot();
+
+    // Solve the captcha with just the API key - everything else is auto-detected!
+    const result = await testdriver.captcha({
+      apiKey: process.env.TWOCAPTCHA_API_KEY,
+    });
+
+    console.log("Captcha result:", result);
+    await testdriver.screenshot();
+
+    expect(result.success).toBe(true);
+  }, 180000);
+
+  it("should solve Cloudflare Turnstile", async (context) => {
+    const testdriver = TestDriver(context);
+
+    await testdriver.provision.chrome({
+      url: "https://2captcha.com/demo/cloudflare-turnstile",
+    });
+
+    await testdriver.screenshot();
+
+    const result = await testdriver.captcha({
+      apiKey: process.env.TWOCAPTCHA_API_KEY,
+    });
+
+    console.log("Turnstile result:", result);
+    await testdriver.screenshot();
+
+    expect(result.success).toBe(true);
+  }, 180000);
+});

package/examples/chrome-extension.test.mjs

@@ -0,0 +1,94 @@
+/**
+ * TestDriver SDK - Chrome Extension Test (Vitest)
+ * Tests loading a Chrome extension using provision.chromeExtension()
+ * 
+ * This test suite covers:
+ * 1. Loading extension from local path (extensionPath)
+ * 2. Loading extension from Chrome Web Store (extensionId)
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Chrome Extension Test", () => {
+  it("should load hello-world Chrome extension from local path", async (context) => {
+
+    console.log('connecting to', process.env.TD_IP)
+
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, cacheKey: new Date().getTime().toString() });
+    
+    // Determine OS-specific paths and commands
+    const shell = testdriver.os === 'windows' ? 'pwsh' : 'sh';
+    const extensionsDir = testdriver.os === 'windows' 
+      ? 'C:\\Users\\testdriver\\Downloads\\chrome-extensions-samples'
+      : '/tmp/chrome-extensions-samples';
+    const extensionPath = testdriver.os === 'windows'
+      ? `${extensionsDir}\\functional-samples\\tutorial.hello-world`
+      : `${extensionsDir}/functional-samples/tutorial.hello-world`;
+    
+    // Clone the Chrome extensions samples repo
+    const cloneCmd = testdriver.os === 'windows'
+      ? `git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git "${extensionsDir}"`
+      : `git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git ${extensionsDir}`;
+    
+    await testdriver.exec(shell, cloneCmd, 60000, true);
+
+    // Launch Chrome with the hello-world extension loaded
+    await testdriver.provision.chromeExtension({
+      extensionPath: extensionPath
+    });
+
+    // Navigate to testdriver.ai (extensions don't load on New Tab)
+    const addressBar = await testdriver.find("Chrome address bar");
+    await addressBar.click();
+    await testdriver.type("testdriver.ai");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load
+    const pageResult = await testdriver.assert("I can see testdriver.ai");
+    expect(pageResult).toBeTruthy();
+
+    // The hello-world extension adds a puzzle piece icon to the toolbar
+    // When clicked, it shows a popup with "Hello Extensions"
+
+    // Click on the extensions button (puzzle piece icon) in Chrome toolbar
+    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar", {zoom: true});
+    await extensionsButton.click();
+
+    // Look for the hello world extension in the extensions menu
+    const helloExtension = await testdriver.find("Hello Extensions extension in the extensions dropdown");
+    await helloExtension.click();
+
+    // Verify the extension popup shows "Hello Extensions" text
+    const popupResult = await testdriver.assert("a popup shows with the text 'Hello Extensions'");
+    expect(popupResult).toBeTruthy();
+  });
+
+  it("should load Loom from Chrome Web Store by extensionId", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+
+    // Launch Chrome with Loom loaded by its Chrome Web Store ID
+    // Loom ID: liecbddmkiiihnedobmlmillhodjkdmb
+    await testdriver.provision.chromeExtension({
+      extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
+    });
+
+    // Navigate to testdriver.ai (extensions don't load on New Tab)
+    const addressBar = await testdriver.find("Chrome address bar");
+    await addressBar.click();
+    await testdriver.type("testdriver.ai");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load
+    const pageResult = await testdriver.assert("I can see testdriver.ai");
+    expect(pageResult).toBeTruthy();
+
+    // Click on the extensions button (puzzle piece icon) in Chrome toolbar
+    const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.", {zoom: true});
+    await extensionsButton.click();
+
+    // Look for Loom in the extensions menu
+    const loomExtension = await testdriver.find("Loom extension in the extensions dropdown");
+    expect(loomExtension.found()).toBeTruthy();
+  });
+});

package/examples/drag-and-drop.test.mjs

@@ -0,0 +1,58 @@
+/**
+ * TestDriver SDK - Drag and Drop Test (Vitest)
+ * Converted from: testdriver/acceptance/drag-and-drop.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+const isLinux = (process.env.TD_OS || "linux") === "linux";
+
+describe("Drag and Drop Test", () => {
+  it.skipIf(isLinux)(
+    'should drag "New Text Document" to "Recycle Bin"',
+    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' });
+
+      //
+      // Show the desktop
+      await testdriver.pressKeys(["win", "d"]);
+
+      // Open the context menu
+      await testdriver.pressKeys(["shift", "f10"]);
+
+      // Hover over "New" in the context menu
+      const newOption = await testdriver.find(
+        "New, new option in the open context menu on the desktop",
+      );
+      await newOption.hover();
+
+      // Click "Text Document" in the context menu
+      const textDocOption = await testdriver.find(
+        "Text Document, text document option in the new submenu of the desktop context menu",
+      );
+      await textDocOption.click();
+
+      // Unfocus the "Text Document" text field
+      await testdriver.pressKeys(["esc"]);
+
+      // Drag the "New Text Document" icon to the "Recycle Bin"
+      const textDoc = await testdriver.find(
+        "New Text Document, new text document icon in the center of the desktop",
+      );
+      await textDoc.mouseDown();
+
+      const recycleBin = await testdriver.find(
+        "Recycle Bin, recycle bin icon in the top left corner of the desktop",
+      );
+      await recycleBin.mouseUp();
+
+      // Assert "New Text Document" icon is not on the Desktop
+      const result = await testdriver.assert(
+        'the "New Text Document" icon is not visible on the Desktop',
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});

package/examples/element-not-found.test.mjs

@@ -0,0 +1,26 @@
+/**
+ * TestDriver SDK - Element Not Found Test
+ * Tests that finding a non-existent element returns properly without timing out
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Element Not Found Test", () => {
+  it("should handle non-existent element gracefully without timing out", 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' });
+
+    //
+
+    // Try to find an element that definitely doesn't exist
+    const element = await testdriver.find(
+      "a purple unicorn dancing on the moon",
+    );
+
+    // Should return an element that is not found
+    expect(element.found()).toBe(false);
+    expect(element.coordinates).toBeNull();
+  }); // 90 second timeout for the test (should complete much faster)
+});
+

package/examples/exec-output.test.mjs

@@ -0,0 +1,59 @@
+/**
+ * TestDriver SDK - Exec Output Test (Vitest)
+ * Converted from: testdriver/acceptance/exec-output.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe.skip("Exec Output Test", () => {
+  it(
+    "should set date using PowerShell and navigate to calendar",
+    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' });
+
+      //
+      // Generate date in query string format
+      const queryString = await testdriver.exec(
+        "pwsh",
+        `
+$date = (Get-Date).AddMonths(1)
+Write-Output $date.ToString("yyyy-MM-dd")
+    `,
+        10000,
+      );
+
+      // Assert that the date is valid
+      const dateValidResult = await testdriver.assert(
+        `${queryString} is a valid date`,
+      );
+      expect(dateValidResult).toBeTruthy();
+
+      // Generate date in display format
+      const expectedDate = await testdriver.exec(
+        "pwsh",
+        `
+$date = (Get-Date).AddMonths(1)
+Write-Output $date.ToString("ddd MMM d yyyy")
+    `,
+        10000,
+      );
+
+      // Navigate to calendar with date parameter
+      await testdriver.focusApplication("Google Chrome");
+      await testdriver.pressKeys(["ctrl", "l"]);
+      await testdriver.type(
+        `https://teamup.com/ks48cf2135e7e080bc?view=d&date=${queryString}`,
+      );
+      await testdriver.pressKeys(["enter"]);
+
+      // Assert that the expected date shows
+      await testdriver.focusApplication("Google Chrome");
+      const result = await testdriver.assert(
+        `the text ${expectedDate} is visible on screen`,
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});

package/examples/exec-pwsh.test.mjs

@@ -0,0 +1,57 @@
+/**
+ * TestDriver SDK - Exec Shell Test (Vitest)
+ * Converted from: testdriver/acceptance/exec-shell.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe.skip("Exec PowerShell Test", () => {
+  it(
+    "should generate random email using PowerShell and enter it",
+    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' });
+
+      //
+      // Generate random email using PowerShell
+      const randomEmail = await testdriver.exec({
+        language: "pwsh",
+        code: `
+# Random email generator in PowerShell
+
+# Arrays of possible names and domains
+$firstNames = @("john", "jane", "alex", "chris", "sara", "mike", "lisa", "david", "emma", "ryan")
+$lastNames = @("smith", "johnson", "williams", "brown", "jones", "garcia", "miller", "davis", "martin", "lee")
+$domains = @("example.com", "testmail.com", "mailinator.com", "demo.org", "company.net")
+
+# Random selection
+$first = Get-Random -InputObject $firstNames
+$last = Get-Random -InputObject $lastNames
+$domain = Get-Random -InputObject $domains
+$number = Get-Random -Minimum 1 -Maximum 1000
+
+# Generate the email
+$email = "$first.$last$number@$domain".ToLower()
+
+# Output
+Write-Output "$email"
+    `,
+        timeout: 10000,
+      });
+
+      // Enter the email in username field
+      const usernameField = await testdriver.find(
+        "Username, input field for username",
+      );
+      await usernameField.click();
+      await testdriver.type(randomEmail);
+
+      // Assert that the username field shows a valid email address
+      const result = await testdriver.assert(
+        `the username field contains ${randomEmail} which is a valid email address`,
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});

package/examples/focus-window.test.mjs

@@ -0,0 +1,36 @@
+/**
+ * TestDriver SDK - Focus Window Test (Vitest)
+ * Converted from: testdriver/acceptance/focus-window.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Focus Window Test", () => {
+  it.skip(
+    "should click Microsoft Edge icon and focus Google Chrome",
+    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' });
+
+      //
+      // Show desktop
+      await testdriver.pressKeys(["winleft", "d"]);
+
+      // Click on the Microsoft Edge icon
+      const edgeIcon = await testdriver.find(
+        "a blue and green swirl icon on the taskbar representing Microsoft Edge",
+      );
+      await edgeIcon.click();
+
+      // Focus Google Chrome
+      await testdriver.focusApplication("Google Chrome");
+
+      // Assert Chrome is focused (implicit through successful focus)
+      const result = await testdriver.assert(
+        "Google Chrome is the focused application",
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});

package/examples/formatted-logging.test.mjs

@@ -0,0 +1,26 @@
+/**
+ * TestDriver SDK - Formatted Logging Demo
+ * Demonstrates nice Vitest-style formatted logs for Dashcam replay
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Formatted Logging Test", () => {
+  it("should demonstrate formatted logs in dashcam replay", 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' });
+
+    // Find and click - logs will be nicely formatted
+    const signInButton = await testdriver.find(
+      "Sign In, black button below the password field",
+    );
+    await signInButton.click();
+
+    // Assert - logs will show pass/fail with nice formatting
+    const result = await testdriver.assert(
+      "an error shows that fields are required",
+    );
+    expect(result).toBeTruthy();
+  });
+});

package/examples/hover-image.test.mjs

@@ -0,0 +1,52 @@
+/**
+ * TestDriver SDK - Hover Image Test (Vitest)
+ * Converted from: testdriver/acceptance/hover-image.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+/**
+ * Perform login flow for SauceLabs demo app
+ * @param {import('../../sdk.js').default} client - TestDriver client instance
+ * @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("Hover Image Test", () => {
+  it("should click on shopping cart icon and verify empty cart", async (context) => {
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, redraw: false });
+    
+    // provision.chrome() automatically calls ready() and starts dashcam
+    await testdriver.provision.chrome({
+      url: 'http://testdriver-sandbox.vercel.app/login'
+    });
+
+    // Perform login first
+    await performLogin(testdriver);
+
+    // Click on the shopping cart icon
+    await testdriver.focusApplication("Google Chrome");
+    const cartIcon = await testdriver.find(
+      "shopping cart icon next to the Cart text in the top right corner",
+    );
+
+    await cartIcon.click();
+
+    // Assert that you see an empty shopping cart
+    const result = await testdriver.assert("Your cart is empty");
+    expect(result).toBeTruthy();
+  });
+});

package/examples/hover-text-with-description.test.mjs

@@ -0,0 +1,56 @@
+/**
+ * TestDriver SDK - Hover Text With Description Test (Vitest)
+ * Converted from: testdriver/acceptance/hover-text-with-description.yaml
+ */
+
+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("Hover Text With Description Test", () => {
+  it("should add TestDriver Hat to cart and verify", 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);
+
+    // Click on "Add to Cart" under TestDriver Hat
+    const addToCartButton = await testdriver.find(
+      "Add to Cart, add to cart button under TestDriver Hat",
+    );
+    await addToCartButton.click();
+
+    // Click on the cart
+    const cartButton = await testdriver.find(
+      "Cart, cart button in the top right corner",
+    );
+    await cartButton.click();
+
+    // Assert the TestDriver Hat is in the cart
+    const result = await testdriver.assert("There is an item in the cart");
+    expect(result).toBeTruthy();
+  });
+});