@testdriverai/agent 7.8.0-test.38

package/docs/v6/guide/authentication.mdx

@@ -0,0 +1,136 @@
+---
+title: "Authentication"
+sidebarTitle: "Authentication"
+description: "Learn how to handle authentication workflows in TestDriver using GitHub Actions."
+icon: "key"
+---
+
+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 />
+
+---
+
+## How authentication works in TestDriver
+
+1. **Store Credentials Securely**:
+
+- Use GitHub Secrets to store sensitive information like usernames, passwords, or API keys.
+
+2. **Pass Credentials to the Workflow**:
+
+- Supply credentials as environment variables or directly in the workflow.
+
+3. **Use Credentials in Tests**:
+
+- Dynamically reference credentials in the `prerun` script or test files to perform authentication steps.
+
+## Step 1: Store credentials in GitHub secrets
+
+1. Navigate to your repository's **Settings** > **Secrets and variables** > **Actions**.
+2. Add the following secrets:
+   - **`TD_USERNAME`**: The username for login.
+   - **`TD_PASSWORD`**: The password for login.
+   - **`TD_API_KEY`**: Your TestDriver API key.
+   - **`TD_WEBSITE`**: The URL of the website to test.
+
+## Step 2: Pass credentials to the workflow
+
+Secrets are passed to the workflow using the `secrets` context. They can be supplied as:
+
+- **Environment Variables**: Passed via the `env` block.
+- **Inline in the `prerun` Script**: Used directly in the script.
+
+### Example GitHub Actions workflow (adapt for your CI/CD platform)
+
+```yaml workflows/td-auth.yml focus={17-24}
+name: TestDriver / Authentication
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test-authentication:
+    name: Test Authentication
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Run Authentication Test
+        run: npx testdriverai@latest run testdriver/authentication.yaml
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TD_USERNAME: ${{ secrets.TD_USERNAME }}
+          TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
+          TD_WEBSITE: ${{ secrets.TD_WEBSITE }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+```
+
+## Step 3: Use credentials in test files
+
+Secrets can be referenced in the test file using placeholders (for example, `${TD_USERNAME}` and `${TD_PASSWORD}`).
+
+### Example test file:
+
+```yaml login.yaml highlight={9, 10, 15, 16}
+version: 6.0.0
+steps:
+  - prompt: Log in to the application
+    commands:
+      - command: hover-text
+        text: Email
+        description: Email input field
+        action: click
+      - command: type
+        text: ${TD_USERNAME}
+      - command: hover-text
+        text: Password
+        description: Password input field
+        action: click
+      - command: type
+        text: ${TD_PASSWORD}
+      - command: hover-text
+        text: Log In
+        description: Log In button
+        action: click
+      - command: assert
+        expect: The dashboard is displayed
+```
+
+## How it works together
+
+1. **Secrets in the Workflow**:
+
+- Secrets like `TD_USERNAME` and `TD_PASSWORD` are passed as environment variables to the TestDriver action.
+
+2. **Secrets in the `prerun` Script**:
+
+- The `TD_WEBSITE` secret is used to launch the browser with the correct URL.
+
+3. **Secrets in the Test File**:
+
+- The test file dynamically references the secrets to fill in login credentials during the test.
+
+## Benefits of using authentication in TestDriver
+
+1. **Secure Handling of Credentials**:
+
+- Secrets are encrypted and not exposed in logs.
+- Even if printed, they appear as `***`.
+
+2. **Dynamic Testing**:
+
+- Easily switch between different environments (for example, staging, production) by updating the secrets.
+
+3. **Reusability**:
+
+- Use the same workflow and test files across multiple repositories or environments.
+
+---
+
+By securely passing credentials and using them in the `prerun` script and test files, you can automate authentication workflows in TestDriver while ensuring sensitive information remains protected.

package/docs/v6/guide/code.mdx

