@testdriverai/agent 7.8.0-test.38

package/docs/v6/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/v6/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/v6/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/v6/exporting/junit.mdx

@@ -0,0 +1,218 @@
+---
+title: "JUnit XML Reports"
+sidebarTitle: "JUnit"
+description: "Generate JUnit XML test reports for seamless integration with CI/CD pipelines and test reporting tools."
+icon: "file-xml"
+---
+
+TestDriver supports generating **JUnit XML reports** that are compatible with most CI/CD systems, test reporting tools, and IDEs. This feature enables you to integrate TestDriver tests into your existing test infrastructure and get detailed test results in a standardized format.
+
+---
+
+## Overview
+
+JUnit XML reports provide structured test results that include:
+
+- **Test Suite Information**: Organized by folder structure from your `testdriver` directory
+- **Test Case Details**: Individual test files with execution status
+- **Step-by-Step Results**: Each step in your test with pass/fail status
+- **System Output**: Complete logs from test execution (ANSI codes stripped)
+- **Error Information**: Detailed failure messages and stack traces
+- **Timing Data**: Execution duration for tests and individual steps
+
+---
+
+## Basic Usage
+
+Enable JUnit reporting by adding the `--junit` flag to your TestDriver command:
+
+```bash
+npx testdriverai@latest run path/to/test.yaml --junit=test-results.xml
+```
+
+This will:
+
+1. Execute your TestDriver test normally
+2. Generate a JUnit XML report at the specified file path
+3. Include all test execution details in the report
+
+---
+
+## Command Line Options
+
+| Flag             | Description                                 | Example                            |
+| ---------------- | ------------------------------------------- | ---------------------------------- |
+| `--junit=<path>` | Generate JUnit XML report to specified file | `--junit=reports/test-results.xml` |
+
+### Examples
+
+**Basic usage:**
+
+```bash
+npx testdriverai@latest run testdriver/login.yaml --junit=junit-report.xml
+```
+
+---
+
+## Report Structure
+
+### Test Suite Hierarchy
+
+JUnit reports organize your tests using the following structure:
+
+- **Test Suite**: Named after the folder path from your `testdriver` directory
+- **Test Case**: Individual test files (`.yaml` files)
+- **Properties**: Each step in your test with its status and prompt
+
+### Example Report Structure
+
+For a test file at `testdriver/features/login.yaml`:
+
+```xml
+<testsuites tests="1" failures="0" errors="0" skipped="0">
+  <testsuite name="testdriver/features" tests="1" failures="0" errors="0" skipped="0">
+    <testcase classname="testdriver/features" name="login.yaml" time="12.543">
+      <properties>
+        <property name="step1[passed]" value="Navigate to login page"/>
+        <property name="step2[passed]" value="Enter username and password"/>
+        <property name="step3[passed]" value="Click login button"/>
+        <property name="step4[passed]" value="Verify dashboard appears"/>
+      </properties>
+      <system-out><![CDATA[
+        Complete test execution logs...
+      ]]></system-out>
+    </testcase>
+  </testsuite>
+</testsuites>
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: TestDriver Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run TestDriver Tests
+        run: npx testdriverai@latest run testdriver/test.yaml --junit=test-results.xml
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+
+      - name: Publish Test Results
+        uses: dorny/test-reporter@v1
+        if: always()
+        with:
+          name: TestDriver Tests
+          path: test-results.xml
+          reporter: java-junit
+```
+
+### Jenkins
+
+```groovy
+pipeline {
+    agent any
+
+    stages {
+        stage('Test') {
+            steps {
+                script {
+                    sh 'npx testdriverai@latest run testdriver/test.yaml --junit=junit-results.xml'
+                }
+            }
+            post {
+                always {
+                    junit 'junit-results.xml'
+                }
+            }
+        }
+    }
+}
+```
+
+### GitLab CI
+
+```yaml
+test:
+  script:
+    - npx testdriverai@latest run testdriver/test.yaml --junit=test-results.xml
+  artifacts:
+    when: always
+    reports:
+      junit: test-results.xml
+```
+
+---
+
+## Test Result Details
+
+### Successful Tests
+
+For passing tests, the report includes:
+
+- Test execution time
+- All step prompts with `[passed]` status
+- Complete system output logs
+- Command execution details
+
+### Failed Tests
+
+For failing tests, the report includes:
+
+- Detailed failure messages
+- Failed assertion information
+- Failed step prompts with `[failed]` status
+- Error logs in `<system-err>` section
+- Exit code information
+
+### Example Failure Report
+
+```xml
+<testcase classname="testdriver/features" name="login.yaml" time="8.234">
+  <failure message="Failed assertions: user should see welcome message"/>
+  <properties>
+    <property name="step1[passed]" value="Navigate to login page"/>
+    <property name="step2[failed]" value="Verify welcome message appears"/>
+  </properties>
+  <system-err><![CDATA[
+    Assertion failed: Expected welcome message not found
+  ]]></system-err>
+</testcase>
+```
+
+---
+
+## Integration with Test Viewers
+
+### JUnit Viewer
+
+Generate HTML reports from your XML:
+
+```bash
+# Install junit-viewer
+npm install -g junit-viewer
+
+# Generate HTML report
+junit-viewer --results=test-results.xml --save=report.html
+
+# Serve the report
+npx http-server . -p 8080 -o report.html
+```
+
+### IDE Integration
+
+Most IDEs support JUnit XML reports:
+
+- **VS Code**: Use test result extensions
+- **IntelliJ IDEA**: Import test results directly
+- **Eclipse**: Built-in JUnit viewer support

package/docs/v6/exporting/playwright.mdx

