testdriverai 6.0.23 → 6.0.24-canary.fffd04a.0

package/docs/getting-started/vscode.mdx

@@ -5,8 +5,6 @@ description: "Comprehensive guide to installing and setting up TestDriver for VS
 icon: "file-code"
 ---
 
-import YmlWarning from "/snippets/yml-warning.mdx";
-
 <Card
   title="Get the VS Code Extension"
   icon="link"
@@ -34,9 +32,7 @@ import YmlWarning from "/snippets/yml-warning.mdx";
     npx testdriverai@latest
     ```
 
-    Once started, you can use commands like `/try`, `/undo`, and `/save` to interactively build and test your flows.
-
-    <YmlWarning />
+    Once started, you can use commands like `/explore`, `/run`, and `/save` to interactively build and test your flows.
 
   </Step>
   <Step title="Define Your Test Steps" stepNumber={3}>
@@ -58,13 +54,14 @@ import YmlWarning from "/snippets/yml-warning.mdx";
     - command: type
       text: testdriverai
     - command: press-keys
-      keys: [enter]
+      keys:
+        - enter
     ```
 
   </Step>
   <Step title="Refine and Save Your Test" stepNumber={4}>
-    - Use `/undo` to remove the last step if needed.
     - Save your test with `/save` to generate a reusable YAML file.
+    - Use `/run` to run the test.
   </Step>
   <Step title="Run Saved Tests" stepNumber={5}>
     Once saved, you can run your test file anytime:

package/docs/guide/assertions.mdx

@@ -106,10 +106,8 @@ Assertions can be combined with navigation and interaction commands to validate
 
 ### Example: Login workflow with assertions
 
-#### TestDriver command:
-
-```yaml
-version: 4.2.18
+```yaml login.yaml highlight={12,13, 36, 37}
+version: 6.0.0
 steps:
   - prompt: Open the homepage
     commands:

package/docs/guide/authentication.mdx

@@ -1,12 +1,10 @@
 ---
-title: "Authentication in TestDriver"
+title: "Authentication"
 sidebarTitle: "Authentication"
-description: "Learn how to securely handle authentication workflows in TestDriver using GitHub Actions."
-icon: "fingerprint"
+description: "Learn how to handle authentication workflows in TestDriver using GitHub Actions."
+icon: "key"
 ---
 
-import GitignoreWarning from "/snippets/gitignore-warning.mdx";
-
 This guide explains how to handle **authentication workflows** in **TestDriver** using GitHub Actions. It covers securely passing credentials (for example, usernames and passwords) to the TestDriver action and using them in both the `prerun` script and test files. Save these locally in your `.env` file and use them in CI as GitHub secrets.
 
 <GitignoreWarning />
@@ -27,7 +25,7 @@ This guide explains how to handle **authentication workflows** in **TestDriver**
 
 - Dynamically reference credentials in the `prerun` script or test files to perform authentication steps.
 
-store credentials in GitHub secrets
+## Step 1: Store credentials in GitHub secrets
 
 1. Navigate to your repository's **Settings** > **Secrets and variables** > **Actions**.
 2. Add the following secrets:
@@ -45,7 +43,7 @@ Secrets are passed to the workflow using the `secrets` context. They can be supp
 
 ### Example GitHub Actions workflow (adapt for your CI/CD platform)
 
-```yaml
+```yaml workflows/td-auth.yml focus={17-24}
 name: TestDriver / Authentication
 
 on:
@@ -63,7 +61,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run Authentication Test
-        run: npx testdriverai@latest run testdriver/authentication.yaml --headless
+        run: npx testdriverai@latest run testdriver/authentication.yaml
         env:
           TD_API_KEY: ${{ secrets.TD_API_KEY }}
           TD_USERNAME: ${{ secrets.TD_USERNAME }}