@@ -0,0 +1,65 @@
+---
+title: "Custom Code in TestDriver"
+sidebarTitle: "Custom Code"
+description: "Learn how to integrate custom Node.js scripts into your TestDriver workflows for dynamic testing."
+icon: "code"
+---
+
+TestDriver allows you to execute custom **Node.js** scripts and shell scripts within your test workflows using the [`exec`](/commands/exec) command. This feature, introduced in version `5.1.0`, enables you to integrate custom logic, such as generating one-time passwords (OTPs), hitting APIs, or performing other dynamic operations, directly into your tests.
+
+## Key features
+
+1. **Run Node.js Scripts**:
+
+- Execute custom JavaScript code within your test steps.
+- Use NPM modules to extend functionality.
+
+2. **Dynamic Outputs**:
+
+- Store the result of your script in a variable for use in subsequent steps.
+
+3. **NPM Support**:
+
+- Install and use NPM packages in your scripts.
+
+## Updated example: One-time password (OTP) validator
+
+This example demonstrates how to generate a one-time password (OTP) using the `totp-generator` NPM package and use it in a test.
+
+```yaml verify-otp.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
+
+- 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.

package/docs/v6/guide/dashcam.mdx

@@ -0,0 +1,118 @@
+---
+title: "Dashcam Replays"
+sidebarTitle: "Dashcam"
+description: "Learn how to use Dashcam to record and replay test sessions in TestDriver."
+icon: "video"
+---
+
+[Dashcam](https://www.dashcam.io), from the makers of TestDriver, is a powerful feature in TestDriver that allows you to record and replay your test sessions. This is particularly useful for debugging, sharing test runs with team members, or reviewing the steps taken during a test. For the full docs see the [Dashcam docs](https://docs.dashcam.io/dashcam/).
+
+## Recording a Test Session
+
+To record a test session, you can use the `dashcam` command in your lifecycle scripts. There are two main lifecycle scripts where you can integrate Dashcam: `lifecycle/prerun.yaml` and `lifecycle/postrun.yaml`.
+
+## Ways to use Dashcam
+
+Dashcam comes as a standalone app and a Chrome extension. You can use either or both to capture your test sessions.
+
+<Info>
+  To capture web logs, make sure to install the Dashcam Chrome extension on the
+  browser you are testing with. We recommend installing it via CLI to Chrome for
+  Testing. You can also find the extension [in the Chrome
+  Webstore](https://chromewebstore.google.com/detail/dashcam/dkcoeknmlfnfimigfagbcjgpokhdcbbp)
+</Info>
+
+### Installing the Dashcam Chrome extension via command line in prerun.yaml
+
+In this lifecycle script, we install Chrome for Testing with a user profile that has the password manager disabled and sets up TestDriver Dashcam for replays and logs.
+
+```yaml lifecycle/prerun.yaml [expandable]
+- prompt: launch chrome for testing and setup dashcam
+    commands:
+      # this script installs chrome for testing with a userprofile that has password manager disabled and sets up TestDriver Dashcam for replays and logs
+      - command: exec
+        lang: pwsh
+        code: |
+          cd $env:TEMP
+          Write-Host "Changed directory to TEMP: $env:TEMP"
+
+          Write-Host "Running 'npm init -y'..."
+          npm init -y
+
+          Write-Host "Installing dependencies: @puppeteer/browsers and dashcam-chrome..."
+          npm install @puppeteer/browsers dashcam-chrome
+
+          Write-Host "Installing Chromium via '@puppeteer/browsers'..."
+          npx @puppeteer/browsers install chrome
+
+          # Define paths
+          $extensionPath = Join-Path (Get-Location) "node_modules/dashcam-chrome/build"
+          $profilePath = Join-Path $env:TEMP "chrome-profile-$(Get-Random)"
+
+          Write-Host "Extension path: $extensionPath"
+          Write-Host "Chrome user data dir: $profilePath"
+
+          # Validate extension path
+          if (-not (Test-Path $extensionPath)) {
+              Write-Host "Extension not found at $extensionPath"
+          }
+
+          $chromeArgs = @(
+            "--start-maximized",
+            "--load-extension=$extensionPath",
+            "--user-data-dir=$profilePath",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-infobars"
+            "${TD_WEBSITE}"
+          ) -join ' '
+
+          Start-Process "cmd.exe" -ArgumentList "/c", "npx @puppeteer/browsers launch chrome -- $chromeArgs"
+
+          Write-Host "Script complete."
+          exit 0
+```
+
+### Using the Chrome extension and capturing web logs
+
+Now in the same `lifecycle/prerun.yaml` script, we set up Dashcam to track web logs and application logs. You can customize the patterns to match your needs. Testing Desktop? You can skip the web logs and just track application logs.
+
+```yaml lifecycle/prerun.yaml
+...
+- command: exec
+    lang: pwsh
+    code: |
+        dashcam track --name="Web Logs" --type="web" --pattern="*"
+        dashcam track --name=TestDriver --type=app --pattern="C:\Users\testdriver\Documents\testdriver.log"
+```
+
+### Starting Dashcam
+
+The final step in our `lifecycle/prerun.yaml` script is to start Dashcam recording.
+
+```yaml lifecycle/prerun.yaml
+...
+- command: exec
+    lang: pwsh
+    code: dashcam start
+```
+
+### Publishing replays to a project in your account
+
+Lastly, in the `lifecycle/postrun.yaml` script, we publish the recorded Dashcam session to a project in your Dashcam account. Make sure to replace `<YOUR_PROJECT_ID>` with the actual ID of your project.
+
+```yaml lifecycle/postrun.yaml
+- prompt: send dashcam recording to server
+    # this script tells TestDriver Dashcam to send the recording to the server
+  commands:
+    - command: exec
+        lang: pwsh
+        code: dashcam -t '${TD_THIS_FILE}' -p -k <YOUR_PROJECT_ID> # optional add `-k MYFOLDERID` for the id of a folder in your Projects page at app.testdriver.ai
+```
+
+<Info>
+  `${TD_THIS_FILE}` is an environment variable set by TestDriver that contains
+  the name of the current test file being executed. This will be used as the
+  title of the Dashcam recording. For more info see [parallel testing
+  docs](/features/parallel-testing).
+</Info>

package/docs/v6/guide/environment-variables.mdx

@@ -0,0 +1,26 @@
+---
+title: "Environment Variables"
+sidebarTitle: "Environment Variables"
+description: "Learn how which environment variables are supported by TestDriver."
+icon: "sliders-up"
+mode: "wide"
+---
+
+import GitignoreWarning from "/snippets/gitignore-warning.mdx";
+
+The supported environment variables in TestDriver are:
+
+<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_KEY`    | `string`     | Set this to spawn VMs with TestDriver Pro. |
+</div>
+<GitignoreWarning />
+## Example
+
+```bash .env
+TD_API_KEY=your_api_key
+```
+
+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/v6/guide/lifecycle.mdx

