@testdriverai/agent 7.8.0-canary.10

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,31 @@
+/**
+ * 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";
+import { getDefaults } from "./config.mjs";
+
+describe("AI Test", () => {
+  it("should use ai to search for testdriver on Google", async (context) => {
+    const testdriver = TestDriver(context, { ...getDefaults(context) });
+    
+    // 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";
+import { getDefaults } from "./config.mjs";
+
+describe("Assert Test", () => {
+  it("should assert the testdriver login page shows", async (context) => {
+    const testdriver = TestDriver(context, {
+      ...getDefaults(context),
+    });
+    
+    // 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/chrome-extension.test.mjs

@@ -0,0 +1,97 @@
+/**
+ * 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";
+import { getDefaults } from "./config.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, { ...getDefaults(context), 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();
+
+    await testdriver.wait(2000); // wait for the popup to open
+
+    // 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, { ...getDefaults(context) });
+
+  //   // 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/config.mjs

@@ -0,0 +1,5 @@
+export const getDefaults = (context) => ({
+  ip: context.ip || process.env.TD_IP,
+  redraw: { enabled: false },
+  preview: 'web',
+});

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

@@ -0,0 +1,27 @@
+/**
+ * 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";
+import { getDefaults } from "./config.mjs";
+
+describe("Element Not Found Test", () => {
+  it("should handle non-existent element gracefully without timing out", async (context) => {
+    const testdriver = TestDriver(context, { ...getDefaults(context), 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,60 @@
+/**
+ * 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";
+import { getDefaults } from "./config.mjs";
+
+describe.skip("Exec Output Test", () => {
+  it(
+    "should set date using PowerShell and navigate to calendar",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), 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,58 @@
+/**
+ * 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";
+import { getDefaults } from "./config.mjs";
+
+describe.skip("Exec PowerShell Test", () => {
+  it(
+    "should generate random email using PowerShell and enter it",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), 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/findall-coffee-icons.test.mjs

@@ -0,0 +1,42 @@
+/**
+ * TestDriver SDK - FindAll Coffee Icons Test
+ * Loads a random icon grid and uses findAll() to locate and click all 4 coffee cup icons
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe("FindAll Coffee Icons", () => {
+  it("should find and click all 4 coffee cup icons", async (context) => {
+    const testdriver = TestDriver(context, {
+      ...getDefaults(context),
+      headless: true,
+    });
+
+    await testdriver.provision.chrome({
+      url: "https://v0-random-icon-grid.vercel.app/",
+    });
+
+    // Use findAll to locate all coffee cup icons on the page
+    const coffeeIcons = await testdriver.findAll("coffee cup icon, there are exactly 4 on the page");
+
+    // Log each icon's coordinates
+    console.log(`Found ${coffeeIcons.length} coffee icons:`);
+    coffeeIcons.forEach((icon, i) => {
+      console.log(`  Icon ${i + 1}: (${icon.x}, ${icon.y}) center=(${icon.centerX}, ${icon.centerY})`);
+    });
+
+    // Verify we found 3 or 4 coffee icons
+    expect(coffeeIcons.length).toBeGreaterThanOrEqual(3);
+    expect(coffeeIcons.length).toBeLessThanOrEqual(4);
+
+    // Click each coffee cup icon
+    for (const icon of coffeeIcons) {
+      await icon.click();
+    }
+
+    // Verify the selection count is displayed
+    await testdriver.assert("the page says 'Selected: 3 / 4' or 'Matched 4 of a kind!'");
+  });
+});

package/examples/focus-window.test.mjs

@@ -0,0 +1,37 @@
+/**
+ * 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";
+import { getDefaults } from "./config.mjs";
+
+describe("Focus Window Test", () => {
+  it.skip(
+    "should click Microsoft Edge icon and focus Google Chrome",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), 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,27 @@
+/**
+ * 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";
+import { getDefaults } from "./config.mjs";
+
+describe("Formatted Logging Test", () => {
+  it("should demonstrate formatted logs in dashcam replay", async (context) => {
+    const testdriver = TestDriver(context, { ...getDefaults(context), 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,53 @@
+/**
+ * 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";
+import { getDefaults } from "./config.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, { ...getDefaults(context) });
+    
+    // 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,57 @@
+/**
+ * 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";
+import { getDefaults } from "./config.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, {
+      ...getDefaults(context),
+      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();
+  });
+});

package/examples/hover-text.test.mjs

@@ -0,0 +1,28 @@
+/**
+ * TestDriver SDK - Hover Text Test (Vitest)
+ * Converted from: testdriver/acceptance/hover-text.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe("Hover Text Test", () => {
+  it("should click Sign In and verify error message", async (context) => {
+    const testdriver = TestDriver(context, { ...getDefaults(context) });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    // Click on Sign In button using new find() API
+
+    const signInButton = await testdriver.find(
+      "Sign In, black button below the password field",
+    );
+    await signInButton.click();
+
+    // Assert that an error shows that fields are required
+    const result = await testdriver.assert(
+      "an error shows that fields are required",
+    );
+    expect(result).toBeTruthy();
+  });
+});