testdriverai 6.0.16-canary.f0eefe0.0 → 6.0.16

package/docs/guide/assertions.mdx

@@ -7,7 +7,7 @@ icon: "square-check"
 
 # Guide: Using assertions in TestDriver
 
-Assertions in TestDriver allow you to validate that your application behaves as expected during a test. By using the `assert` command and visual assertions, you can ensure that specific conditions are met, such as verifying the presence of text, images, or UI elements on the screen.
+Assertions in TestDriver allow you to validate that your application behaves as expected during a test. By using the [`assert`](/commands/assert) command and visual assertions, you can ensure that specific conditions are met, such as verifying the presence of text, images, or UI elements on the screen.
 
 ---
 
@@ -16,15 +16,16 @@ Assertions in TestDriver allow you to validate that your application behaves as
 Assertions are checks that validate whether a specific condition is true. If the condition isn't met, the test will fail, providing feedback on what went wrong.
 
 ### Types of assertions in TestDriver:
+
 1. **Text Assertions**: Verify that specific text is visible on the screen.
 2. **Visual Assertions**: Validate the presence of images, icons, or UI elements.
 3. **Custom Assertions**: Use descriptive conditions to check for specific outcomes.
 
 ---
 
-## How to use the `assert` command
+## How to use the [`assert`](/commands/assert) command
 
-The `assert` command is used to validate conditions during a test. It checks whether the specified expectation is true.
+The [`assert`](/commands/assert) command is used to validate conditions during a test. It checks whether the specified expectation is true.
 
 ### Syntax:
 
@@ -32,10 +33,8 @@ The `assert` command is used to validate conditions during a test. It checks whe
 - command: assert
   expect: <condition to check>
   async: <true|false> # Optional, defaults to false
-
 ```
 
-
 - **`expect`**: The condition to validate (for example, "The login form is displayed").
 - **`async`**: (Optional) If set to `true`, the test will continue running without waiting for the assertion to pass.
 
@@ -48,10 +47,8 @@ The `assert` command is used to validate conditions during a test. It checks whe
 ```yaml
 - command: assert
   expect: The login form is displayed
-
 ```
 
-
 This assertion checks if the login form is visible on the screen.
 
 ---
@@ -64,10 +61,8 @@ This assertion checks if the login form is visible on the screen.
 - command: assert
   expect: The success message is displayed
   async: true
-
 ```
 
-
 This assertion runs asynchronously, allowing the test to continue without waiting for the success message to appear.
 
 ---
@@ -84,10 +79,8 @@ Visual assertions validate the presence of images, icons, or UI elements on the
 - command: hover-image
   description: Company logo in the top-left corner
   action: hover
-
 ```
 
-
 This command hovers over the company logo to ensure it's present on the screen.
 
 ---
@@ -101,10 +94,8 @@ This command hovers over the company logo to ensure it's present on the screen.
   text: Submit
   description: Blue button with the text 'Submit' at the bottom of the form
   action: hover
-
 ```
 
-
 This command hovers over the "Submit" button to confirm its presence.
 
 ---
@@ -155,18 +146,18 @@ steps:
     commands:
       - command: assert
         expect: The dashboard is displayed
-
 ```
 
-
 ---
 
 ## Debugging assertions
 
 1. **Review Error Messages**:
+
    - If an assertion fails, TestDriver provides detailed error messages to help identify the issue.
 
 2. **Use Visual Feedback**:
+
    - Leverage screenshots and visual feedback to verify the state of the application during the assertion.
 
 3. **Refine Descriptions**:
@@ -177,15 +168,19 @@ steps:
 ## Best practices for assertions
 
 1. **Be Specific**:
+
    - Use clear and concise conditions for assertions (for example, "The login form is displayed").
 
 2. **Use Visual Assertions for Non-Text Elements**:
-   - Validate images, icons, and other UI elements using `hover-image` or `hover-text`.
+
+   - Validate images, icons, and other UI elements using [`hover-image`](/commands/hover-image) or [`hover-text`](/commands/hover-text).
 
 3. **Combine Assertions with Navigation**:
+
    - Place assertions after navigation or interaction steps to validate the application's state.
 
 4. **Leverage Async Assertions**:
+
    - Use `async: true` for non-blocking checks, especially for dynamic content.
 
 5. **Test Incrementally**:
@@ -193,4 +188,4 @@ steps:
 
 ---
 
-By using the `assert` command and visual assertions effectively, you can create robust and reliable tests that ensure your application behaves as expected.
+By using the [`assert`](/commands/assert) command and visual assertions effectively, you can create robust and reliable tests that ensure your application behaves as expected.

package/docs/guide/code.mdx

@@ -5,7 +5,7 @@ description: "Learn how to integrate custom Node.js scripts into your TestDriver
 icon: "code"
 ---
 
-TestDriver allows you to execute custom **Node.js** scripts and shell scripts within your test workflows using the `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.
+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
 