@@ -0,0 +1,242 @@
+---
+title: "Lifecycle Files"
+sidebarTitle: "Lifecycle Files"
+description: "Learn how to customize TestDriver execution with lifecycle files for setup, provisioning, and cleanup."
+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
+- **`lifecycle/prerun.yaml`**: Executed before tests run
+- **`lifecycle/postrun.yaml`**: Executed after tests complete
+
+---
+
+## File Structure
+
+All lifecycle files follow the standard TestDriver YAML format:
+
+```yaml
+version: 6.0.0
+steps:
+  - prompt: description of what this step does
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          # Your PowerShell commands here
+      - command: wait-for-text
+        text: "Expected text"
+        timeout: 30000
+```
+
+---
+
+## Provision Scripts
+
+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
+
+```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",
+            "${TD_WEBSITE}"
+          )
+      - command: wait-for-text
+        text: ${TD_WEBSITE}
+        timeout: 60000
+```
+
+### Common provision tasks:
+
+- Installing software dependencies
+- Setting up browser extensions
+- Configuring system settings
+- Downloading test data or assets
+
+---
+
+## Prerun Scripts
+
+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
+
+```yaml lifecycle/prerun.yaml
+version: 6.0.0
+session: 67f00511acbd9ccac373edf7
+steps:
+  - prompt: start dashcam
+    commands:
+      - command: exec
+        lang: pwsh
+        code: dashcam track --name=TestDriver --type=app --pattern="C:\Users\testdriver\Documents\testdriver.log"
+      - command: exec
+        lang: pwsh
+        code: dashcam start
+```
+
+### Common prerun tasks:
+
+- Opening applications or browsers
+- Navigating to starting pages
+- Clearing application state
+- Starting monitoring tools
+- Setting environment variables
+
+---
+
+## Postrun Scripts
+
+The `lifecycle/postrun.yaml` file is executed after tests complete. This is useful for cleanup tasks, generating reports, or capturing final state information.
+
+### Example
+
+```yaml lifecycle/postrun.yaml
+version: 6.0.0
+steps:
+  - prompt: cleanup and generate reports
+    commands:
+      - command: exec
+        lang: pwsh
+        code: dashcam -t 'demo-test-title' -p # use '${TD_THIS_FILE}' to dynamically set the title for the recording
+```
+
+### Common postrun tasks:
+
+- Generating test reports
+- Capturing screenshots or logs
+- Cleaning up temporary files
+- Stopping background processes
+- Uploading artifacts
+
+---
+
+## Environment Variables
+
+Lifecycle files have access to TestDriver environment variables:
+
+- `${TD_WEBSITE}`: The target website URL
+- `${TD_THIS_FILE}`: Current test file name
+- `${TD_API_KEY}`: Your TestDriver API key
+- Custom variables defined in your workflow
+
+### Using variables in lifecycle files:
+
+```yaml highlight={8, 9}
+version: 6.0.0
+steps:
+  - prompt: setup with custom variables
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          Write-Host "Testing website: ${TD_WEBSITE}"
+          Write-Host "Current test: ${TD_THIS_FILE}"
+          # Your setup commands here
+```
+
+---
+
+## Best Practices
+
+### Keep lifecycle files focused
+
+Each lifecycle file should have a specific purpose:
+
+- **Provision**: System-level setup
+- **Prerun**: Test preparation
+- **Postrun**: Cleanup and reporting
+
+### Use appropriate commands
+
+- Use [`exec`](/commands/exec) with `lang: pwsh` for system commands
+- Use TestDriver commands ([`wait-for-text`](/commands/wait-for-text), [`hover-text`](/commands/hover-text), etc.) for UI interactions
+- Include appropriate timeouts for reliability
+
+### Error handling
+
+Include checks to verify operations completed successfully:
+
+```yaml
+- command: exec
+  lang: pwsh
+  code: |
+    if (!(Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe")) {
+      throw "Chrome not found"
+    }
+    Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe"
+```
+
+### Performance considerations
+
+- Keep provision scripts efficient to minimize sandbox setup time
+- Cache dependencies when possible
+- Use lightweight operations in prerun/postrun scripts
+
+---
+
+## File Placement
+
+Place lifecycle files in your repository's root directory:
+
+```
+your-project/
+├── testdriver/
+│   ├── demo-test.yaml
+│   └── lifecycle/
+│       ├── provision.yaml
+│       ├── prerun.yaml
+│       └── postrun.yaml
+│   ├── screenshots/
+│   │   └──
+│   └── snippets/
+│       └──
+```
+
+---
+
+## Execution Order
+
+When TestDriver runs, lifecycle files execute in this order:
+
+1. **Provision** (once per sandbox creation)
+2. **Prerun** (before each test)
+3. **Your test files**
+4. **Postrun** (after each test)
+
+---
+
+## Troubleshooting
+
+### Lifecycle files not executing
+
+- Verify files are in the `testdriver/lifecycle/` directory
+- Check YAML syntax is valid
+- Ensure version number is specified
+- Verify file permissions in your repository
+
+### Commands failing
+
+- Check PowerShell syntax for [`exec`](/commands/exec) commands
+- Verify file paths exist on the target system
+- Add error handling and logging
+- Use appropriate timeouts for operations