@@ -79,8 +77,8 @@ Secrets can be referenced in the test file using placeholders (for example, `${T
 
 ### Example test file:
 
-```yaml
-version: 4.2.18
+```yaml login.yaml highlight={9, 10, 15, 16}
+version: 6.0.0
 steps:
   - prompt: Log in to the application
     commands:

package/docs/guide/code.mdx

@@ -26,20 +26,18 @@ TestDriver allows you to execute custom **Node.js** scripts and shell scripts wi
 
 This example demonstrates how to generate a one-time password (OTP) using the `totp-generator` NPM package and use it in a test.
 
-### Test file: `testdriver/testdriver.yaml`
-
-```yaml
-version: 5.3.8
+```yaml verify-otp.yaml
+version: 6.0.0
 steps:
   - commands:
       - command: exec
         lang: pwsh
-        linux: |
+        code: |
           npm install totp-generator
       - command: exec
         lang: js
         output: totp
-        linux: |
+        code: |
           const { TOTP } = require("totp-generator");
           let otp = TOTP.generate("JBSWY3DPEB3W64TMMQQQ").otp;
           console.log(otp);
@@ -50,14 +48,18 @@ steps:
 
 ## Additional details
 
-- The [`exec`](/commands/exec) command now takes a `lang` argument and supports different operating systems (`linux`, `mac`, and `windows`).
-- Supported `lang` values are `js` or `shell`:
-  - `js` code is executed in a Node.js VM on the host machine (your computer).
-  - `shell` code is executed in the shell on the runner.
-- Code specified in `linux`, `mac`, and `windows` is executed based on the platform of the runner machine.
+- The [`exec`](/commands/exec) command now takes a `lang` argument with supported values `js` or `pwsh`.
+- `js` code is executed in a Node.js [VM](https://nodejs.org/api/vm.html) module internally.
+- `pwsh` code is executed in the PowerShell on the runner.
+
+<Note>
+The `result` variable is already available in your script, overwrite it to store the output as shown in the example.
+
+The `output`argument is assigned automatically by setting `result = somestringvalue` in the script you run.
+
+</Note>
 
 ## Protips
 
 - Always assign the output of your script to the `result` variable.
 - Ensure all required NPM packages are installed locally and in the `prerun` script when using GitHub Actions.
-- The script runs in the same context as the calling process and uses Node.js's [VM module](https://nodejs.org/api/vm.html) internally.

package/docs/guide/environment-variables.mdx

@@ -2,33 +2,34 @@
 title: "Environment Variables"
 sidebarTitle: "Environment Variables"
 description: "Learn how which environment variables are supported by TestDriver."
-icon: "key"
+icon: "sliders-up"
+mode: "wide"
 ---
 
 import GitignoreWarning from "/snippets/gitignore-warning.mdx";
 
 The supported environment variables in TestDriver are:
 
-|    Variable     |   Type    | Description                                                                              |
-| :-------------: | :-------: | :--------------------------------------------------------------------------------------- |
-| `TD_ANALYTICS`  | `boolean` | Send analytics to TestDriver servers. This helps provide feedback to inform our roadmap. |
-|  `TD_API_ROOT`  | `string`  | Developer only. Set API root to another URL. For on-prem.                                |
-|  `TD_API_KEY`   | `string`  | Set this to spawn VMs with TestDriver Pro.                                               |
-| `TD_RESOLUTION` | `string`  | Change resolution when TD_VM is true. Format like `1280x1024`.                           |
-|    `TD_TYPE`    | `string`  | Set the type of test to run. Can be `website`, `desktop`, or `mobile`. Not required.     |
+<div className="env-vars-table">
+  | Variable | Type | Description | |:---------------:|:---------:|-----------|
+  | TD_ANALYTICS | boolean | Send analytics to TestDriver servers. This helps
+  provide feedback to inform our roadmap. | | TD_API_ROOT | string | Developer
+  only. Set API root to another URL. For on-prem. | | TD_API_KEY | string | Set
+  this to spawn VMs with TestDriver Pro. | | TD_RESOLUTION | string | Change
+  resolution when TD_VM is true. Format like `1280x1024`. | | TD_TYPE | string |
+  Set the type of test to run. Can be `website`, `desktop`, or `mobile`. Not
+  required. |
+</div>
 
 <GitignoreWarning />
 
----
-
 ## Example
 
-```
+```bash .env
 TD_API_KEY=your_api_key
 TD_RESOLUTION=1024x768
 TD_TYPE=website
 TD_WEBSITE=www.jeep.com
-TD_ANALYTICS=true
 ```
 
 In this example `.env` file, we're running a website test in a local Linux VM with a resolution of 1024x768. The terminal will be minimized, and the overlay won't be shown. Analytics will be sent to TestDriver servers.

package/docs/guide/lifecycle.mdx

@@ -5,6 +5,10 @@ description: "Learn how to customize TestDriver execution with lifecycle files f
 icon: "wrench"
 ---
 
+---
+
+## Overview
+
 Lifecycle files are YAML files placed in your repository's `lifecycle/` directory. TestDriver automatically executes these files during the appropriate phases:
 
 - **`lifecycle/provision.yaml`**: Executed when a new sandbox is created
@@ -18,7 +22,7 @@ Lifecycle files are YAML files placed in your repository's `lifecycle/` director
 All lifecycle files follow the standard TestDriver YAML format:
 
 ```yaml
-version: 5.1.1
+version: 6.0.0
 steps:
   - prompt: description of what this step does
     commands:
@@ -37,17 +41,25 @@ steps:
 
 The `lifecycle/provision.yaml` file is executed when a new sandbox is created. This is ideal for installing dependencies, setting up the environment, or preparing the system for testing.
 
-### Example: `lifecycle/provision.yaml`
+### Example
 
-```yaml
-version: 5.1.1
+```yaml lifecycle/provision.yaml
+version: 6.0.0
 steps:
   - prompt: setup testing environment
     commands:
       - command: exec
         lang: pwsh
         code: |
-          Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -ArgumentList "--start-maximized --disable-infobars --disable-fre --no-default-browser-check --no-first-run --guest --load-extension=$(pwd)/node_modules/dashcam-chrome/build", "${TD_WEBSITE}"
+          Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -ArgumentList @(
+            "--start-maximized",
+            "--disable-infobars",
+            "--disable-fre",
+            "--no-default-browser-check",
+            "--no-first-run",
+            "--guest",
+            "${TD_WEBSITE}"
+          )
       - command: wait-for-text
         text: ${TD_WEBSITE}
         timeout: 60000
@@ -64,19 +76,16 @@ steps:
 
 ## Prerun Scripts
 
-The `lifecycle/prerun.yaml` file is executed before each test run. This replaces the previous `prerun` parameter from the GitHub Action and is useful for preparing the immediate test environment.
+The `lifecycle/prerun.yaml` file is executed before each test run irrespective of whether its a new sandbox or an already running one. This is useful for preparing the immediate test environment.
 
-### Example: `lifecycle/prerun.yaml`
+### Example
 
-```yaml
-version: 5.1.1
+```yaml lifecycle/prerun.yaml
+version: 6.0.0
+session: 67f00511acbd9ccac373edf7
 steps:
-  - prompt: launch chrome and start tracking
+  - prompt: start dashcam
     commands:
-      - command: exec
-        lang: pwsh
-        code: |
-          Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -ArgumentList "--start-maximized --disable-infobars --disable-fre --no-default-browser-check --no-first-run --guest --load-extension=$(pwd)/node_modules/dashcam-chrome/build", "${TD_WEBSITE}"
       - command: exec
         lang: pwsh
         code: dashcam track --name=TestDriver --type=application --pattern="C:\Users\testdriver\Documents\testdriver.log"
@@ -99,16 +108,16 @@ steps:
 
 The `lifecycle/postrun.yaml` file is executed after tests complete. This is useful for cleanup tasks, generating reports, or capturing final state information.
 
-### Example: `lifecycle/postrun.yaml`
+### Example
 
-```yaml
-version: 5.1.1
+```yaml lifecycle/postrun.yaml
+version: 6.0.0
 steps:
   - prompt: cleanup and generate reports
     commands:
       - command: exec
         lang: pwsh
-        code: dashcam -t '${TD_THIS_FILE}' -p
+        code: dashcam -t 'demo-test-title' -p # use '${TD_THIS_FILE}' to dynamically set the title for the recording
 ```
 
 ### Common postrun tasks:
@@ -132,8 +141,8 @@ Lifecycle files have access to TestDriver environment variables:
 
 ### Using variables in lifecycle files:
 
-```yaml
-version: 5.1.1
+```yaml highlight={8, 9}
+version: 6.0.0
 steps:
   - prompt: setup with custom variables
     commands:
@@ -191,13 +200,16 @@ Place lifecycle files in your repository's root directory:
 
 ```
 your-project/
-├── lifecycle/
-│   ├── provision.yaml
-│   ├── prerun.yaml
-│   └── postrun.yaml
 ├── testdriver/
-│   └── your-tests.yaml
-└── package.json
+│   ├── demo-test.yaml
+│   └── lifecycle/
+│       ├── provision.yaml
+│       ├── prerun.yaml
+│       └── postrun.yaml
+│   ├── screenshots/
+│   │   └──
+│   └── snippets/
+│       └──
 ```
 
 ---
@@ -217,7 +229,7 @@ When TestDriver runs, lifecycle files execute in this order:
 
 ### Lifecycle files not executing
 
-- Verify files are in the `lifecycle/` directory
+- Verify files are in the `testdriver/lifecycle/` directory
 - Check YAML syntax is valid
 - Ensure version number is specified
 - Verify file permissions in your repository
@@ -228,7 +240,3 @@ When TestDriver runs, lifecycle files execute in this order:
 - Verify file paths exist on the target system
 - Add error handling and logging
 - Use appropriate timeouts for operations
-
----
-
-Lifecycle files provide powerful customization capabilities for your TestDriver workflows. Use them to create reliable, reproducible test environments that meet your specific requirements.

package/docs/guide/variables.mdx

@@ -16,10 +16,10 @@ Variables in **TestDriver** allow you to dynamically store and reuse data during
 
 By leveraging variables in TestDriver, you can create dynamic, flexible, and reusable test scripts that adapt to changing conditions and data.
 
-#### Test file example:
+#### Example:
 
-```yaml
-version: 5.1.0
+```yaml random.yaml highlight={6, 11, 19, 20}
+version: 6.0.0
 steps:
   - prompt: Generate a random number
     commands:
@@ -45,7 +45,7 @@ steps:
 
 You can run TestDriver in any CI/CD pipeline. Here is an example using the CLI in a generic workflow (adapt for your platform, e.g., GitHub Actions, GitLab CI, CircleCI, Jenkins, etc.):
 
-```yaml
+```yaml workflows/testdriver.yml focus={6-13}
 steps:
   - name: Check out repository
     # For GitHub Actions: uses: actions/checkout@v4
@@ -58,17 +58,27 @@ steps:
       TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
       # Add any other required environment variables
     run: |
-      npx testdriverai@latest run --key "$TD_API_KEY" --prompt "1. Log in with username and password\n2. Verify the dashboard is displayed"
+      npx testdriverai@latest run testdriver/login.yaml
 ```
 
-> **Note:** This approach works with any CI/CD system (GitHub Actions, GitLab CI, CircleCI, Jenkins, etc.). Just set the appropriate environment variables and use the `npx testdriverai@latest run ...` command in your pipeline.
+Now inside the `login.yaml` test file you can refer the variables
 
-#### Test file
-
-```yaml
-version: 4.2.18
+```yaml login.yaml highlight={21, 22, 27, 28}
+version: 6.0.0
 steps:
-  - prompt: Log in to the application
+  - prompt: Open the homepage
+    commands:
+      - command: hover-text
+        text: Login
+        description: Login button in the top-right corner
+        action: click
+
+  - prompt: Verify the login form is displayed
+    commands:
+      - command: assert
+        expect: The login form is displayed
+
+  - prompt: Enter credentials and submit
     commands:
       - command: hover-text
         text: Email
@@ -83,25 +93,25 @@ steps:
       - command: type
         text: ${TD_PASSWORD}
       - command: hover-text
-        text: Log In
-        description: Log In button
+        text: Submit
+        description: Submit button
         action: click
 ```
 
-### **Capturing outputs as variables**
+## **Capturing outputs as variables**
 
-#### Test file example:
+#### Example:
 
-```yaml
-version: 5.1.0
+```yaml capture-text.yaml highlight={5, 6, 14, 15}
+version: 6.0.0
 steps:
   - prompt: Capture text from the screen
     commands:
-      - command: capture-text
-        description: Capture the welcome message
+      - command: remember
         output: welcomeMessage
+        description: Capture the welcome message
 
-  - prompt: Verify the captured text
+  - prompt: Verify the dashboard is displayed
     commands:
       - command: exec
         js: |

package/docs/guide/waiting.mdx

@@ -52,7 +52,7 @@ The [`wait-for-text`](/commands/wait-for-text) command pauses the test until the
 ```yaml
 - command: wait-for-text
   text: <text to wait for>
-  timeout: <time in milliseconds> # Optional, defaults to 5000ms
+  timeout: <time in milliseconds> # Optional, defaults to 5000ms or 5 seconds
 ```
 
 #### Example
@@ -74,7 +74,7 @@ The [`wait-for-image`](/commands/wait-for-image) command pauses the test until t
 ```yaml
 - command: wait-for-image
   description: <description of the image>
-  timeout: <time in milliseconds> # Optional, defaults to 5000ms
+  timeout: <time in milliseconds> # Optional, defaults to 10000ms or 10 seconds
 ```
 
 #### Example:

package/docs/importing/csv.mdx

@@ -68,7 +68,7 @@ function generateTestFile(userStory) {
   } = userStory;
 
   const testContent = {
-    version: "4.2.18",
+    version: "6.0.0",
     steps: [
       {
         prompt: title,
@@ -109,7 +109,7 @@ This script will generate individual YAML test files (for example, `test_1.yaml`
 
 Create a CI/CD workflow to execute the generated test files in parallel using the TestDriver CLI. Below is a generalized example for any CI/CD system (adapt for your platform):
 
-```yaml
+```yaml .github/workflows/testdriver.yaml
 name: Run TestDriver Tests
 
 on:
@@ -149,10 +149,9 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run TestDriver CLI
+        run: npx testdriverai@latest run ${{ matrix.test_file }}
         env:
           TD_API_KEY: ${{ secrets.TD_API_KEY }}
-          FORCE_COLOR: "3"
-        run: npx testdriverai@latest run ${{ matrix.test_file }} --headless
 ```
 
 ---

package/docs/importing/jira.mdx

@@ -119,10 +119,10 @@ fetchJiraTickets();
 
 The script above generates a YAML file for each Jira ticket. Each file contains the **acceptance criteria** as `prompt` entries.
 
-### Example YAML file (`testdriver_tests/PROJ-123.yaml`):
+### Example
 
-```yaml
-version: 4.2.18
+```yaml testdriver/proj_123.yaml
+version: 6.0.0
 steps:
   - prompt: The user can log in with valid credentials.
   - prompt: An error message is displayed for invalid credentials.
@@ -133,7 +133,7 @@ steps:
 
 ## Step 3: Save and organize test files
 
-1. The generated YAML files will be saved in the `testdriver_tests/` directory.
+1. The generated YAML files will be saved in the `testdriver/` directory.
 2. Ensure the directory is part of your TestDriver project structure.
 
 ---
@@ -145,13 +145,7 @@ Use the TestDriver CLI to execute the generated test files.
 ### Run a single test file:
 
 ```bash
-npx testdriverai@latest run testdriver_tests/PROJ-123.yaml
-```
-
-### Run all test files:
-
-```bash
-npx testdriverai@latest run testdriver_tests/*.yaml
+npx testdriverai@latest run testdriver/proj_123.yaml
 ```
 
 ---
@@ -161,7 +155,7 @@ npx testdriverai@latest run testdriver_tests/*.yaml
 1. **Field Mapping**: Ensure the correct Jira field ID (for example, `customfield_12345`) is used for "Acceptance Criteria."
 2. **Secure Credentials**: Store Jira API credentials in environment variables or secrets.
 3. **Review Generated Files**: Manually review the YAML files to ensure they align with your testing requirements.
-4. **Organize Tests**: Use a structured directory (for example, `testdriver_tests/`) to manage your test files.
+4. **Organize Tests**: Use a structured directory (for example, `testdriver/`) to manage your test files.
 
 ---
 

package/docs/importing/testrail.mdx

@@ -116,10 +116,10 @@ fetchTestRailTestCases();
 
 The script above generates a YAML file for each TestRail test case. Each file contains the **steps** as `prompt` entries.
 
-### Example YAML file (`testdriver_tests/test_123.yaml`):
+### Example
 
-```yaml
-version: 4.2.18
+```yaml testdriver/test_123.yaml
+version: 6.0.0
 steps:
   - prompt: Navigate to the login page.
   - prompt: Enter valid credentials.
@@ -131,7 +131,7 @@ steps:
 
 ## Step 3: Save and organize test files
 
-1. The generated YAML files will be saved in the `testdriver_tests/` directory.
+1. The generated YAML files will be saved in the `testdriver/` directory.
 2. Ensure the directory is part of your TestDriver project structure.
 
 ---
@@ -143,7 +143,7 @@ Use the TestDriver CLI to execute the generated test files.
 ### Run a Single test file:
 
 ```bash
-npx testdriverai@latest run testdriver_tests/test_123.yaml
+npx testdriverai@latest run testdriver/test_123.yaml
 ```
 
 ---
@@ -153,7 +153,7 @@ npx testdriverai@latest run testdriver_tests/test_123.yaml
 1. **Field Mapping**: Ensure the correct TestRail field ID (for example, `custom_steps`) is used for test steps.
 2. **Secure Credentials**: Store TestRail API credentials in environment variables or secrets.
 3. **Review Generated Files**: Manually review the YAML files to ensure they align with your testing requirements.
-4. **Organize Tests**: Use a structured directory (for example, `testdriver_tests/`) to manage your test files.
+4. **Organize Tests**: Use a structured directory (for example, `testdriver/`) to manage your test files.
 
 ---