@@ -50,7 +50,7 @@ steps:
 
 ## Additional details
 
-- The `exec` command now takes a `lang` argument and supports different operating systems (`linux`, `mac`, and `windows`).
+- 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.

package/docs/guide/lifecycle.mdx

@@ -159,8 +159,8 @@ Each lifecycle file should have a specific purpose:
 
 ### Use appropriate commands
 
-- Use `exec` with `lang: pwsh` for system commands
-- Use TestDriver commands (`wait-for-text`, `hover-text`, etc.) for UI interactions
+- 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
@@ -224,7 +224,7 @@ When TestDriver runs, lifecycle files execute in this order:
 
 ### Commands failing
 
-- Check PowerShell syntax for `exec` commands
+- 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

package/docs/guide/locating.mdx

@@ -12,14 +12,17 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 ## KeypPrinciples for locating elements
 
 1. **Describe the Element Visually**:
+
    - Focus on the **appearance** of the element, not its behavior or function.
    - Mention unique visual traits such as **text**, **color**, **size**, **position**, or **icon**.
 
 2. **Avoid Behavioral Descriptions**:
+
    - don't describe what the element does (for example, "button that submits the form").
    - Instead, describe how it looks (for example, "blue button with the text 'Submit' in the bottom-right corner").
 
 3. **Use Unique Identifiers**:
+
    - If the element has visible text, include it in the description.
    - For icons or images, describe their shape, color, or associated label.
 
@@ -32,22 +35,27 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 ## Examples of effective descriptions
 
 ### 1. Buttons
+
 - **Good**: "Blue button with the text 'Sign In' in the top-right corner."
 - **Bad**: "Button that logs the user in."
 
 ### 2. Links
+
 - **Good**: "Hyperlink with the text 'Learn More' in the footer."
 - **Bad**: "Link that navigates to the About page."
 
 ### 3. Icons
+
 - **Good**: "Magnifying glass icon next to the search bar."
 - **Bad**: "Search icon that opens the search feature."
 
 ### 4. Input fields
+
 - **Good**: "White input box labeled 'Email Address' above the password field."
 - **Bad**: "Field where the user enters their email."
 
 ### 5. Images
+
 - **Good**: "Company logo in the top-left corner, a blue circle with white text."
 - **Bad**: "Logo that redirects to the homepage."
 
@@ -64,11 +72,8 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
   text: Sign In
   description: Blue button with the text 'Sign In' in the top-right corner
   action: click
-
-
 ```
 
-
 ---
 
 ### Example: Locating an icon
@@ -92,20 +97,19 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
   text: Learn More
   description: Hyperlink with the text 'Learn More' in the footer
   action: click
-
-
 ```
 
-
 ---
 
 ## Debugging element detection
 
 1. **Run the Test**:
+
    - Execute the test using TestDriver.
    - TestDriver will draw **yellow boxes** around detected elements.
 
 2. **Verify the Correct Element**:
+
    - Ensure the yellow box highlights the intended element.
    - If the wrong element is highlighted, refine your description.
 
@@ -118,12 +122,15 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 ## Best practices
 
 1. **Be Specific**:
+
    - Include as many unique visual traits as possible to differentiate the element from others.
 
 2. **Test Incrementally**:
+
    - Run tests after adding or modifying commands to verify element detection.
 
 3. **Use Visual Feedback**:
+
    - Leverage the yellow boxes drawn by TestDriver to confirm the correct element is being targeted.
 
 4. **Avoid Overloading Descriptions**:

package/docs/guide/waiting.mdx

@@ -7,44 +7,45 @@ icon: "clock"
 
 # Waiting in TestDriver: Ensuring stability and reducing flakiness
 
-Waiting is a critical feature in TestDriver that ensures tests are stable and reliable, even in dynamic or slow-loading environments. 
+Waiting is a critical feature in TestDriver that ensures tests are stable and reliable, even in dynamic or slow-loading environments.
 
 - Automatically adjusts to varying load times, reducing the need for hardcoded delays.
 - Ensures that tests wait for dynamic elements to appear, reducing false negatives caused by incomplete rendering.
 - By waiting for the screen and network to stabilize, `redraw` minimizes the risk of interacting with incomplete or incorrect elements.
 
