testdriverai 5.2.1 → 5.3.0

package/docs/action/setup.mdx

@@ -0,0 +1,115 @@
+---
+title: "GitHub Action Setup Guide"
+sidebarTitle: "Setup Guide"
+description: "Learn how to set up and configure the TestDriver GitHub Action for automated cloud-based testing in your CI/CD workflows."
+---
+
+## Overview
+The TestDriver GitHub Action enables cloud-based testing using TestDriver's infrastructure. This guide will walk you through the steps to install and configure the GitHub Action for your repository.
+
+---
+
+## Step 1: Install the GitHub Action
+TestDriver Cloud Testing is performed via the TestDriver GitHub Action. You can find and install the action from the GitHub Marketplace:
+
+[**TestDriver.ai - GitHub Marketplace**](https://github.com/marketplace/actions/testdriver-ai)
+
+---
+
+## Step 2: Get Your API Key
+To execute TestDriver actions on our virtual machines, you'll need an API key. Follow these steps to retrieve and configure your API key:
+
+1. **Upgrade Your Account**: Ensure you have a paid TestDriver account.
+2. **Log In**: Go to the **Team Page** in your TestDriver dashboard.
+3. **Copy Your API Key**: Locate and copy your API key.
+4. **Add the API Key as a GitHub Secret**:
+   - Navigate to your repository settings in GitHub.
+   - Add a new secret named `TESTDRIVER_API_KEY` and paste your API key.
+
+---
+
+## Step 3: Create Your Workflow
+Now it's time to create your first TestDriver workflow. Add the following configuration to `.github/workflows/testdriver.yml`:
+
+```yaml
+name: TestDriver.ai
+
+permissions:
+  actions: read
+  contents: read
+  statuses: write
+  pull-requests: write
+
+on:
+  pull_request: # Run on every pull request event
+  schedule:
+    - cron: '0 * * * *' # Run every hour
+  push:
+    branches:
+      - main # Run on merge to the main branch
+  workflow_dispatch: # Manual trigger
+
+jobs:
+  test:
+    name: "TestDriver"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dashcamio/testdriver@main
+        version: "v5.0.7"
+        key: ${{ secrets.TESTDRIVER_API_KEY }}
+        os: linux
+        with:
+          prompt: |
+            1. /run testdriver.yaml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+```
+
+### Key Points:
+- **Trigger Conditions**: The `on` section defines when the workflow runs (e.g., pull requests, scheduled events, or manual triggers).
+- **API Key**: The `key` field uses the `TESTDRIVER_API_KEY` secret for authentication.
+- **Prompt**: The `prompt` field specifies the commands to execute. In this example, the `/run` command is used to execute a test file from the repository.
+
+---
+
+## Step 4: Deploy the Workflow
+Save the workflow file, create a new branch, and push it to your repository. Then, create a pull request to trigger the workflow.
+
+```bash
+git checkout -b testdriver
+git commit -am 'Add TestDriver GitHub Action'
+git push origin testdriver
+gh pr create --web
+```
+
+---
+
+## How It Works
+1. **Trigger**: The GitHub Action is triggered based on the conditions defined in the `on` section.
+2. **Authentication**: The `key` value authenticates your account.
+3. **VM Setup**: An ephemeral virtual machine is spawned on TestDriver's infrastructure.
+4. **Code Cloning**: The current branch's code is cloned onto the VM.
+5. **Dashcam Recording**: Dashcam begins recording the test execution.
+6. **Prerun Script**: If supplied, a prerun shell script is executed.
+7. **Prompt Execution**: The `prompt` is parsed as a Markdown list, and each item is executed sequentially.
+8. **Test Summary**: TestDriver summarizes the test and sets the exit code based on the pass or fail state.
+9. **Cleanup**: The VM is destroyed, and all data is wiped.
+
+---
+
+## Additional Features
+- **Dynamic Prompts**: You can use commands like `/explore`, supply variables, or dynamically generate prompts from earlier steps.
+- **Staging Workflows**: A common workflow involves waiting for staging to deploy before executing tests.
+
+---
+
+## Output
+For details on interpreting the output of the GitHub Action, refer to the [Action Output Documentation](../output).
+
+---
+
+## Notes
+- The TestDriver GitHub Action is a powerful tool for automating cloud-based testing.
+- Ensure your API key is securely stored as a GitHub secret.
+- For advanced workflows, consider using prerun scripts or dynamic prompts to customize your tests.

package/docs/bugs/jira.mdx

@@ -0,0 +1,208 @@
+---
+title: "Reporting Failed Tests to Jira"
+sidebarTitle: "Jira"
+description: "Step-by-step instructions to integrate TestDriver.ai with Jira for automated test failure tracking in CI/CD workflows."
+---
+
+# Automating Jira Ticket Creation for Test Failures Using TestDriver.ai and Jira GitHub Actions
+
+This guide explains how to integrate the **TestDriver.ai GitHub Action** with the **Jira GitHub Action** to automatically create a Jira ticket whenever a TestDriver.ai test fails. This workflow ensures that test failures are tracked in Jira, enabling teams to address issues promptly.
+
+---
+
+## Workflow Overview
+
+1. **Run Tests with TestDriver.ai**: Use the TestDriver.ai GitHub Action to execute your test suite.
+2. **Check for Test Failures**: Capture the test results and determine if any tests failed.
+3. **Create a Jira Ticket**: Use the Jira GitHub Action to create a new ticket for each test failure, including relevant details such as the test name, failure reason, and logs.
+
+---
+
+## Prerequisites
+
+1. **TestDriver.ai API Key**: Store your API key as a GitHub secret (e.g., `TESTDRIVER_API_KEY`).
+2. **Jira API Token**: Generate an API token from your Jira account and store it as a GitHub secret (e.g., `JIRA_API_TOKEN`).
+3. **Jira Base URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`).
+4. **Jira Project Key**: The key of the Jira project where tickets will be created (e.g., `TEST`).
+
+---
+
+## GitHub Actions Workflow
+
+Here’s a complete workflow that integrates TestDriver.ai and Jira:
+
+### Workflow File: `.github/workflows/testdriver-jira.yml````yaml
+name: TestDriver.ai with Jira Integration
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  run-tests:
+    name: Run Tests with TestDriver.ai
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+
+      - name: Run TestDriver.ai
+        id: testdriver
+        uses: testdriverai/action@main
+        with:
+          key: ${{ secrets.TESTDRIVER_API_KEY }}
+          prompt: |
+            1. Run all tests in the testdriver directory
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+
+      - name: Check for Test Failures
+        id: check-failures
+        run: |
+          if [[ "${{ steps.testdriver.outputs.success }}" == "false" ]]; then
+            echo "TestDriver.ai tests failed."
+            echo "failure=true" >> $GITHUB_ENV
+          else
+            echo "All tests passed."
+            echo "failure=false" >> $GITHUB_ENV
+          fi
+
+  create-jira-ticket:
+    name: Create Jira Ticket for Test Failures
+    needs: run-tests
+    runs-on: ubuntu-latest
+    if: env.failure == 'true'
+    steps:
+      - name: Create Jira Ticket
+        uses: atlassian/gajira-create@v3
+        with:
+          url: ${{ secrets.JIRA_BASE_URL }}
+          user: ${{ secrets.JIRA_USERNAME }}
+          api-token: ${{ secrets.JIRA_API_TOKEN }}
+          project: TEST # Replace with your Jira project key
+          summary: "Test Failure: ${{ steps.testdriver.outputs.summary }}"
+          description: |
+            A test failure occurred during the TestDriver.ai workflow.
+
+            **Test Summary**:
+            ${{ steps.testdriver.outputs.summary }}
+
+            **Failure Details**:
+            ${{ steps.testdriver.outputs.markdown }}
+
+            Please investigate the issue and resolve it promptly.
+          issuetype: Bug
+
+```
+
+---
+
+## Workflow Steps Explained
+
+### 1. **Run Tests with TestDriver.ai**
+The `testdriverai/action@main` step runs your TestDriver.ai tests and captures the results. The `outputs.success` variable indicates whether the tests passed or failed.```yaml
+- name: Run TestDriver.ai
+  id: testdriver
+  uses: testdriverai/action@main
+  with:
+    key: ${{ secrets.TESTDRIVER_API_KEY }}
+    prompt: |
+      1. Run all tests in the testdriver directory
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    FORCE_COLOR: "3"
+
+```
+
+---
+
+### 2. **Check for Test Failures**
+This step checks the `outputs.success` variable from the TestDriver.ai action. If the tests failed, it sets an environment variable (`failure=true`) to trigger the Jira ticket creation step.```yaml
+- name: Check for Test Failures
+  id: check-failures
+  run: |
+    if [[ "${{ steps.testdriver.outputs.success }}" == "false" ]]; then
+      echo "TestDriver.ai tests failed."
+      echo "failure=true" >> $GITHUB_ENV
+    else
+      echo "All tests passed."
+      echo "failure=false" >> $GITHUB_ENV
+    fi
+
+```
+
+---
+
+### 3. **Create a Jira Ticket**
+If any tests failed, the `create-jira-ticket` job uses the `atlassian/gajira-create` action to create a new Jira ticket. The ticket includes:
+- **Summary**: A brief description of the failure.
+- **Description**: Detailed information about the failure, including the test summary and markdown output from TestDriver.ai.```yaml
+- name: Create Jira Ticket
+  uses: atlassian/gajira-create@v3
+  with:
+    url: ${{ secrets.JIRA_BASE_URL }}
+    user: ${{ secrets.JIRA_USERNAME }}
+    api-token: ${{ secrets.JIRA_API_TOKEN }}
+    project: TEST # Replace with your Jira project key
+    summary: "Test Failure: ${{ steps.testdriver.outputs.summary }}"
+    description: |
+      A test failure occurred during the TestDriver.ai workflow.
+
+      **Test Summary**:
+      ${{ steps.testdriver.outputs.summary }}
+
+      **Failure Details**:
+      ${{ steps.testdriver.outputs.markdown }}
+
+      Please investigate the issue and resolve it promptly.
+    issuetype: Bug
+
+```
+
+---
+
+## Secrets Configuration
+
+Add the following secrets to your GitHub repository:
+1. **`TESTDRIVER_API_KEY`**: Your TestDriver.ai API key.
+2. **`JIRA_API_TOKEN`**: Your Jira API token.
+3. **`JIRA_BASE_URL`**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`).
+4. **`JIRA_USERNAME`**: Your Jira account email.
+
+---
+
+## Example Jira Ticket
+
+### Summary:
+`Test Failure: Login Test Failed`
+
+### Description:
+
+
+```
+A test failure occurred during the TestDriver.ai workflow.
+
+**Test Summary**:
+Login Test Failed
+
+**Failure Details**:
+- The login button was not clickable.
+- The error message was not displayed.
+
+Please investigate the issue and resolve it promptly.
+
+```---
+
+## Benefits of This Workflow
+
+1. **Automated Issue Tracking**: Automatically creates Jira tickets for test failures, ensuring no issues are overlooked.
+2. **Detailed Context**: Includes test summaries and failure details in the Jira ticket for easier debugging.
+3. **Streamlined Workflow**: Integrates testing and issue tracking into a single automated pipeline.
+
+---
+
+By combining TestDriver.ai and Jira GitHub Actions, you can automate the process of tracking test failures, improving collaboration and ensuring faster resolution of issues.

