@testdriverai/agent 7.8.0-canary.10

package/docs/v6/apps/chrome-extensions.mdx

@@ -0,0 +1,48 @@
+---
+title: Using TestDriver with Chrome Extensions
+sidebarTitle: "Chrome Extensions"
+description: "Test Chrome extensions with TestDriver"
+icon: "puzzle-piece"
+---
+
+import TestPrereqs from "/snippets/test-prereqs.mdx";
+
+<iframe
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/UUSXqAnau0Q"
+  title="Testing Chrome Extensions with TestDriver"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+# Testing Chrome extensions with TestDriver
+
+TestDriver can be used to test Chrome extensions. This guide provides an overview of how to set up and run tests for your Chrome extension using TestDriver.
+
+<TestPrereqs />
+
+## How do I test Chrome extensions?
+
+TestDriver provides a powerful solution for testing Chrome extensions. With our platform, you can easily create and run tests to ensure your extension functions as expected across different browsers and operating systems.
+
+## Getting started
+
+You can test a preinstalled extension or test by installing an extension. If the extension is in development mode, turn this on by checking the "Developer mode" checkbox in the Chrome extensions page. From there you can load the unpacked extension by selecting the folder where your extension is located. To download the files onto the VM if you are performing a test on cloud hosted runners, see the [Lifecycle](/guide/lifecycle) docs.
+
+## Sample test steps
+
+1. Load a the Chrome Web Store.
+2. Search for the extension you want to test.
+3. Click on the extension to open its details page.
+4. Click on the "Add to Chrome" button to install the extension.
+5. Wait for the installation to complete.
+6. Click the 'puzzle piece' icon to pin the extension to the toolbar.
+7. Click on the extension icon to open it.
+
+---
+
+## Now what?
+
+Once you have installed your extension, simply create a TestDriver test to test any functionality a user would use.

package/docs/v6/apps/desktop-apps.mdx

@@ -0,0 +1,93 @@
+---
+title: Using TestDriver with Desktop Apps
+sidebarTitle: "Desktop Apps"
+description: "TestDriver is designed to work with any desktop application, including Electron, Java, and .NET apps."
+icon: "desktop"
+---
+
+import TestPrereqs from "/snippets/test-prereqs.mdx";
+
+<iframe
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/DzgZf2b5XJs"
+  title="Assert 2+2=4"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+--- # Using TestDriver with Desktop Apps
+
+TestDriver is designed to work with any desktop application, including Electron, Java, and .NET apps. This guide provides an overview of how to use TestDriver with desktop applications, including installation, configuration, and running tests.
+
+<TestPrereqs />
+
+## Sample test steps
+
+1. **Launch the application**: Use the [`exec`](/commands/exec) command to launch the application. You can specify the path to the executable file and any command-line arguments needed to start the application.
+2. **Wait for the application to load**: Use the [`wait-for-text`](/commands/wait-for-text) command to wait for a specific text or element to appear in the application window. This ensures that the application is fully loaded before proceeding with the test.
+3. **Interact with the application**: Use the [`focus-application`](/commands/focus-application) command to bring the application window to the foreground. Then, use the [`hover-image`](/commands/hover-image) command to interact with specific elements in the application, such as buttons or text fields.
+4. **Perform actions**: Use the [`hover-image`](/commands/hover-image) command to click on buttons or enter text in input fields. You can also use the [`wait-for-text`](/commands/wait-for-text) command to verify that the expected output appears after performing an action.
+5. **Verify results**: Use the [`assert`](/commands/assert) command to check if the expected result matches the actual output. This step is crucial for validating the functionality of the application.
+
+## Supported desktop applications
+
+TestDriver supports a wide range of desktop applications, including:
+
+- Electron apps
+- Java apps
+- .NET apps
+- Native Windows applications
+- Native Mac applications
+- Native Linux applications
+- Any other desktop application that can be run on Windows, Mac, or Linux
+
+---
+
+## Installation
+
+To use TestDriver with desktop applications, no special setup is needed. Simply run the local agent to interact with applications on your local machine, or add instructions to `provision.yaml` to tell the runner to launch or install the application. Here is an example that performs a calculation on a calculator app:
+
+```yaml testdriver/lifecycle/provision.yaml
+version: 6.0.0
+steps:
+  - prompt: launch a calculator
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          start /B calc.exe
+          timeout /t 5
+      - command: wait-for-text
+        text: "calculator"
+        timeout: 30000
+```
+
+A `calculator.yaml` file might look like this:
+
+```yaml calculator.yaml
+version: 6.0.0
+steps:
+  - prompt: perform the operation 2 + 2 = on the calculator that is opened
+    commands:
+      - command: focus-application
+        name: galculator
+      - command: hover-image
+        description: button with number 2 on the calculator
+        action: click
+      - command: hover-image
+        description: plus button on the calculator
+        action: click
+      - command: hover-image
+        description: button with number 2 on the calculator
+        action: click
+      - command: hover-image
+        description: equals button on the calculator
+        action: click
+      - command: assert
+        expected: 4 is displayed as the result
+```
+
+## Conclusion
+
+TestDriver is a powerful tool for automating tests for desktop applications. With its support for a wide range of desktop platforms and its easy-to-use interface, you can quickly set up and run tests for your applications. Whether you are testing Electron apps, Java apps, or any other desktop application, TestDriver provides the tools you need to ensure your applications work as expected.