-
 ## Summary of waiting features
 
-| **Feature**          | **Description**                                                                 |
-|-----------------------|---------------------------------------------------------------------------------|
-| **`redraw`(automatic)** | TestDriver automatically waits for UI changes and network activity to resolve. |
-| **`wait-for-text`**   | Waits for specific text to appear on the screen.                                |
-| **`wait-for-image`**  | Waits for a specific image or visual element to appear on the screen.           |
+| **Feature**                                      | **Description**                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| **`redraw`(automatic)**                          | TestDriver automatically waits for UI changes and network activity to resolve. |
+| **[`wait-for-text`](/commands/wait-for-text)**   | Waits for specific text to appear on the screen.                               |
+| **[`wait-for-image`](/commands/wait-for-image)** | Waits for a specific image or visual element to appear on the screen.          |
 
 ## Key waiting features in TestDriver
 
 1. **Automatic Waiting with `redraw`**:
-  - TestDriver automatically waits for the machine before moving to the next step.
-  - This includes waiting for:
-    - UI changes to complete.
-    - Network activity to stabilize (for example, API calls).
-  - Reduces the need for manual waits, making tests faster and less prone to flakiness.
 
-2. **`wait-for-text` Command**:
-  - Waits for specific text to appear on the screen.
-  - Useful for validating dynamic content or ensuring that a page has fully loaded before proceeding.
+- TestDriver automatically waits for the machine before moving to the next step.
+- This includes waiting for:
+  - UI changes to complete.
+  - Network activity to stabilize (for example, API calls).
+- Reduces the need for manual waits, making tests faster and less prone to flakiness.
+
+2. **[`wait-for-text`](/commands/wait-for-text) Command**:
+
+- Waits for specific text to appear on the screen.
+- Useful for validating dynamic content or ensuring that a page has fully loaded before proceeding.
 
-3. **`wait-for-image` Command**:
-  - Waits for a specific image or visual element to appear on the screen.
-  - Ideal for verifying the presence of icons, logos, or other graphical elements.
+3. **[`wait-for-image`](/commands/wait-for-image) Command**:
 
+- Waits for a specific image or visual element to appear on the screen.
+- Ideal for verifying the presence of icons, logos, or other graphical elements.
 
 ## Commands for explicit waiting
 
-### 1. **`wait-for-text`**
+### 1. **[`wait-for-text`](/commands/wait-for-text)**
 
-The `wait-for-text` command pauses the test until the specified text appears on the screen. This is particularly useful for dynamic content that takes time to load.
+The [`wait-for-text`](/commands/wait-for-text) command pauses the test until the specified text appears on the screen. This is particularly useful for dynamic content that takes time to load.
 
 #### Syntax
 
@@ -64,9 +65,9 @@ The `wait-for-text` command pauses the test until the specified text appears on
 
 In this example, the test waits up to 10 seconds for the text "Welcome, Test User!" to appear.
 
-### **`wait-for-image`**
+### **[`wait-for-image`](/commands/wait-for-image)**
 
-The `wait-for-image` command pauses the test until the specified image or visual element appears on the screen.
+The [`wait-for-image`](/commands/wait-for-image) command pauses the test until the specified image or visual element appears on the screen.
 
 #### Syntax:
 
@@ -91,31 +92,39 @@ In this example, the test waits up to 8 seconds for the company logo to appear i
 TestDriver's **`redraw` function** is a built-in mechanism that automatically waits for the screen to stabilize before proceeding to the next step. This includes:
 
 1. **UI Changes**:
-  - Waits for animations, transitions, or DOM updates to complete.
-  - Ensures that the screen is fully rendered before interacting with elements.
+
+- Waits for animations, transitions, or DOM updates to complete.
+- Ensures that the screen is fully rendered before interacting with elements.
 
 2. **Network Stabilization**:
-  - Waits for network activity (for example, API calls, AJAX requests) to finish.
-  - Ensures that dynamic content is fully loaded before proceeding.
+
+- Waits for network activity (for example, API calls, AJAX requests) to finish.
+- Ensures that dynamic content is fully loaded before proceeding.
 
 3. **Screen Stabilization**:
