testdriverai 6.2.2 → 7.0.0

package/docs/v7/commands/wait-for-image.mdx

@@ -0,0 +1,54 @@
+---
+title: "wait-for-image"
+sidebarTitle: "wait-for-image"
+description: "Wait until an image matching the description is detected on the screen."
+icon: "clock-three-thirty"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/wait-for-image-replay.mdx";
+import Example from "/snippets/tests/wait-for-image-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `wait-for-image` command waits until the specified image is detected on the screen. This is useful for ensuring that visual elements are present before proceeding with the next steps in a test.
+
+## Arguments
+
+|   Argument    |   Type    | Description                                                                                                       |
+| :-----------: | :-------: | :---------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`  | A description of the image.                                                                                       |
+|   `timeout`   | `number`  | (Optional) The duration in milliseconds to wait for the image to appear. Default is `10000` (10 seconds).         |
+|   `invert`    | `boolean` | (Optional) If set to `true`, the command will wait until the specified image is NOT detected. Default is `false`. |
+
+## Example usage
+
+```yaml
+command: wait-for-image
+description: trash icon
+timeout: 5000
+```
+
+## Protips
+
+- Use clear and concise descriptions for the image to improve detection accuracy.
+- Adjust the `timeout` value based on the expected load time of the image to avoid unnecessary delays.
+
+<Tip>
+  If you are unable to land on an accurate description or experiencing flaky
+  results, try to upload the image to [chatgpt](https://chatgpt.com) and ask it
+  to describe the image and use the generated `description` to get better
+  accuracy and determinism.
+</Tip>
+
+## Gotchas
+
+- If the image doesn't appear within the specified `timeout`, the command will fail.
+- Ensure the description accurately represents the image to avoid detection issues.
+
+---
+
+The `wait-for-image` command is ideal for synchronizing tests with visual elements that may take time to load.

package/docs/v7/commands/wait-for-text.mdx

@@ -0,0 +1,48 @@
+---
+title: "wait-for-text"
+sidebarTitle: "wait-for-text"
+description: "Wait until the specified text is detected on the screen."
+icon: "clock-nine"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/wait-for-text-replay.mdx";
+import Example from "/snippets/tests/wait-for-text-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `wait-for-text` command waits until the specified text is detected on the screen. This is useful for ensuring that textual elements are present before proceeding with the next steps in a test.
+
+## Arguments
+
+| Argument  |   Type    | Description                                                                                                      |
+| :-------: | :-------: | :--------------------------------------------------------------------------------------------------------------- |
+|  `text`   | `string`  | The text to find on the screen.                                                                                  |
+| `timeout` | `number`  | (Optional) The duration in milliseconds to wait for the text to appear. Default is `5000` (5 seconds).           |
+| `method`  |  `enum`   | (Optional) The matching algorithm to use. Possible values are `ai` and `turbo`. Default is `turbo`               |
+| `invert`  | `boolean` | (Optional) If set to `true`, the command will wait until the specified text is NOT detected. Default is `false`. |
+
+## Example usage
+
+```yaml
+command: wait-for-text
+text: Copyright 2024
+timeout: 5000
+```
+
+## Protips
+
+- Use unique and specific text to improve detection accuracy.
+- Adjust the `timeout` value based on the expected load time of the text to avoid unnecessary delays.
+
+## Gotchas
+
+- If the text doesn't appear within the specified `timeout`, the command will fail.
+- Ensure the text matches exactly, as variations in font size, style, or screen resolution may affect detection accuracy.
+
+---
+
+The `wait-for-text` command is ideal for synchronizing tests with textual elements that may take time to load.

package/docs/v7/commands/wait.mdx

@@ -0,0 +1,45 @@
+---
+title: "wait"
+sidebarTitle: "wait"
+description: "Pause the execution of the script for a specified duration."
+icon: "clock"
+"mode": "wide"
+---
+
+import Replay from "/snippets/tests/wait-replay.mdx";
+import Example from "/snippets/tests/wait-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `wait` command pauses the execution of the script for a specified number of milliseconds before continuing. This is useful for adding delays between commands or waiting for certain conditions to stabilize.
+
+## Arguments
+
+| Argument  | Type     | Description                           |
+| --------- | -------- | ------------------------------------- |
+| `timeout` | `number` | The duration in milliseconds to wait. |
+
+## Example usage
+
+```yaml
+command: wait
+timeout: 5000
+```
+
+## Protips
+
+- Use the `wait` command to handle timing issues, such as waiting for animations to complete or elements to load.
+- Avoid using excessively long timeouts to keep tests efficient.
+
+## Gotchas
+
+- Overusing the `wait` command can slow down test execution. Use it only when necessary.
+- Ensure the timeout value is appropriate for the scenario to avoid unnecessary delays.
+
+## Notes
+
+- The `wait` command is ideal for introducing controlled pauses in your test scripts.
+- Whenever you are waiting for something to load, use the [wait-for-text](/commands/wait-for-text) or [wait-for-image](/commands/wait-for-image) commands instead to make the test more efficient.

package/docs/v7/getting-started/quickstart.mdx

@@ -0,0 +1,199 @@
+---
+title: "SDK Quickstart"
+sidebarTitle: "Quickstart"
+description: "Get started with the TestDriver JavaScript SDK in minutes."
+icon: "gauge-high"
+mode: "wide"
+---
+
+TestDriver v7 introduces a powerful JavaScript SDK that lets you write tests in JavaScript/TypeScript instead of YAML. This gives you full programmatic control over your tests with IDE autocomplete, type safety, and all the benefits of modern development tooling.
+
+<Steps>
+  <Step title="Create a TestDriver Account">
+      
+  You will need a [TestDriver Pro](https://app.testdriver.ai/team) account ($20/month) to get an API key. 
+    
+    <Card
+      title="Sign Up for TestDriver"
+      icon="user-plus"
+      href="https://app.testdriver.ai/team"
+    />
+
+  </Step>
+  
+  <Step title="Install TestDriver SDK">
+      
+    Install the TestDriver SDK package in your project:
+    
+    ```bash
+    npm install testdriverai
+    ```
+    
+    Or using other package managers:
+    
+    <Tabs>
+      <Tab title="npm">
+        ```bash
+        npm install testdriverai
+        ```
+      </Tab>
+      <Tab title="yarn">
+        ```bash
+        yarn add testdriverai
+        ```
+      </Tab>
+      <Tab title="pnpm">
+        ```bash
+        pnpm add testdriverai
+        ```
+      </Tab>
+    </Tabs>
+
+  </Step>
+  
+  <Step title="Set up your environment">
+      
+    Copy your API key from [the TestDriver dashboard](https://app.testdriver.ai/team), and set it as an environment variable.
+    
+    <Tabs>
+      <Tab title="macOS / Linux">
+        ```bash
+        export TD_API_KEY="your_api_key_here"
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        $env:TD_API_KEY="your_api_key_here"
+        ```
+      </Tab>
+      <Tab title="Windows (CMD)">
+        ```cmd
+        set TD_API_KEY=your_api_key_here
+        ```
+      </Tab>
+    </Tabs>
+
+  </Step>
+  
+  <Step title="Write your first test">
+      
+    Create a new test file (e.g., `login.test.mjs`):
+
+    ```javascript login.test.mjs
+    import { beforeAll, afterAll, describe, it, expect } from 'vitest';
+    import TestDriver from 'testdriverai';
+
+    describe('Login Test', () => {
+      let testdriver;
+
+      beforeAll(async () => {
+        // Create a new TestDriver client
+        client = new TestDriver(process.env.TD_API_KEY, {
+          os: 'windows',        // 'windows' or 'linux'
+          resolution: '1366x768'
+        });
+        
+        // Authenticate and connect to a sandbox
+        await testdriver.auth();
+        await testdriver.connect({ newSandbox: true });
+      });
+
+      afterAll(async () => {
+        // Clean up after tests
+        await testdriver.disconnect();
+      });
+
+      it('should verify the login page is displayed', async () => {
+        // Use AI to assert the login page is visible
+        const result = await testdriver.assert('the TestDriver.ai Sandbox login page is displayed');
+        expect(result).toBeTruthy();
+      });
+
+      it('should enter username and password', async () => {
+        // Focus the browser
+        await testdriver.focusApplication('Google Chrome');
+        
+        // Find and click the username field
+        const usernameField = await testdriver.find('Username input field');
+        await usernameField.click();
+        await testdriver.type('standard_user');
+        
+        // Tab to password field and enter password
+        await testdriver.pressKeys(['tab']);
+        await testdriver.type('secret_sauce');
+        
+        // Verify the credentials were entered
+        const result = await testdriver.assert('username field contains "standard_user"');
+        expect(result).toBeTruthy();
+      });
+    });
+    ```
+
+  </Step>
+  
+  <Step title="Run your test">
+    
+    Run your test using Vitest (or your preferred test runner):
+
+    ```bash
+    npx vitest run login.test.mjs
+    ```
+    
+    TestDriver will:
+    1. Authenticate with the API
+    2. Spin up a virtual machine sandbox
+    3. Execute your test steps
+    4. Return results to your test runner
+    
+    <Tip>
+      The SDK automatically connects to TestDriver's cloud infrastructure. You can also [self-host](/getting-started/self-hosting) the sandbox environment.
+    </Tip>
+
+  </Step>
+</Steps>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="API Reference"
+    icon="book"
+    href="/v7/api/client"
+  >
+    Explore all available SDK methods and options
+  </Card>
+  
+  <Card
+    title="Element Finding"
+    icon="search"
+    href="/v7/api/elements"
+  >
+    Learn how to locate and interact with UI elements
+  </Card>
+  
+  <Card
+    title="Sandbox Management"
+    icon="server"
+    href="/v7/api/sandbox"
+  >
+    Manage sandbox lifecycle and connections
+  </Card>
+  
+  <Card
+    title="Assertions & Testing"
+    icon="check"
+    href="/v7/api/assertions"
+  >
+    Use AI-powered assertions in your tests
+  </Card>
+</CardGroup>
+
+## Key Differences from v6
+
+The v7 SDK offers several advantages over the YAML-based approach:
+
+- **Type Safety**: Full TypeScript support with IntelliSense
+- **Programmatic Control**: Use variables, loops, and functions
+- **Better Debugging**: Stack traces point to your actual code
+- **Integration**: Works with any JavaScript test framework (Vitest, Jest, Mocha, etc.)
+- **Flexibility**: Combine TestDriver with other testing tools seamlessly