package/docs/cli/overview.mdx

@@ -0,0 +1,65 @@
+```mdx
+# Command: `testdriverai`
+
+## Description
+The `testdriverai` CLI is the primary interface for running, managing, and debugging TestDriver.ai scripts. It provides commands to execute tests, validate configurations, and interact with the TestDriver.ai framework.
+
+## Usage
+```bash
+testdriverai <command> [options]
+```
+
+## Available Commands
+| Command       | Description                                                                 |
+|---------------|-----------------------------------------------------------------------------|
+| `run`         | Executes a TestDriver.ai script.                                           |
+| `validate`    | Validates the syntax and structure of a TestDriver.ai script.              |
+| `init`        | Initializes a new TestDriver.ai project in the current directory.          |
+| `version`     | Displays the current version of the TestDriver.ai CLI.                     |
+| `help`        | Displays help information for the CLI or a specific command.               |
+
+## Example Usage
+
+### Running a Test Script
+```bash
+testdriverai run path/to/testdriver.yaml
+```
+This command runs the specified TestDriver.ai script, executing all steps defined in the file.
+
+### Validating a Script
+```bash
+testdriverai validate path/to/testdriver.yaml
+```
+This command checks the syntax and structure of the script to ensure it is valid before execution.
+
+### Initializing a New Project
+```bash
+testdriverai init
+```
+This command sets up a new TestDriver.ai project in the current directory, creating the necessary folder structure and configuration files.
+
+### Checking the Version
+```bash
+testdriverai version
+```
+This command displays the installed version of the TestDriver.ai CLI.
+
+### Getting Help
+```bash
+testdriverai help
+```
+This command displays general help information. To get help for a specific command, use:
+```bash
+testdriverai help <command>
+```
+
+## Protips
+- Use `testdriverai validate` before running a script to catch errors early.
+- Combine `testdriverai run` with CI/CD pipelines to automate test execution.
+- Use the `--debug` flag with `run` to enable detailed logging for troubleshooting.
+
+## Notes
+- The `testdriverai` CLI is cross-platform and works on macOS, Windows, and Linux.
+- Ensure you have the required dependencies installed and configured before running scripts.
+- For more advanced usage, refer to the official TestDriver.ai documentation.
+```