package/docs/v6/apps/mobile-apps.mdx

@@ -0,0 +1,26 @@
+---
+title: "Mobile Apps"
+sidebarTitle: "Mobile Apps"
+description: "Test mobile apps with TestDriver"
+icon: "mobile"
+---
+
+# Testing mobile apps with TestDriver
+
+## How do I test mobile apps?
+
+TestDriver provides a powerful solution for testing mobile apps. With our platform, you can easily create and run tests to ensure your mobile app functions as expected across different devices and operating systems.
+
+<Tip>
+  You will need to install a mobile emulator for your deployed tests or use a
+  device farm to test your mobile app.
+</Tip>
+
+## Gettins started
+
+To get started with testing mobile apps using TestDriver, follow these steps:
+
+1. **Follow our [quick start guide](/overview/quickstart) to set up your TestDriver account.**
+2. **Create a new test project** in your TestDriver dashboard.
+3. **Add your mobile emulator to the test settings.**
+4. **Add your mobile app URL** to the test settings.

package/docs/v6/apps/static-websites.mdx

@@ -0,0 +1,54 @@
+---
+title: "Testing Static Websites with TestDriver"
+sidebarTitle: "Static Websites"
+description: "Test static websites with TestDriver"
+icon: "browser"
+---
+
+<iframe
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/Jgj1sZRpDiU"
+  title="Form Filling with TestDriver"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+/>
+
+---
+
+# Testing Static Websites with TestDriver
+
+TestDriver provides a powerful solution for testing static websites. With our platform, you can easily create and run tests to ensure your static website functions as expected across different browsers and devices.
+
+## Getting started
+
+To get started with testing static websites using TestDriver, follow these steps:
+
+1. [**Follow our quick start guide to set up your TestDriver account.**](/getting-started/setup)
+2. **Create a new test project** in your TestDriver dashboard.
+3. **Add your static website URL** to the test settings.
+   It looks like this in the `provision.yaml` file:
+
+```yaml testdriver/lifecycle/provision.yaml
+version: 6.0.0
+steps:
+  - prompt: launch chrome
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "--start-maximized", "${TD_WEBSITE}"
+          exit
+      - command: wait-for-text
+        text: ${TD_WEBSITE}
+        timeout: 30000
+```
+
+Set the `TD_WEBSITE` environment variable to the URL of your static website. This will allow TestDriver to launch the browser and navigate to your website. You can do this by adding this `provision.yaml` file to your project or by simply using:
+
+```bash
+npx testdriverai@latest init
+```
+
+Running init will create the `provision.yaml` file for you and ask you which website to load with your test.

