testdriverai 5.6.3 → 5.6.5

package/docs/guide/lifecycle-prerun.mdx

@@ -0,0 +1,191 @@
+---
+title: "Prerun Scripts"
+sidebarTitle: "Prerun Scripts"
+description: "Learn how to customize and set up your TestDriver environment to optimize your CI/CD pipeline."
+icon: "terminal"
+---
+
+## Prerun configuration
+
+## The default `prerun` script
+When setting up your TestDriver environment, a default prerun script is automatically generated when you run:
+```bash
+ testdriverai init
+``` 
+
+The directory structure is created like this:
+```bash
+testdriver
+├── lifecycle
+│   └── prerun.yaml
+```
+
+This script includes essential commands to ensure your VM is ready for testing. You can customize this script to suit your specific needs, but it's important to understand that it serves as a baseline for your test environment. It looks like this:
+ 
+
+```yaml ./lifecycle/prerun.yaml
+version: 5.1.1
+steps:
+  - prompt: launch chrome
+    commands:
+      - command: exec
+        lang: shell
+        linux: |
+          jumpapp google-chrome --disable-fre --no-default-browser-check --no-first-run "${TD_WEBSITE}" &
+          exit
+        mac: |
+          open -na "Google Chrome" --args --disable-fre --no-default-browser-check --no-first-run --disable-features=PasswordManagerEnabled "${TD_WEBSITE}" &
+          exit
+        windows:
+          Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "--start-maximized", "${TD_WEBSITE}"
+          exit
+      - command: wait-for-text
+        text: "Google Chrome"
+        timeout: 30000
+```
+Take note that it defaults to launching the Chrome browser. If you want to use a different browser, you can modify the `prompt` and `commands` sections accordingly. 
+
+<Warning>
+The `wait-For-text` command is crucial for ensuring that the browser is fully loaded before proceeding with the test steps. If you are testing a web application, you may want to adjust the `text` parameter to match the expected app name, title or content of the page.
+</Warning>
+
+If a file is found at `./lifecycle/prerun.yaml`, it's executed _before_ the test begins. _This will happen even if you have a pre or post test script defined in your GitHub Actions workflow._ This file works like any other TestDriver file and is commonly used to perform tasks such as opening a browser, navigating to a specific page, or resetting the application state.
+
+### Prerun diagram
+```mermaid
+graph TD
+    A{Is prerun available at ./lifecycle/prerun.yaml and a testfile present in ./somedirectory?}
+    A -->|Yes| B[Run ./lifecycle/prerun.yaml]
+    B --> C[Run ./somedirectory/testfile.yaml]
+    A -->|No| D{Is ./somedirectory/testfile.yaml present?}
+    D -->|Yes| C
+```
+---
+
+## Examples
+For example, the `prerun.yaml` file can be combined with the [`exec`](/commands/exec) command to open the Chrome browser and navigate to a page, similar to the example provided above. This ensures that the test environment is properly set up before the test starts. _Note that the prerun is a TestDriver test file like any other, combining commands to complete a task_.
+
+---
+
+### Opening a different browser
+Here is an example of a `prerun.yaml` file that opens Firefox instead of Chrome (note the `wait-for-text` command at the end):
+
+```yaml {5, 16} ./lifecycle/prerun.yaml
+version: 5.1.1
+steps:
+  - prompt: launch firefox
+    commands:
+      - command: exec
+        lang: shell
+        linux: |
+            jumpapp firefox --no-default-browser-check --no-first-run "${TD_WEBSITE}" &
+            exit
+
+        mac: |
+            open -na "Firefox" --args --no-default-browser-check --no-first-run "${TD_WEBSITE}" &
+            exit
+
+        windows: |
+            Start-Process "C:/Program Files/Mozilla Firefox/firefox.exe" -ArgumentList "--no-default-browser-check", "--no-first-run", "${TD_WEBSITE}"
+            exit
+      - command: wait-for-text
+        text: "Firefox"
+        timeout: 30000
+```
+
+---
+### Loading a calculator app on Linux, MacOS or Windows
+```yaml ./lifecycle/prerun.yaml
+version: 5.5.5
+steps:
+  - prompt: launch a calculator
+    commands:
+      - command: exec
+        lang: shell
+        linux: |
+          linux: |
+            jumpapp /usr/bin/galculator > /dev/null 2>&1 &
+            exit
+        mac: |
+          open "/Applications/Calculator.app"
+          wait
+        windows:
+          start /B calc.exe
+          timeout /t 5
+      - command: wait-for-text
+        text: "galculator"
+        timeout: 30000
+```
+
+## Key points
+- **Provisioning**: Prerun scripts allow you to provision the VM with the necessary tools and configurations before running tests.
+- **Reproducibility**: By ensuring a consistent environment, prerun scripts help prevent flaky tests caused by environmental differences.
+- **Flexibility**: You can use prerun scripts to customize the VM for specific test scenarios, such as installing alternative browsers or setting up staging environments.
+
+---
+
+## Best practices
+- **Keep It Simple**: Write clear and concise prerun scripts to minimize setup time and reduce complexity.
+- **Error Handling**: Include checks to verify that dependencies are installed successfully. Log errors to help debug issues.
+- **Optimize Performance**: Cache dependencies or use lightweight tools to speed up the setup process.
+- **Security**: Avoid hardcoding sensitive information in prerun scripts. Use GitHub secrets to securely pass credentials or tokens.
+
+
+---
+## Example
+
+### Using `exec` shell commands in prerun to set up a test file
+Here we're doing the exact same thing as the previous example, except the `shell` context is setting up the calculator app to be used by the test file. This method is useful if you are going to use the same application over again in many tests.
+
+```yaml ./lifecycle/prerun.yaml
+version: 5.5.5
+steps:
+  - prompt: launch a calculator
+    commands:
+      - command: exec
+        lang: shell
+        linux: |
+          linux: |
+            jumpapp /usr/bin/galculator > /dev/null 2>&1 &
+            exit
+        mac: |
+          open "/Applications/Calculator.app"
+          wait
+        windows: start /B calc.exe
+          timeout /t 5
+      - command: wait-for-text
+        text: "calculator"
+        timeout: 30000
+```
+
+Then in the test file, the runner will already have the calculator loaded before it runs this test:
+```yaml testfile.yaml
+version: 5.5.5
+steps:
+    - prompt: /try 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
+```
+
+<Tip>See [`exec`](/commands/exec) for more examples and use cases of including `shell` or `js` context and proper usage within your prerun!</Tip>
+
+---
+
+## Notes
+- Prerun scripts are executed on the VM before the test suite begins.
+- They're essential for ensuring a consistent and reliable test environment.
+- For advanced workflows, combine prerun scripts with TestDriver prompts to create dynamic and flexible test setups.
+- Currently, there is no teardown task implemented within TestDriver itself. This is due to the nature of deployed tests: when running on GitHub Actions, the virtual machine (VM) is _ephemeral_, meaning everything is destroyed after the test run.

