testdriverai 6.2.2 → 7.0.0

package/docs/v7/api/type.mdx

@@ -0,0 +1,314 @@
+---
+title: "type()"
+sidebarTitle: "type"
+description: "Type text into focused input fields"
+icon: "keyboard"
+---
+
+## Overview
+
+Type text or numbers into the currently focused input field with optional delay between keystrokes.
+
+## Syntax
+
+```javascript
+await testdriver.type(text, delay)
+```
+
+## Parameters
+
+<ParamField path="text" type="string | number" required>
+  Text to type (can be a string or number)
+</ParamField>
+
+<ParamField path="delay" type="number" default="250">
+  Delay between keystrokes in milliseconds
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Examples
+
+### Basic Typing
+
+```javascript
+// Type text
+await testdriver.type('hello@example.com');
+
+// Type numbers
+await testdriver.type(12345);
+
+// Type with custom delay
+await testdriver.type('slow typing', 500); // 500ms between each character
+```
+
+### Form Filling
+
+```javascript
+// Focus field and type
+const emailField = await testdriver.find('email input');
+await emailField.click();
+await testdriver.type('user@example.com');
+
+// Tab to next field and type
+await testdriver.pressKeys(['tab']);
+await testdriver.type('John Doe');
+
+// Type password
+await testdriver.pressKeys(['tab']);
+await testdriver.type('MySecureP@ssw0rd');
+```
+
+### Clearing and Replacing Text
+
+```javascript
+const searchBox = await testdriver.find('search input');
+await searchBox.click();
+
+// Clear existing text
+await testdriver.pressKeys(['ctrl', 'a']); // Select all
+await testdriver.type('new search query');
+```
+
+## Best Practices
+
+<Check>
+  **Focus the field first**
+  
+  Always click the input field or navigate to it before typing:
+  
+  ```javascript
+  const input = await testdriver.find('username input');
+  await input.click();
+  await testdriver.type('testuser');
+  ```
+</Check>
+
+<Check>
+  **Use Tab for navigation**
+  
+  Navigate between fields using Tab instead of clicking each one:
+  
+  ```javascript
+  const firstField = await testdriver.find('first name');
+  await firstField.click();
+  await testdriver.type('John');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('Doe');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('john@example.com');
+  ```
+</Check>
+
+<Check>
+  **Clear fields before typing**
+  
+  Clear existing content to avoid appending:
+  
+  ```javascript
+  const input = await testdriver.find('search field');
+  await input.click();
+  await testdriver.pressKeys(['ctrl', 'a']); // Select all
+  await testdriver.type('new search');
+  ```
+</Check>
+
+<Warning>
+  **Field must be focused**
+  
+  Typing will only work if an input field is currently focused. If no field is focused, the text may be lost or trigger unexpected keyboard shortcuts.
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Login Forms">
+    ```javascript
+    await testdriver.focusApplication('Google Chrome');
+    
+    const usernameField = await testdriver.find('username input');
+    await usernameField.click();
+    await testdriver.type('testuser@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MyP@ssword123');
+    
+    await testdriver.pressKeys(['enter']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Search Fields">
+    ```javascript
+    const searchBox = await testdriver.find('search input');
+    await searchBox.click();
+    await testdriver.type('laptop computers');
+    await testdriver.pressKeys(['enter']);
+    
+    // Wait for results
+    await new Promise(r => setTimeout(r, 2000));
+    ```
+  </Accordion>
+  
+  <Accordion title="Multi-Field Forms">
+    ```javascript
+    // First field
+    const nameField = await testdriver.find('full name input');
+    await nameField.click();
+    await testdriver.type('Jane Smith');
+    
+    // Navigate with Tab
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('jane.smith@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('+1-555-0123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('123 Main Street');
+    ```
+  </Accordion>
+  
+  <Accordion title="Text Editors">
+    ```javascript
+    const editor = await testdriver.find('text editor area');
+    await editor.click();
+    
+    await testdriver.type('# My Document', 100);
+    await testdriver.pressKeys(['enter', 'enter']);
+    await testdriver.type('This is the first paragraph.', 50);
+    ```
+  </Accordion>
+  
+  <Accordion title="Numeric Input">
+    ```javascript
+    const quantityField = await testdriver.find('quantity input');
+    await quantityField.click();
+    
+    // Clear field
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Type number
+    await testdriver.type(5);
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Typing Speed
+
+Adjust the delay parameter based on your needs:
+
+```javascript
+// Fast typing (100ms delay)
+await testdriver.type('quick entry', 100);
+
+// Normal typing (250ms - default)
+await testdriver.type('standard speed');
+
+// Slow typing (500ms delay) - useful for fields with live validation
+await testdriver.type('slow and steady', 500);
+
+// Very slow (1000ms delay) - for problematic fields
+await testdriver.type('one by one', 1000);
+```
+
+<Note>
+  Some applications with live validation or autocomplete may require slower typing speeds to avoid race conditions.
+</Note>
+
+## Special Characters
+
+```javascript
+// Email addresses
+await testdriver.type('user@example.com');
+
+// URLs
+await testdriver.type('https://example.com/path?query=value');
+
+// Passwords with special characters
+await testdriver.type('P@ssw0rd!#$%');
+
+// Paths
+await testdriver.type('C:\\Users\\Documents\\file.txt');
+
+// Multi-line text (use pressKeys for Enter)
+await testdriver.type('Line 1');
+await testdriver.pressKeys(['enter']);
+await testdriver.type('Line 2');
+```
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it, expect } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Form Filling with Type', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect({ newSandbox: true });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should fill out registration form', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Email field
+    const emailField = await testdriver.find('email input field');
+    await emailField.click();
+    await testdriver.type('john.doe@example.com');
+    
+    // Tab through form fields
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('John');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MySecureP@ssword123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MySecureP@ssword123'); // Confirm password
+    
+    // Verify fields were filled
+    const result = await testdriver.assert('all form fields are filled');
+    expect(result).toBeTruthy();
+  });
+
+  it('should update search query', async () => {
+    const searchBox = await testdriver.find('search input');
+    await searchBox.click();
+    
+    // Type initial search
+    await testdriver.type('laptops');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Update search
+    await searchBox.click();
+    await testdriver.pressKeys(['ctrl', 'a']); // Select all
+    await testdriver.type('gaming laptops');
+    await testdriver.pressKeys(['enter']);
+    
+    // Verify new search
+    await testdriver.assert('search results for "gaming laptops" are shown');
+  });
+});
+```
+
+## Related Methods
+
+- [`pressKeys()`](/v7/api/pressKeys) - Press keyboard keys and shortcuts
+- [`find()`](/v7/api/find) - Locate input fields
+- [`click()`](/v7/api/click) - Focus input fields

package/docs/v7/commands/assert.mdx

@@ -0,0 +1,45 @@
+---
+title: "assert"
+sidebarTitle: "assert"
+description: "Validate conditions during a test using the assert command."
+icon: "check"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/assert-replay.mdx";
+import Example from "/snippets/tests/assert-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `assert` command validates that a specific condition is true. It ensures that a task completed successfully by checking the screen for the expected outcome. If the condition isn't met, the test will fail.
+
+## Arguments
+
+| Argument | Type      | Description                                                                                                        |
+| -------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `expect` | `string`  | The condition to check. This should describe what you expect to see on the screen.                                 |
+| `async`  | `boolean` | (Optional) If set to `true`, the test will continue without waiting for the assertion to pass. Default is `false`. |
+| `invert` | `boolean` | (Optional) If set to `true`, will fail if the assertion passes.                                                    |
+
+## Example usage
+
+```yaml
+command: assert
+expect: the video is playing
+```
+
+### Example with `async`
+
+```yaml
+command: assert
+expect: There is no error message
+async: true
+```
+
+## Notes
+
+- Use `async: true` to speed up tests by allowing non-blocking assertions. However, the test will still fail if the condition isn't met.
+- Ensure the `expect` string clearly describes the condition to avoid ambiguity.

package/docs/v7/commands/exec.mdx

@@ -0,0 +1,282 @@
+---
+title: "exec"
+sidebarTitle: "exec"
+description: "Execute custom shell or Node.js scripts within your tests."
+icon: "code"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/exec-shell-replay.mdx";
+import Example from "/snippets/tests/exec-shell-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `exec` command allows you to execute custom Node.js scripts within your TestDriver tests. This is useful for tasks like generating dynamic data, interacting with APIs, or performing custom logic during a test. The output of the script can be stored in a variable for use in subsequent steps. It's important to note that the output from `exec` must be a `string`.
+
+## Arguments
+
+| Argument |   Type   | Description                                                                                                                                                                        |
+| :------: | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|  `lang`  | `string` | The language of the script to execute. Supported values are `pwsh` and `js`.                                                                                                       |
+| `output` | `string` | The variable name to store the result of the script. This variable can be accessed as `${OUTPUT.<var>}` in future steps.                                                           |
+|  `code`  | `string` | The script to execute on Windows systems. For `js`, the script must define the output as `result`.                                                                                 |
+| `silent` | `string` | Defaults to `false`. The command will print the output of the script. This is useful for suppressing unnecessary or private output in the test logs and it's useful for debugging. |
+
+## Example usage
+
+This example demonstrates how to use the `exec` command to generate a TOTP (Time-based One-Time Password) using the `totp-generator` library.
+
+```yaml otp-generator.yaml
+version: 6.0.0
+steps:
+  - commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          npm install totp-generator
+      - command: exec
+        lang: js
+        output: totp
+        code: |
+          const { TOTP } = require("totp-generator");
+          let otp = TOTP.generate("JBSWY3DPEB3W64TMMQQQ").otp;
+          console.log(otp);
+          result = otp;
+      - command: type
+        text: ${OUTPUT.totp}
+```
+
+## Additional details
+
+- Supported `lang` values are `js` or `pwsh`:
+  - `js` code is executed in a Node.js [VM](https://nodejs.org/api/vm.html) internally on the host machine (for example the machine where your CI/CD runs, or your computer if using the local agent).
+  - `pwsh` code is executed in the shell on target runner (which can be the cloud runner, local sandbox, or local machine, depending on where you run your tests).
+    - **Note:** You can also use `pwsh` in [lifecycle](/guide/lifecycle) scripts to install npm packages if you need them.
+    - Otherwise, the `pwsh` code can be used within test steps to launch applications or perform simple commands (like writing text to a file on the machine to perform a simple file upload).
+- The `output`argument is assigned automatically by setting `result = somestringvalue` in the script you run.
+
+## Protips
+
+- The `result` variable is already available in your script, overwrite it to store the output as shown in the examples.
+- Do any handling of arrays or nested objects within your `js` script:
+  - ✅ `result = users[1].profile.firstName`
+  - ✅ `result = data.length > 0 ? data[0].userEmail : 'no user found'` if no data is found the value of output will be `null`
+  - ✅ `result = someTestUserEmail`
+  - ✅ `result = someTextToAssert`
+  - ✅ `result = someDescriptionOfAnImageToScrollTo`
+- Don't try to pass any non-string values to `output`:
+  - ❌ `result = [...users, ...values]`
+  - ❌ `result = {name: "Dale Earnhardt", starts: 676, wins: 76}`
+  - ❌ `result = [{user1: ...}, {user2: ...}]`
+
+---
+
+## Ways to use `exec`
+
+Here is an example using both `pwsh` and `js` contexts within a `prerun.yaml` script which creates a temporary email account and automatically clicks links found in received emails.
+
+```yaml ./lifecycle/prerun.yaml [expandable]
+version: 6.0.0
+steps:
+  - commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          npm install @sendgrid/mail
+      - command: exec
+        lang: js
+        output: accountData
+        code: |
+          const Mailjs = require("@cemalgnlts/mailjs");
+          const mailjs = new Mailjs();
+          let account = await mailjs.createOneAccount()
+          console.log("Account created:", account);
+          result = JSON.stringify(account.data)
+      - command: exec
+        lang: js
+        output: emailAddress
+        code: |
+          const accountData = ${OUTPUT.accountData};
+          result = accountData.username
+  - prompt: Enter the generated email into the email field
+    commands:
+      - command: hover-text
+        text: standard_user
+        description: email input field label
+        action: click
+      - command: type
+        text: ${OUTPUT.emailAddress}
+  - prompt: Wait for an email, extract links, and open each link
+    commands:
+      - command: exec
+        lang: js
+        code: |
+          const Mailjs = require("@cemalgnlts/mailjs");
+          const { JSDOM } = require('jsdom'); // To parse HTML and extract links
+
+          const accountData = ${OUTPUT.accountData};
+
+          const getLatestEmailAndClickLinks = async () => {
+            try {
+              // Initialize the Mailjs client
+              const mailjs = new Mailjs();
+
+              // Login to your account
+              await mailjs.login(accountData.username, accountData.password);
+
+              // Fetch list of messages
+              const messages = await mailjs.getMessages();
+
+              if (messages.length === 0) {
+                console.log('No emails found.');
+                return;
+              }
+
+              // Assuming the latest email is the first one in the list
+              const latestMessage = messages[0];
+
+              // Fetch the full details of the latest email
+              const fullMessage = await mailjs.getMessage(latestMessage.id);
+
+              console.log('Latest Email Details:', fullMessage);
+
+              // Parse the HTML content to extract links
+              const dom = new JSDOM(fullMessage.html);
+              const links = Array.from(dom.window.document.querySelectorAll('a')).map(a => a.href);
+
+              console.log('Found Links:', links);
+
+              // Click (fetch) every link using native fetch
+              for (const link of links) {
+                try {
+                  const response = await fetch(link);
+                  console.log('Clicked ${link}: ${response.status}');
+                } catch (linkError) {
+                  console.error('Error clicking ${link}:', linkError);
+                }
+              }
+
+            } catch (error) {
+              console.error('Error fetching latest email or clicking links:', error);
+            }
+          };
+
+          getLatestEmailAndClickLinks();
+```
+
+### Using `exec` pwsh commands in a test file
+
+In a test file, you can use the `pwsh` context directly:
+
+```yaml calculator.yaml highlight={5-8} [expandable]
+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
+  - prompt: performing 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
+```
+
+### One more option
+
+You can also save reusable snippets (like launching the calculator) to be inserted into a script later with the [`run`](/commands/run) command. That version would look something like this:
+
+```yaml snippets/launch-calculator.yaml [expandable]
+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
+```
+
+Then in the test:
+
+```yaml calculator.yaml highlight={5-6} [expandable]
+version: 6.0.0
+steps:
+  - prompt: launch a calculator
+    commands:
+      - command: run
+        file: snippets/launch-calculator.yaml
+  - prompt: performing 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
+```
+
+### Don't try to run `js` within a test field
+
+This example will fail at runtime, so don't try to execute `js` context directly in a test file. Remember - use this in `prerun` to setup your test!
+
+```yaml badtestfile.yaml [expandable]
+version: 6.0.0
+commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          npm install -g axios json2csv
+  - prompt: fetch user data from API
+    commands:
+      - command: exec
+        output: user
+        lang: js
+        code: |
+          const axios = require('axios');
+          const { Parser } = require('json2csv');
+          const fs = require('fs');
+
+          const response = await axios.get('https://jsonplaceholder.typicode.com/users');
+          const parser = new Parser();
+          const csv = parser.parse(response.data);
+          fs.writeFileSync('users.csv', csv);
+          const user = response.data[0].name;
+          result = user;
+          console.log('username', user);
+    ...
+```
+
+This example will produce errors in the TestDriver output or CLI since the runner won't have access to the Node.js VM context.

package/docs/v7/commands/focus-application.mdx

@@ -0,0 +1,44 @@
+---
+title: "focus-application"
+sidebarTitle: "focus-application"
+description: "Bring a specific application window to the foreground."
+icon: "window-restore"
+mode: "wide"
+---
+
+## Description
+
+The `focus-application` command displays a specific application window to the foreground. This ensures that subsequent commands interact with the correct application during a test.
+
+## Arguments
+
+| Argument | Type     | Description                                                                             |
+| -------- | -------- | --------------------------------------------------------------------------------------- |
+| `name`   | `string` | The name of the application to focus. This should match the application's display name. |
+
+## Example usage
+
+```yaml
+command: focus-application
+name: Google Chrome
+```
+
+## Protips
+
+- Ensure the application name matches the exact name displayed in your operating system's task manager.
+- Use this command at the start of a test or before interacting with an application to avoid focus-related issues.
+
+<Note>
+If the specified application isn't running, the command will fail. Ensure the application is open before using this command.
+For example, to launch chrome try using the exec command:
+
+```yaml
+- command: exec
+  lang: pwsh
+  code: start chrome
+```
+
+</Note>
+## Notes
+
+- The `focus-application` command is useful for multi-application workflows where you need to switch between different apps during a test.