package/docs/v6/apps/tauri-apps.mdx

@@ -0,0 +1,361 @@
+---
+title: "Tauri Apps"
+sidebarTitle: "Tauri Apps"
+description: "Testing Tauri Apps with TestDriver"
+icon: "https://tauri.app/favicon.svg"
+---
+
+> [Tauri](https://tauri.app/) is a framework for building tiny, fast binaries for all major desktop and mobile platforms. Developers can integrate any frontend framework that compiles to HTML, JavaScript, and CSS for building their user experience while leveraging languages such as Rust, Swift, and Kotlin for backend logic when needed.
+>
+> \
+> – [https://tauri.app/start](https://tauri.app/start/)
+
+## Testing Tauri apps with TestDriver
+
+In this guide, we'll leverage [Playwright](https://playwright.dev/) and the [TestDriver Playwright SDK](/getting-started/playwright) to convert the [Tauri Quick Start](https://tauri.app/start/create-project/) to TestDriver's selectorless, Vision AI.
+
+<Info>View Source: https://github.com/testdriverai/demo-tauri-app</Info>
+
+### Requirements
+
+To start testing your Tauri app with TestDriver, you need the following:
+
+<AccordionGroup>
+  <Accordion title="Create a TestDriver account">
+    <Steps>
+      <Step title="Create a TestDriver Account">
+        You will need a [Free TestDriver Account](https://app.testdriver.ai/team) to get an API key.
+
+        <Card title="Sign Up for TestDriver" icon="user-plus" horizontal href="https://app.testdriver.ai/team">
+
+        </Card>
+      </Step>
+      <Step title="Set up your environment">
+        Copy your API key from [your TestDriver dashboard](https://app.testdriver.ai/team), and set it as an environment variable.
+
+        <Tabs>
+          <Tab title="macOS / Linux">
+            Export an environment variable on macOS or Linux systems:
+
+            ```bash
+            export TD_API_KEY="your_api_key_here"
+            ```
+          </Tab>
+          <Tab title="Windows">
+            Export an environment variable in PowerShell:
+
+            ```powershell
+            setx TD_API_KEY "your_api_key_here"
+            ```
+          </Tab>
+        </Tabs>
+      </Step>
+    </Steps>
+
+  </Accordion>
+  <Accordion title="Create a Tauri project">
+    <Note>
+      Follow Tauri's [Create a Project](https://tauri.app/start/create-project/)
+      guide.
+    </Note>
+  </Accordion>
+  <Accordion title="Create a Playwright project">
+    <Info>
+      This is a condensed version of [Playwright's Installation Instructions](https://playwright.dev/docs/intro).
+
+      **If you're new to Playwright, you should follow their guide first.**
+    </Info>
+    In your Tauri project, run:
+
+    <Tabs>
+      <Tab title="npm">
+        ```bash
+        npm init playwright@latest
+        ```
+      </Tab>
+      <Tab title="yarn">
+        ```bash
+        yarn create playwright
+        ```
+      </Tab>
+      <Tab title="pnpm">
+        ```bash
+        pnpm create playwright
+        ```
+      </Tab>
+    </Tabs>
+    Select the following options when prompted:
+
+    ```console
+    ✔ Do you want to use TypeScript or JavaScript?
+    > TypeScript
+    ✔ Where to put your end-to-end tests?
+    > tests
+    ✔ Add a GitHub Actions workflow? (y/N)
+    > N
+    ✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n)
+    > Y
+    ```
+
+  </Accordion>
+  <Accordion title="Install the TestDriver Playwright SDK">
+    `@testdriver.ai/playwright` is an AI-powered extension of `@playwright/test`.
+
+    <Tabs>
+      <Tab title="npm">
+        ```bash
+        npm install @testdriver.ai/playwright
+        ```
+      </Tab>
+      <Tab title="yarn">
+        ```bash
+        yarn add @testdriver.ai/playwright
+        ```
+      </Tab>
+      <Tab title="pnpm">
+        ```bash
+        pnpm add @testdriver.ai/playwright
+        ```
+      </Tab>
+    </Tabs>
+
+  </Accordion>
+</AccordionGroup>
+
+## Testing the Tauri Web App
+
+### Setup
+
+First, we need to modify the default Playwright configuration and our Tauri project to work together:
+
+<Steps>
+  <Step title="Configure Playwright to start the Tauri frontend">
+    In the `playwright.config.ts` file, we'll configure the [`webServer`](https://playwright.dev/docs/test-webserver)
+    to start the Tauri frontend for Playwright to test against:
+
+    ```typescript playwright.config.ts
+      /* Run your local dev server before starting the tests */
+      // [!code ++:8]
+      webServer: {
+        command: "npm run dev",
+        url: "http://localhost:1420",
+        reuseExistingServer: !process.env.CI,
+        env: {
+          VITE_PLAYWRIGHT: "true",
+        },
+      },
+    });
+    ```
+
+  </Step>
+  <Step title="Mock Tauri APIs">
+    Since we're testing the Tauri frontend, we need to [mock IPC Requests](https://tauri.app/develop/tests/mocking/)
+    to simulate `invoke` calls to the Rust backend:
+
+    ```html src/index.html
+    <body>
+      <div id="root"></div>
+      <!-- [!code ++:7] -->
+      <script type="module">
+        // This is set in playwright.config.ts to allow our tests to mock Tauri IPC `invoke` calls
+        if (import.meta.env.VITE_PLAYWRIGHT) {
+          const { mockIPC } = await import("@tauri-apps/api/mocks");
+          window.mockIPC = mockIPC;
+        }
+      </script>
+      <script type="module" src="/src/main.tsx"></script>
+    </body>
+    ```
+
+    We only need to do this once, as we'll be accessing `window.mockIPC` in our tests.
+
+  </Step>
+  <Step title="Create a new test file">
+    Create a new file (e.g. `tests/testdriver.spec.ts`) with:
+
+    ```typescript tests/testdriver.spec.ts
+    import type { mockIPC } from "@tauri-apps/api/mocks";
+    import { expect, test } from "@playwright/test";
+
+    test.beforeEach(async ({ page }) => {
+      await page.goto("http://localhost:1420");
+    });
+
+    test("should have title", async ({ page }) => {
+      await expect(page).toHaveTitle("Tauri + React + TypeScript");
+    });
+    ```
+
+  </Step>
+  <Step title="Run Playwright in UI Mode">
+    Now we're ready to run Playwright and start working on our tests:
+
+    <Tabs>
+      <Tab title="npm">
+        ```bash
+        npx playwright test --ui
+        ```
+      </Tab>
+      <Tab title="yarn">
+        ```bash
+        yarn playwright test --ui
+        ```
+      </Tab>
+      <Tab title="pnpm">
+        ```bash
+        pnpm exec playwright test --ui
+        ```
+      </Tab>
+    </Tabs>
+    ![Playwright UI Mode](https://playwright.dev/assets/ideal-img/ui-mode.4e54d6b.3598.png)
+
+    Click the <Icon icon="play" /> button to successfully run the tests in the UI.
+
+    <Tip>
+      Click the <Icon icon="eye" /> button to automatically re-run tests on save.
+    </Tip>
+
+  </Step>
+</Steps>
+
+### Usage
+
+#### Import the TestDriver Playwright SDK
+
+By changing **1 line**, we can add TestDriver's AI capabilities to Playwright:
+
+```typescript tests/testdriver.spec.ts
+import type { mockIPC } from "@tauri-apps/api/mocks";
+// [!code --]
+import { expect, test } from "@playwright/test";
+// [!code ++]
+import { expect, test } from "@testdriver.ai/playwright";
+
+// For type-safety of the mockIPC function
+declare global {
+  interface Window {
+    mockIPC: typeof mockIPC;
+  }
+}
+
+test.beforeEach(async ({ page }) => {
+  await page.goto("http://localhost:1420");
+});
+
+test("should have title", async ({ page }) => {
+  await expect(page).toHaveTitle("Tauri + React + TypeScript");
+});
+```
+
+Notice how we're able to continue using Playwright's API (`toHaveTitle`)
+with `@testdriver.ai/playwright`.
+
+The test continues to pass as before, so now we can update our test to use natural language instead of selectors.
+
+#### Assertions with `expect.toMatchPrompt`
+
+With Playwright, we would normally use a `getByRole` selector to assert the heading text:
+
+```typescript tests/example.spec.ts
+test("should have heading", async ({ page }) => {
+  await expect(
+    page.getByRole("heading", { name: "Installation" }),
+  ).toBeVisible();
+});
+```
+
+With TestDriver, we can use natural language with `toMatchPrompt` instead:
+
+```typescript tests/testdriver.spec.ts
+test("should have heading", async ({ page }) => {
+  // [!code --:3]
+  await expect(
+    page.getByRole("heading", { name: "Installation" }),
+  ).toBeVisible();
+  // [!code ++:1]
+  await expect(page).toMatchPrompt("Heading says 'Welcome to Tauri + React'");
+});
+```
+
+#### Agentic tests with `test.agent`
+
+With TestDriver, we can skip the test implementation **entirely** and let AI perform the test for us:
+
+<Steps>
+  <Step title="Mock the `greet` call">
+    First, we need to [`mock our invoke calls`](https://tauri.app/develop/tests/mocking/#ipc-requests),
+    since we're testing the frontend behavior and not our Tauri backend:
+
+    ```typescript tests/testdriver.spec.ts
+    test.beforeEach(async ({ page }) => {
+      await page.goto("http://localhost:1420");
+      // [!code ++:12]
+      await page.evaluate(() => {
+        // https://tauri.app/develop/tests/mocking/#mocking-commands-for-invoke
+        window.mockIPC((cmd, args) => {
+          switch (cmd) {
+            case "greet":
+              args = args as { name: string };
+              return `Hello, ${args.name}! You've been greeted from Rust!`;
+            default:
+              throw new Error(`Unsupported command: ${cmd}`);
+          }
+        });
+      });
+    });
+    ```
+
+  </Step>
+  <Step title="Add an Agentic Test">
+    Next, wrap a _prompt_ in `test.agent` to perform the test:
+
+    ```typescript tests/testdriver.spec.ts
+    test.describe("should greet with name", () => {
+      test.agent(`
+        - Enter the name "Tauri"
+        - Click the "Greet" button
+        - You should see the text "Hello, Tauri! You've been greeted from Rust!"
+      `);
+    });
+    ```
+
+  </Step>
+</Steps>
+
+#### Continued Reading
+
+[Learn more about TestDriver's Playwright SDK](/getting-started/playwright)
+
+## Testing the Tauri Desktop App
+
+We can use TestDriver and natural language to test our Tauri desktop app:
+
+<Steps>
+  <Step title="Run the Desktop App">
+    <Tabs>
+      <Tab title="npm">```bash npm run tauri dev ```</Tab>
+      <Tab title="yarn">```bash yarn tauri dev ```</Tab>
+      <Tab title="pnpm">```bash pnpm tauri dev ```</Tab>
+    </Tabs>
+  </Step>
+  <Step title="Continued Reading">
+    <Note>See [Desktop Apps](/apps/desktop-apps) for more information.</Note>
+  </Step>
+</Steps>
+
+## Testing the Tauri Mobile App
+
+We can use TestDriver and natural language to test our Tauri iOS app:
+
+<Steps>
+  <Step title="Run the Mobile App">
+    <Tabs>
+      <Tab title="npm">```bash npm run tauri ios dev ```</Tab>
+      <Tab title="yarn">```bash yarn tauri ios dev ```</Tab>
+      <Tab title="pnpm">```bash pnpm tauri ios dev ```</Tab>
+    </Tabs>
+  </Step>
+  <Step title="Continued Reading">
+    <Note>See [Mobile Apps](/apps/mobile-apps) for more information.</Note>
+  </Step>
+</Steps>