package/docs/commands/assert.mdx

@@ -0,0 +1,31 @@
+---
+title: "assert"
+---
+
+## Description
+The `assert` command is used to validate that a specific condition is true. It ensures that a task was completed successfully by checking the screen for the expected outcome. If the condition is not met, the test will fail.
+
+## Arguments
+| Argument   | Type      | Description                                                                 |
+|------------|-----------|-----------------------------------------------------------------------------|
+| `expect`   | `string`  | The condition to check. This should describe what you expect to see on the screen. |
+| `async`    | `boolean` | (Optional) If set to `true`, the test will continue without waiting for the assertion to pass. Default is `false`. |
+
+## Example Usage
+```yaml
+command: assert
+expect: the video is playing
+```
+
+### Example with `async`
+
+```yaml
+command: assert
+expect: There is no error message
+async: true
+```
+
+## Notes
+- Use `async: true` to speed up tests by allowing non-blocking assertions. However, the test will still fail if the condition is not met.
+- Assertions should be used sparingly, as too many can slow down the test execution.
+- Ensure the `expect` string clearly describes the condition to avoid ambiguity.

package/docs/commands/exec.mdx

@@ -0,0 +1,42 @@
+---
+title: "exec"
+---
+
+## Description
+The `exec` command allows you to execute custom NodeJS scripts within your TestDriver.ai tests. This is useful for tasks like generating dynamic data, interacting with APIs, or performing custom logic during a test. The output of the script can be stored in a variable for use in subsequent steps.
+
+## Arguments
+| Argument   | Type      | Description                                                                 |
+|------------|-----------|-----------------------------------------------------------------------------|
+| `js`       | `string`  | The NodeJS script to execute. The script must define the output as `result`. |
+| `output`   | `string`  | The variable name to store the result of the script. This variable can be accessed as `${OUTPUT.<var>}` in future steps. |
+
+## Example Usage
+```yaml
+version: 5.1.0
+session: 67e57d614dc25283aa0872a9
+steps:
+  - prompt: Log in with the totp
+    commands:
+      - command: exec
+        output: totp 
+        js: |
+          const { TOTP } = require("totp-generator");
+          let otp = TOTP.generate("JBSWY3DPEB3W64TMMQQQ").otp;
+          result = otp;
+      - command: type
+        text: ${OUTPUT.totp}
+```
+
+## Protips
+- Do not overwrite the `result` variable in your script, as it is used to store the output.
+- Ensure that all required NPM packages are installed locally using `npm install`. If using GitHub Actions, include the installation in the `prerun` step.
+- NodeJS code executes in the same context as the calling process on the host machine, using the [VM](https://nodejs.org/api/vm.html) module internally.
+
+## Gotchas
+- This command is only supported on hosted Windows runners. Hosted Linux runners do not yet support the `prerun` step.
+- Ensure your NodeJS environment is properly configured with all necessary dependencies.
+
+## Notes
+- The `exec` command is available starting from TestDriver.ai version `5.1.0`.
+- Use this command to integrate custom logic or external libraries into your tests.

package/docs/commands/focus-application.mdx

@@ -0,0 +1,29 @@
+---
+title: "focus-application"
+---
+
+## Description
+The `focus-application` command is used to bring a specific application window to the foreground. This ensures that subsequent commands interact with the correct application during a test.
+
+## Arguments
+| Argument   | Type      | Description                                                                 |
+|------------|-----------|-----------------------------------------------------------------------------|
+| `name`     | `string`  | The name of the application to focus. This should match the application's display name. |
+
+## Example Usage
+```yaml
+command: focus-application
+name: Google Chrome
+```
+
+## Protips
+- Ensure the application name matches the exact name displayed in your operating system's task manager or application switcher.
+- Use this command at the start of a test or before interacting with an application to avoid focus-related issues.
+
+## Gotchas
+- If the specified application is not running, the command will fail. Ensure the application is open before using this command.
+- On macOS, the application name is case-sensitive.
+
+## Notes
+- The `focus-application` command is useful for multi-application workflows where you need to switch between different apps during a test.
+- This command is supported on both Windows and macOS environments.

package/docs/commands/hover-image.mdx

@@ -0,0 +1,32 @@
+---
+title: "hover-image"
+---
+
+## Description
+The `hover-image` command is used to locate an image on the screen based on a description and perform an action on it. This can include hovering, clicking, right-clicking, or double-clicking the image.
+
+## Arguments
+| Argument      | Type     | Description                                                                 |
+|---------------|----------|-----------------------------------------------------------------------------|
+| `description` | `string` | A description of the image and what it represents. Do not include the image itself here. |
+| `action`      | `string` | The action to take when the image is found. Available actions are: `click`, `right-click`, `double-click`, `hover`. |
+
+## Example Usage
+```yaml
+command: hover-image
+description: search icon in the webpage content
+action: click
+```
+
+## Protips
+- Use clear and concise descriptions for the image to improve detection accuracy.
+- Ensure the action specified matches the intended interaction with the image.
+- If the hover-image command fails to locate an image based on the provided description, consider using the match-image command instead. The match-image command is specifically designed for scenarios where precise image matching is required, such as when the visual element cannot be reliably described with text. It works by directly comparing the image on the screen with a reference image file.
+
+## Gotchas
+- If the image cannot be located based on the description, the command will fail.
+- Ensure the screen resolution and scaling settings are consistent to avoid detection issues.
+
+## Notes
+- The `hover-image` command is useful for interacting with visual elements that cannot be identified using text-based selectors.
+- Supported actions allow flexibility in how the image is interacted with during the test.

package/docs/commands/hover-text.mdx

@@ -0,0 +1,37 @@
+---
+title: "hover-text"
+---
+
+## Description
+The `hover-text` command is used to locate text on the screen based on a description and perform an action on it. This can include hovering, clicking, right-clicking, or double-clicking the text.
+
+## Arguments
+| Argument      | Type     | Description                                                                 |
+|---------------|----------|-----------------------------------------------------------------------------|
+| `text`        | `string` | The text to find on the screen. The longer and more unique, the better.     |
+| `description` | `string` | A description of the text and what it represents. The actual text itself should not be included here. |
+| `action`      | `string` | The action to take when the text is found. Available actions are: `click`, `right-click`, `double-click`, `hover`. |
+| `method`      | `enum`   | The matching algorithm to use. Possible values are `turbo` (default) and `ai`. |
+
+## Example Usage
+```yaml
+command: hover-text
+text: Sign Up
+description: link in the header
+action: click
+```
+
+## Protips
+- Use unique and specific text to improve detection accuracy.
+- Choose the appropriate `method` for your use case:
+  - `turbo`: Faster and more efficient for most scenarios.
+  - `ai`: More robust for complex or ambiguous text matching.
+- Ensure the action specified matches the intended interaction with the text.
+
+## Gotchas
+- If the text cannot be located, the command will fail. Ensure the text is visible on the screen and matches exactly.
+- Variations in font size, style, or screen resolution may affect detection accuracy.
+
+## Notes
+- The `hover-text` command is ideal for interacting with textual elements that cannot be identified using other selectors.
+- Supported actions allow flexibility in how the text is interacted with during the test.

package/docs/commands/if.mdx

@@ -0,0 +1,43 @@
+---
+title: "if"
+---
+
+## Description
+The `if` command is used to conditionally execute a set of commands based on whether a specified condition evaluates to true or false. If the condition is true, the commands in the `then` block are executed. Otherwise, the commands in the `else` block are executed.
+
+## Arguments
+| Argument    | Type              | Description                                                                 |
+|-------------|-------------------|-----------------------------------------------------------------------------|
+| `condition` | `string`          | The condition to evaluate.                                                 |
+| `then`      | `list of commands`| The commands to run if the condition is true.                              |
+| `else`      | `list of commands`| The commands to run if the condition is false.                             |
+
+## Example Usage
+```yaml
+command: if
+condition: the text "Accept Cookies" is visible
+then:
+  - command: hover-text
+    text: Accept Cookies
+    description: cookie banner button
+    action: click
+else:
+  - command: hover-text
+    text: Sign Up
+    description: link in the header
+    action: click
+```
+
+## Protips
+- Ensure the `condition` is clearly defined and evaluates correctly to avoid unexpected behavior.
+- Use descriptive `then` and `else` blocks to handle both outcomes effectively.
+- Combine the `if` command with other commands like `hover-text` or `focus-application` to create dynamic workflows.
+
+## Gotchas
+- If the `condition` is invalid or cannot be evaluated, the command will fail.
+- Ensure all commands in the `then` and `else` blocks are valid and properly formatted.
+
+## Notes
+- The `if` command is useful for creating conditional logic in your tests, allowing for more dynamic and flexible workflows.
+- Both the `then` and `else` blocks are optional, but at least one must be provided.
+```

package/docs/commands/match-image.mdx

@@ -0,0 +1,41 @@
+---
+title: "match-image"
+---
+
+## Description
+The `match-image` command is used to locate an image on the screen by matching it with a reference image file and performing an action (e.g., click or hover) at its center. This command is particularly useful for interacting with elements that the AI has difficulty locating using descriptions or other methods.
+
+## Arguments
+| Argument       | Type     | Description                                                                 |
+|----------------|----------|-----------------------------------------------------------------------------|
+| `path`         | `string` | The relative path to the image file that needs to be matched on the screen. Do not include `testdriver/screenshots/*/` in the path. |
+| `action`       | `string` | The action to perform when the image is found. Available actions are: `click` or `hover`. The action will be performed at the center of the matched image. |
+
+## Example Usage
+```yaml
+command: match-image
+path: button.png
+action: click
+```
+
+## How It Works
+- The `match-image` command takes a screenshot of the desktop and searches for the location of the reference image within the screenshot.
+- The matching logic looks for the most similar image within the screenshot, not an exact match. If the similarity is below ~80%, it will search additional scales. If no match is found, the command will fail.
+- Screenshots should be stored in the `testdriver/screenshots/(mac/linux/windows)/` directory. TestDriver dynamically resolves the correct image based on the current platform.
+
+## Protips
+- To create high-quality screenshots for matching:
+  - Download the video of the test and open it at "full" or "actual" size on your computer.
+  - Use a screenshot tool like Cleanshot X to capture the target element.
+  - Center the clickable element as much as possible within the screenshot.
+- Ensure the image file is clear and free of unnecessary visual noise to improve matching accuracy.
+
+## Gotchas
+- If the image match is below ~80% similarity, the command will fail.
+- Variations in screen resolution, scaling settings, or platform-specific UI differences may affect matching accuracy.
+- Ensure the image file is stored in the correct directory structure (`testdriver/screenshots/(mac/linux/windows)/`) for dynamic resolution.
+
+## Notes
+- The `match-image` command is ideal for interacting with visual elements that cannot be reliably described or located using other commands like `hover-image`.
+- This command supports flexible scaling to account for minor differences in image size or resolution.
+- Use this command as a fallback when other methods fail to locate the desired element.

package/docs/commands/press-keys.mdx

@@ -0,0 +1,30 @@
+---
+title: "press-keys"
+---
+
+## Description
+The `press-keys` command is used to simulate typing a keyboard combination. This is useful for triggering shortcuts or interacting with applications via keyboard input.
+
+## Arguments
+| Argument | Type                | Description                                                                 |
+|----------|---------------------|-----------------------------------------------------------------------------|
+| `keys`   | `yml array of strings` | A list of keys to press together. Keys are automatically remapped for different operating systems. |
+
+## Example Usage
+```yaml
+command: press-keys
+keys: [command, space]
+```
+
+## Protips
+- Use this command to trigger system-wide or application-specific shortcuts, such as opening Spotlight on macOS or the Start menu on Windows.
+- Ensure the keys specified are valid and supported by the operating system or application.
+
+## Gotchas
+- Key mappings may differ between operating systems. For example, `command` on macOS is remapped to `ctrl` on Windows.
+- Ensure the application or system is in focus when using this command to avoid unexpected behavior.
+
+## Notes
+- The `press-keys` command is ideal for automating workflows that rely on keyboard shortcuts.
+- This command supports cross-platform key remapping to ensure compatibility across macOS, Windows, and Linux.
+```