package/docs/guide/locating.mdx

@@ -9,15 +9,15 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 
 ---
 
-## Key Principles for Locating Elements
+## 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 (e.g., "button that submits the form").
-   - Instead, describe how it looks (e.g., "blue button with the text 'Submit' in the bottom-right corner").
+   - 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.
@@ -29,7 +29,7 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 
 ---
 
-## Examples of Effective Descriptions
+## Examples of effective descriptions
 
 ### 1. Buttons
 - **Good**: "Blue button with the text 'Sign In' in the top-right corner."
@@ -43,7 +43,7 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 - **Good**: "Magnifying glass icon next to the search bar."
 - **Bad**: "Search icon that opens the search feature."
 
-### 4. Input Fields
+### 4. Input fields
 - **Good**: "White input box labeled 'Email Address' above the password field."
 - **Bad**: "Field where the user enters their email."
 
@@ -53,11 +53,11 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 
 ---
 
-## How to Write TestDriver Commands
+## How to write TestDriver commands
 
-### Example: Locating a Button
+### Example: Locating a button
 
-#### YAML Command:
+#### TestDriver command:
 
 ```yaml
 - command: hover-text
@@ -71,24 +71,21 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 
 ---
 
-### Example: Locating an Icon
+### Example: Locating an icon
 
-#### YAML Command:
+#### TestDriver command:
 
 ```yaml
 - command: hover-image
   description: Magnifying glass icon next to the search bar
   action: click
-
-
 ```
 
-
 ---
 
-### Example: Locating a Link
+### Example: Locating a link
 
-#### YAML Command:
+#### TestDriver command:
 
 ```yaml
 - command: hover-text
@@ -102,7 +99,7 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
 
 ---
 
-## Debugging Element Detection
+## Debugging element detection
 
 1. **Run the Test**:
    - Execute the test using TestDriver.
@@ -113,12 +110,12 @@ TestDriver uses **visual understanding** to locate elements on the screen. Unlik
    - If the wrong element is highlighted, refine your description.
 
 3. **Adjust the Description**:
-   - Add more specific visual details (e.g., color, position, associated text).
+   - Add more specific visual details (for example, color, position, associated text).
    - Avoid generic terms like "button" or "icon" without additional context.
 
 ---
 
-## Best Practices
+## Best practices
 
 1. **Be Specific**:
    - Include as many unique visual traits as possible to differentiate the element from others.