-  - Continuously monitors the screen for changes and only moves forward when the screen is stable.
+
+- Continuously monitors the screen for changes and only moves forward when the screen is stable.
 
 ---
 
 ## Best practices for waiting
 
 2. **Leverage Automatic Waiting**:
-  - Rely on TestDriver's `redraw` function to handle most waiting scenarios automatically.
+
+- Rely on TestDriver's `redraw` function to handle most waiting scenarios automatically.
 
 1. **Use Explicit Waiting for Dynamic Elements**:
-  - Use `wait-for-text` or `wait-for-image` for elements that take time to load.
+
+- Use [`wait-for-text`](/commands/wait-for-text) or [`wait-for-image`](/commands/wait-for-image) for elements that take time to load.
 
 3. **Avoid Hardcoded Delays**:
-  - Replace hardcoded `sleep` or `wait` commands with dynamic waiting commands to improve test reliability.
+
+- Replace hardcoded `sleep` or [`wait`](/commands/wait) commands with dynamic waiting commands to improve test reliability.
 
 4. **Set Appropriate Timeouts**:
-  - Use reasonable timeouts for explicit waiting commands to balance reliability and test execution time.
+
+- Use reasonable timeouts for explicit waiting commands to balance reliability and test execution time.
 
 5. **Test Incrementally**:
-  - Add waiting commands step-by-step to ensure each part of the workflow is stable.
+
+- Add waiting commands step-by-step to ensure each part of the workflow is stable.

package/docs/interactive/assert.mdx

@@ -8,14 +8,17 @@ icon: "clipboard-check"
 # Command: `/assert`
 
 ## Description
+
 The `/assert` command ensures that a specific condition is true within your test. This is useful for verifying that tasks were completed successfully, just as a user would observe.
 
 ## Usage
+
 ```bash
 /assert <criteria>
 ```
 
 ## Behavior
+
 - The `/assert` command generates an assertion based on the specified criteria.
 - TestDriver takes a screenshot and uses it to verify that the condition described in the `expect` field is true.
 - If the condition isn't met, the test will fail and exit immediately.
@@ -23,17 +26,22 @@ The `/assert` command ensures that a specific condition is true within your test
 ## Example usage
 
 ### Basic assertion
+
 ```bash
 /assert No error message is displayed
 ```
+
 This generates the following command:
+
 ```yaml
 - command: assert
   expect: There is no error message
 ```
 
 ### Asynchronous assertion
+
 To speed up tests, use `async: true` to allow the test to continue without waiting for the assertion to pass:
+
 ```yaml
 - command: assert
   expect: There is no error message
@@ -41,14 +49,17 @@ To speed up tests, use `async: true` to allow the test to continue without waiti
 ```
 
 ## Protips
+
 - Use assertions sparingly to avoid slowing down your tests.
 - Combine `async: true` with assertions to improve test performance while still validating critical conditions.
 - Ensure the `expect` field clearly describes the condition to avoid ambiguity.
 
 ## Gotchas
+
 - If the condition in `expect` isn't met, the test will fail and exit immediately.
 - Overusing assertions can make tests slower and harder to maintain.
 
 ## Notes
+
 - The `/assert` command is ideal for validating key checkpoints in your test workflow.
 - Use this command to ensure that critical tasks, such as error-free execution or successful navigation, are completed as expected.

package/docs/interactive/generate.mdx

@@ -8,21 +8,26 @@ icon: "wand-sparkles"
 # Command: `/generate`
 
 ## Description
+
 The `/generate` command is an experimental feature that instructs TestDriver to create its own exploratory prompts. This command is used in the "Generate a Test Suite" demo and is designed to help automate the creation of exploratory test cases.
 
 ## Usage
+
 ```bash
 /generate
 ```
 
 ## Behavior
+
 - The `/generate` command analyzes the display and generates exploratory prompts for testing.
 - Each exploratory test is saved as a simple Markdown file containing a list of steps.
 - TestDriver generates 10 Markdown files every time the `/generate` command is called.
 - The generated files are stored in the `./testdriver/generate/*.md` directory.
 
 ## Example output
+
 Here's an example of a generated test file (`test-search-function.md`):
+
 ```markdown
 1. Click on the search icon.
 2. Type "real-time chat" into the search bar.
@@ -30,15 +35,21 @@ Here's an example of a generated test file (`test-search-function.md`):
 ```
 
 ## Protips
+
 - Use `/generate` to quickly create exploratory tests for regression testing or feature validation.
 - Combine `/generate` with the GitHub Action to generate and run regression tests in parallel.
 - Review the generated Markdown files and convert them into YAML test scripts for reuse.
 
 ## Gotchas