@@ -0,0 +1,197 @@
+---
+title: "Playwright Export"
+sidebarTitle: "Playwright"
+description: "A comprehensive guide to integrating TestDriver with Playwright for automated test generation."
+icon: "masks-theater"
+---
+
+This guide explains how to use **TestDriver CLI** to generate Playwright test scripts and integrate them into your repository using a GitHub Actions workflow. The workflow automates the process of generating Playwright tests using TestDriver's execution capabilities and can create pull requests with the generated tests.
+
+---
+
+## Workflow overview
+
+1. **Run TestDriver CLI**: Execute a TestDriver test file.
+2. **Lifecycle Prerun**: Automatically install Playwright and generate test scripts via `lifecycle/prerun.yaml`.
+3. **Execute Test**: Run the main test logic to verify or use the generated Playwright tests.
+4. **Create Pull Request**: Optional additional steps can commit changes and create a pull request for review.
+
+---
+
+## Prerequisites
+
+1. **GitHub Repository**: Ensure your project is hosted on GitHub.
+2. **TestDriver API Key**: Store your API key as a GitHub secret (for example, `TD_API_KEY`).
+3. **Lifecycle Files**: Create `lifecycle/prerun.yaml` for Playwright installation and generation.
+4. **TestDriver Test File**: Create a test file (`testdriver/test.yaml`) for your main test logic.
+
+---
+
+## GitHub Actions workflow
+
+Here's the GitHub Actions workflow to automate the process:
+
+### Workflow file: `.github/workflows/playwright.yaml`
+
+```yaml [expandable]
+name: TestDriver / Playwright
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: write
+  statuses: write
+  pull-requests: write
+
+jobs:
+  test:
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.ref }}
+
+      - name: Run TestDriver
+        run: npx testdriverai@latest run testdriver/test.yaml
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+```
+
+---
+
+## Workflow steps explained
+
+### 1. **Check out repository**
+
+The workflow checks out the repository to ensure the latest code is available for the test generation process.
+
+```yaml
+- name: Check out repository
+  uses: actions/checkout@v4
+  with:
+    ref: ${{ github.event.ref }}
+```
+
+---
+
+### 2. **Run TestDriver**
+
+TestDriver CLI executes the test file in headless mode. The test file should contain commands to install Playwright and generate the test scripts.
+
+```yaml
+- name: Run TestDriver
+  run: npx testdriverai@latest run testdriver/test.yaml
+  env:
+    TD_API_KEY: ${{ secrets.TD_API_KEY }}
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    FORCE_COLOR: "3"
+```
+
+---
+
+### 3. **Lifecycle configuration**
+
+Use `lifecycle/prerun.yaml` to install and launch Playwright before your test runs. This keeps the setup separate from your actual test logic:
+
+```yaml
+# lifecycle/prerun.yaml
+version: 5.1.1
+steps:
+  - prompt: install and launch playwright
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          npm install playwright -g
+          playwright install --with-deps chromium
+          npx playwright codegen --target playwright-test -o testdriver/pw-test.spec.js https://airbnb.com
+```
+
+Your main `testdriver/test.yaml` file can then focus on the actual test logic:
+
+```yaml
+# testdriver/test.yaml
+version: 5.1.1
+steps:
+  - prompt: verify playwright test was generated
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          if (Test-Path "testdriver/pw-test.spec.js") {
+            Write-Host "Playwright test generated successfully"
+          } else {
+            throw "Playwright test generation failed"
+          }
+```
+
+---
+
+### 4. **Commit and create pull request**
+
+After TestDriver generates the Playwright test files, you can use additional GitHub Actions steps to commit the changes and create a pull request:
+
+```yaml
+- name: Commit changes
+  run: |
+    git config --local user.email "action@github.com"
+    git config --local user.name "GitHub Action"
+    git add testdriver/pw-test.spec.js
+    git commit -m "Generate Playwright test" || exit 0
+
+- name: Create Pull Request
+  uses: peter-evans/create-pull-request@v5
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    commit-message: "Generate Playwright test"
+    title: "TestDriver / Generate Playwright Test"
+    branch: generate-playwright
+    base: main
+```
+
+---
+
+## Running the workflow
+
+<Steps>
+<Step title="Trigger the Workflow">
+  - Push changes to the `main` branch.
+  - Open a pull request.
+  - Manually trigger the workflow using the **workflow_dispatch** event.
+  </Step>
+<Step title="Review the Pull Request">
+  - Navigate to the **Pull Requests** tab in your GitHub repository.
+  - Review the generated Playwright test script (`pw-test.spec.js`).
+  </Step>
+
+<Step title="Merge the Pull Request">
+  - Once reviewed, merge the pull request to include the generated test in your repository.
+</Step>
+</Steps>
+---
+
+## Example output
+
+- **Generated Test File**: `testdriver/pw-test.spec.js`
+- **Pull Request**: A new pull request titled `TestDriver / Generate Playwright Test` will be created.
+
+---
+
+## Best practices
+
+1. **Secure API Key**: Store the TestDriver API key as a GitHub secret to avoid exposing sensitive information.
+2. **Review Generated Tests**: Always review the generated Playwright test scripts to ensure they meet your requirements.
+3. **Use Lifecycle Files**: Use `lifecycle/prerun.yaml` for Playwright installation and setup to separate concerns from your main test logic.
+4. **Error Handling**: Include error handling in both lifecycle and test files to manage installation and generation failures gracefully.
+5. **File Organization**: Keep generated Playwright tests in a dedicated directory for better organization.
+
+---
+
+By following this guide, you can use TestDriver CLI to generate and manage Playwright tests in your GitHub repository through automated workflows.