package/docs/guide/variables.mdx

@@ -5,7 +5,7 @@ description: "Learn how to use variables in TestDriver for dynamic data handling
 icon: "square-root-variable"
 ---
 
-# Using Variables in TestDriver
+# Using variables in TestDriver
 
 Variables in **TestDriver** allow you to dynamically store and reuse data during test execution. This feature is particularly useful for handling dynamic content, passing data between steps, and customizing test behavior based on runtime conditions.
 
@@ -16,7 +16,7 @@ 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:
+#### Test file example:
 
 ```yaml
 version: 5.1.0
@@ -41,7 +41,7 @@ steps:
         text: ${OUTPUT.randomNumber}
 ```
 
-## GitHub Actions Example
+## GitHub Actions example
 
 ```yaml
 name: TestDriver with Variables
@@ -74,7 +74,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           FORCE_COLOR: "3"
 ```
-#### Test File
+#### Test file
 
 ```yaml
 version: 4.2.18
@@ -99,9 +99,9 @@ steps:
         action: click
 ```
 
-### **Capturing Outputs as Variables**
+### **Capturing outputs as variables**
 
-#### Test File Example:
+#### Test file example:
 
 ```yaml
 version: 5.1.0
@@ -121,10 +121,10 @@ steps:
         expect: "${OUTPUT.welcomeMessage}" == "Welcome, Test User!"
 ```
 
-## Best Practices for Using Variables
+## Best practices for using variables
 
 1. **Use Descriptive Names**:
-  - Name variables clearly to indicate their purpose (e.g., `capturedText`, `randomNumber`).
+  - Name variables clearly to indicate their purpose (for example, `capturedText`, `randomNumber`).
 
 2. **Secure Sensitive Data**:
   - Use environment variables for sensitive information like credentials or API keys.

package/docs/guide/waiting.mdx

@@ -5,7 +5,7 @@ description: "Waiting in TestDriver: Ensuring Stability and Reducing Flakiness"
 icon: "clock"
 ---
 
-# Waiting in TestDriver: Ensuring Stability and Reducing Flakiness
+# 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. 
 
@@ -14,7 +14,7 @@ Waiting is a critical feature in TestDriver that ensures tests are stable and re
 - By waiting for the screen and network to stabilize, `redraw` minimizes the risk of interacting with incomplete or incorrect elements.
 
 
-## Summary of Waiting Features
+## Summary of waiting features
 
 | **Feature**          | **Description**                                                                 |
 |-----------------------|---------------------------------------------------------------------------------|
@@ -22,13 +22,13 @@ Waiting is a critical feature in TestDriver that ensures tests are stable and re
 | **`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.           |
 
-## Key Waiting Features in TestDriver
+## 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 (e.g., API calls).
+    - 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**:
@@ -40,13 +40,13 @@ Waiting is a critical feature in TestDriver that ensures tests are stable and re
   - Ideal for verifying the presence of icons, logos, or other graphical elements.
 
 
-## Commands for Explicit Waiting
+## Commands for explicit waiting
 
 ### 1. **`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.
 
-#### Syntax:
+#### Syntax
 
 ```yaml
 - command: wait-for-text
@@ -54,7 +54,7 @@ The `wait-for-text` command pauses the test until the specified text appears on
   timeout: <time in milliseconds> # Optional, defaults to 5000ms
 ```
 