+
 - The `/generate` command is experimental and may not always produce perfect test cases. Review and refine the generated tests as needed.
 - Ensure the `./testdriver/generate/` directory exists and has write permissions.
 
 ## Notes
+
 - The `/generate` command is ideal for automating the creation of exploratory test cases and generating regression tests.
 - Generated tests can be merged into a regression test suite for continuous testing and validation.
+
+```
+
 ```

package/docs/interactive/run.mdx

@@ -6,34 +6,42 @@ icon: "play"
 ---
 
 ## Description
+
 The `/run` command is used to execute a test file from a specified file. This command performs each step defined in the test file and outputs the results.
 
 ## Usage
+
 ```bash
 /run <file>
 ```
 
 ## Example usage
+
 ```bash
 testdriverai
 > /run helloworld.yaml
 ```
+
 This command runs the `helloworld.yaml` test file, executing each command in the file sequentially.
 
 ## Behavior
+
 - TestDriver will execute the test file, performing each command as defined in the file.
 - If the test completes successfully, the program will exit with code `0`.
 - If any failures occur during the test, the program will output the errors and exit with code `1`.
 
 ## Protips
+
 - Ensure the test file path is correct and accessible before running the command.
 - Use descriptive filenames for your test files to make them easier to identify.
 - Combine `/run` with debugging tools to troubleshoot failing tests.
 
 ## Gotchas
+
 - This command will exit the program upon execution, so ensure all necessary setup is complete before running it.
 - Any errors in the test file (for example, invalid commands or missing arguments) will cause the test to fail.
 
 ## Notes
+
 - The `/run` command is ideal for executing pre-created test files in an interactive session.
 - Use this command to validate and debug your test files during development.

package/docs/interactive/save.mdx

@@ -6,14 +6,17 @@ icon: "floppy-disk"
 ---
 
 ## Description
+
 The `/save` command saves the current state of the test script to a file. This command generates a YAML file containing the history of executed commands and tasks, allowing you to reuse or modify the test script later.
 
 ## Usage
+
 ```bash
 /save
 ```
 
 ## Example usage
+
 ```bash
 testdriverai
 > /save
@@ -40,17 +43,21 @@ testdriverai
 ```
 
 ## Behavior
+
 - The `/save` command generates a YAML file with the current test script, including all executed steps and commands.
 - The file can be used as a reusable test file for future executions.
 
 ## Protips
+
 - Use `/save` frequently during interactive sessions to preserve your progress and avoid losing work.
 - Combine `/save` with `/run` to quickly test and iterate on your scripts.
 
 ## Gotchas
+
 - Ensure you have write permissions in the directory where the file will be saved.
 - The saved script reflects the current state of the session. Any unexecuted commands won't be included.
 
 ## Notes
+
 - The `/save` command is ideal for creating reusable test scripts from interactive sessions.
 - Use this command to document and share your test workflows with your team.

package/docs/interactive/undo.mdx

@@ -6,45 +6,53 @@ icon: "arrow-rotate-left"
 ---
 
 ## Description
+
 The `/undo` command removes the last generated command or step from the current test script. This is useful for quickly correcting mistakes or removing unintended actions during an interactive session.
 
 ## Usage
+
 ```bash
 /undo
 ```
 
 ## Behavior
+
 - The `/undo` command removes the most recently added command or step from the test script.
 - You can call `/undo` multiple times to remove multiple commands or steps.
 
 ## Example usage
 
 ### Before `/undo`
+
 ```yaml
-- step: 
+- step:
     - command: scroll-until-text
       text: Add to cart
-- step: 
+- step:
     - command: hover-text
       text: Add to cart
       action: click
 ```
 
 ### After `/undo`
+
 ```yaml
-- step: 
+- step:
     - command: scroll-until-text
       text: Add to cart
 ```
 
 ## Protips
+
 - Use `/undo` immediately after generating a command to quickly fix mistakes or refine your test script.
 - Combine `/undo` with `/save` to iteratively build and refine your test scripts.
 
 ## Gotchas
+
 - The `/undo` command only removes the last generated command or step. If you need to undo multiple actions, call `/undo` repeatedly.
 - Once a session is closed, you can't undo previously saved commands.
 
 ## Notes
+
 - The `/undo` command is ideal for interactive sessions where you are experimenting with test generation.
 - This command helps maintain a clean and accurate test script by allowing quick corrections.