-#### Example:
+#### Example
 
 ```yaml
 - command: wait-for-text
@@ -86,7 +86,7 @@ The `wait-for-image` command pauses the test until the specified image or visual
 
 In this example, the test waits up to 8 seconds for the company logo to appear in the top-left corner.
 
-## Automatic Waiting with `redraw`
+## Automatic waiting with `redraw`
 
 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:
 
@@ -95,7 +95,7 @@ TestDriver's **`redraw` function** is a built-in mechanism that automatically wa
   - Ensures that the screen is fully rendered before interacting with elements.
 
 2. **Network Stabilization**:
-  - Waits for network activity (e.g., API calls, AJAX requests) to finish.
+  - Waits for network activity (for example, API calls, AJAX requests) to finish.
   - Ensures that dynamic content is fully loaded before proceeding.
 
 3. **Screen Stabilization**:
@@ -103,7 +103,7 @@ TestDriver's **`redraw` function** is a built-in mechanism that automatically wa
 
 ---
 
-## Best Practices for Waiting
+## Best practices for waiting
 
 2. **Leverage Automatic Waiting**:
   - Rely on TestDriver's `redraw` function to handle most waiting scenarios automatically.

package/docs/importing/csv.mdx

@@ -9,7 +9,7 @@ This guide demonstrates how to convert user stories from **CSV files** into indi
 
 ---
 
-## Workflow Overview
+## Workflow overview
 
 1. **Export User Stories**: Extract user stories from TestRail, CSV, or Jira.
 2. **Convert to Test Files**: Use a Node.js script to generate individual YAML test files for each user story.
@@ -17,11 +17,11 @@ This guide demonstrates how to convert user stories from **CSV files** into indi
 
 ---
 
-## Step 1: Export User Stories
+## Step 1: Export user stories
 
-Export user stories from your source (TestRail, CSV, or Jira) and save them in a structured format (e.g., JSON or CSV). For example:
+Export user stories from your source (TestRail, CSV, or Jira) and save them in a structured format (for example, JSON or CSV). For example:
 
-### Example CSV File (`user_stories.csv`):
+### Example CSV file (`user_stories.csv`):
 
 | User Story ID | User Story Title          | Description                          |
 |---------------|---------------------------|--------------------------------------|
@@ -31,18 +31,18 @@ Export user stories from your source (TestRail, CSV, or Jira) and save them in a
 
 ---
 
-## Step 2: Node.js Script to Convert User Stories into Test Files
+## Step 2: Node.js script to convert user stories into test files
 
 Create a Node.js script to read the exported data and generate individual YAML test files for each user story.
 
-### Install Required Dependencies
+### Install required dependencies
 
 ```bash
 npm install yaml fs csv-parser
 
 ```
 
-### Node.js Script (`generate-tests.js`)
+### Node.js script (`generate-tests.js`)
 
 ```javascript
 const fs = require('fs');
@@ -73,7 +73,7 @@ function generateTestFile(userStory) {
   };
 
   const yamlContent = yaml.stringify(testContent);
-  const fileName = `test_${id}.yml`;
+  const fileName = `test_${id}.yaml`;
   const filePath = path.join(outputDir, fileName);
 
   fs.writeFileSync(filePath, yamlContent, 'utf8');
@@ -92,23 +92,22 @@ fs.createReadStream(inputFile)
 
 ```
 
-### Run the Script
+### Run the script
 
 ```bash
 node generate-tests.js
-
 ```
 
-This script will generate individual YAML test files (e.g., `test_1.yml`, `test_2.yml`) in the `testdriver/` directory.
+This script will generate individual YAML test files (for example, `test_1.yaml`, `test_2.yaml`) in the `testdriver/` directory.
 
 ---
 
-## Step 3: GitHub Actions Workflow to Run Tests
+## Step 3: GitHub Actions workflow to run tests
 
 Create a GitHub Actions workflow to execute the generated test files in parallel.
 
-### GitHub Actions Workflow (`.github/workflows/run-tests.yml`)
-```yaml
+### GitHub Actions workflow (`.github/workflows/run-tests.yaml`)
+```yaml [expandable]
 name: Run TestDriver Tests
 
 on:
@@ -131,7 +130,7 @@ jobs:
       - name: Find all test files
         id: test_list
         run: |
-          FILES=$(ls ./testdriver/*.yml)
+          FILES=$(ls ./testdriver/*.yaml)
           FILES_JSON=$(echo "$FILES" | jq -R -s -c 'split("\n")[:-1]')
           echo "::set-output name=files::$FILES_JSON"
 
@@ -161,20 +160,20 @@ jobs:
 
 ---
 
-## Step 4: Secure API Key
+## Step 4: Secure API key
 
-Store your TestDriver API key as a GitHub secret (e.g., `TD_API_KEY`) to securely authenticate your tests.
+Store your TestDriver API key as a GitHub secret (for example, `TD_API_KEY`) to securely authenticate your tests.
 
 ---
 
-## Step 5: Commit and Push
+## Step 5: Commit and push
 
-1. Commit the `generate-tests.js` script, `user_stories.csv`, and `.github/workflows/run-tests.yml` to your repository.
+1. Commit the `generate-tests.js` script, `user_stories.csv`, and `.github/workflows/run-tests.yaml` to your repository.
 2. Push the changes to the `main` branch.
 
 ---
 
-## Step 6: Run the Workflow
+## Step 6: Run the workflow
 
 The GitHub Actions workflow will automatically:
 1. Gather all test files in the `testdriver/` directory.
@@ -182,12 +181,12 @@ The GitHub Actions workflow will automatically:
 
 ---
 
-## Example Output
+## Example output
 
 - **Generated Test Files**:
-  - `testdriver/test_1.yml`
-  - `testdriver/test_2.yml`
-  - `testdriver/test_3.yml`
+  - `testdriver/test_1.yaml`
+  - `testdriver/test_2.yaml`
+  - `testdriver/test_3.yaml`
 
 - **GitHub Actions Dashboard**:
   - Each test file is executed as a separate job, and the results are displayed in the Actions tab.