testdriverai 6.2.1 → 7.0.0

package/docs/v7/commands/hover-image.mdx

@@ -0,0 +1,69 @@
+---
+title: "hover-image"
+sidebarTitle: "hover-image"
+description: "Locate an image on the screen and perform an action."
+icon: "image"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/hover-image-replay.mdx";
+import Example from "/snippets/tests/hover-image-yaml.mdx";
+
+<Replay />
+<Example />
+
+## 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, double-clicking or dragging the image.
+
+## Arguments
+
+| Argument      | Type     | Description                                                                                                                                                                       |
+| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description` | `string` | A description of the image and what it represents. Don't 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`. Also supports `drag-start` and `drag-end` for dragging images |
+
+The `hover-image` command is useful for interacting with visual elements that can't be identified using text-based selectors.
+
+---
+
+## Drag functionality
+
+- The `drag-start` and `drag-end` actions are used to drag an image to a specific location. `drag-start` could be the image (or inner text element, in which case using `hover-text` is preferred) to drag and `drag-end` is the location is supposed to be dragged to. This could be coupled with [`hover-text`](/commands/hover-text) or [`match-image`](/commands/match-image) or just `hover-image`.
+
+### Example: Drag and Drop to upload an image
+
+```yaml drag-and-drop.yaml
+version: 6.0.0
+steps:
+  - prompt: click on the image of a shopping cart
+    commands:
+      - command: hover-image
+        description: a pink tree image in the file explorer
+        action: drag-start
+      - command: hover-text
+        text: Upload
+        description: The drop zone of the application
+        action: drag-end
+```
+
+---
+
+## 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 can't be reliably described with text. It works by directly comparing the image on the screen with a reference image file.
+
+## Gotchas
+
+- If the image can't be located based on the description, the command will fail.
+- Ensure the screen resolution and scaling settings are consistent to avoid detection issues.

package/docs/v7/commands/hover-text.mdx

@@ -0,0 +1,47 @@
+---
+title: "hover-text"
+sidebarTitle: "hover-text"
+description: "Hover or click on text elements based on a description."
+icon: "text"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/hover-text-replay.mdx";
+import Example from "/snippets/tests/hover-text-yaml.mdx";
+
+<Replay />
+<Example />
+
+## 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. Longer and unique is better.                                                                                                                                                                |
+| `description` | `string` | A description of the text and what it represents. The actual text itself shouldn't be included here.                                                                                                                        |
+|   `action`    | `string` | The action to take when the text is found. Available actions are: `click`, `right-click`, `double-click`, `hover`. Also supports `drag-start` and `drag-end` for [dragging text](/commands/hover-image#drag-functionality). |
+|   `method`    |  `enum`  | The matching algorithm to use. Possible values are `turbo` (default) and `ai`.                                                                                                                                              |
+|   `timeout`   | `number` | **(Optional)** The duration in milliseconds to wait for the text to appear. Default is `5000` (5 seconds).                                                                                                                  |
+
+## Example usage
+
+```yaml
+command: hover-text
+text: Sign Up
+description: link in the header
+action: click
+timeout: 10000 # 10 seconds
+```
+
+## Gotchas
+
+- If the text can't be located, it will internally call the [wait-for-text](/commands/wait-for-text) command and wait for the text to appear. The wait `timeout` is 5 seconds by default, and the command fails if the text is not found.
+- 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 can't be identified using other selectors.
+- Supported actions allow flexibility in how the text is interacted with during the test.

package/docs/v7/commands/if.mdx

@@ -0,0 +1,53 @@
+---
+title: "if"
+sidebarTitle: "if"
+description: "Conditionally execute commands based on a specified condition."
+icon: "split"
+mode: "wide"
+---
+
+## 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. It is an **optional command**. |
+
+## Example usage
+
+```yaml
+- prompt: click on sign up, if cookie banner appears close it
+  commands:
+    - 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.
+
+## Gotchas
+
+- The else block is optional, if the `condition` fails and there is no `else` block, the execution will continue from the next available command.
+- If the `condition` is invalid or can't be evaluated, the command will fail.
+- Ensure all commands in the `then` and `else` blocks are valid and properly formatted.
+
+---
+
+The `if` command is useful for creating conditional logic in your tests, allowing for more dynamic and flexible workflows.

package/docs/v7/commands/match-image.mdx

@@ -0,0 +1,67 @@
+---
+title: "match-image"
+sidebarTitle: "match-image"
+description: "Locate an image on the screen and perform an action."
+icon: "images"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/match-image-replay.mdx";
+import Example from "/snippets/tests/match-image-yaml.mdx";
+
+<Replay />
+<Example />
+
+## 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 (For example, 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 path to the image that needs to be matched. The path needs to be relative to the current test file                                                                                                                        |
+| `action` | `string`  | The action to take when the image is found. Available actions are: `click`, `right-click`, `double-click`, `hover`. Also supports `drag-start` and `drag-end` for [dragging images](/commands/hover-image#drag-functionality) |
+| `invert` | `boolean` | (Optional) If set to `true`, the command will pass when the specified image is NOT detected. Default is `false`.                                                                                                              |
+
+## Example usage
+
+```yaml
+command: match-image
+path: screenshots/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/` directory.
+
+## 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
+
+- The screenshot image should be of the actual size of the image that's being match against.
+- If the image match is below ~80% similarity, the program tries to match will different scales, its recommended to have an actual size image.
+- 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/`) for dynamic resolution.
+- The `path`needs to be relative to the current test file's directory. For example, if the test file is at `testdriver/onboarding/login.yaml` and the image is present at the conventional `testdriver/screenshots/nepal-flag.png` it should be referrenced as
+
+```yaml highlight={2}
+command: match-image
+path: ../screenshots/nepal-flag.png
+action: click
+```
+
+## Notes
+
+- The `match-image` command is ideal for interacting with visual elements that can't 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/v7/commands/press-keys.mdx

@@ -0,0 +1,87 @@
+---
+title: "press-keys"
+sidebarTitle: "press-keys"
+description: "Simulate typing a keyboard combination."
+icon: "keyboard"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/press-keys-replay.mdx";
+import Example from "/snippets/tests/press-keys-yaml.mdx";
+
+<Replay />
+<Example />
+
+## 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`   | YAML sequence of strings | A list of keys to press together. |
+
+---
+
+The keys supported are the standard [Windows keys](https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.keys?view=windowsdesktop-9.0). Supported values:
+
+<Tabs>
+  <Tab title="Modifiers">
+    - `ctrl`, `shift`, `alt`, `command`, `option`, `win` - Left/right variants:
+    `ctrlleft`, `ctrlright`, `shiftleft`, `shiftright`, `altleft`, `altright`,
+    `optionleft`, `optionright`, `winleft`, `winright`
+  </Tab>
+  <Tab title="Printable">
+    - All ASCII printable characters: letters `a`–`z`, digits `0`–`9`, common
+    punctuation, and `space`.
+  </Tab>
+  <Tab title="Function keys">- `f1`–`f24`</Tab>
+  <Tab title="Navigation">
+    - `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`,
+    `pgup`, `pgdn`
+  </Tab>
+  <Tab title="Editing">
+    - `backspace`, `delete`, `del`, `insert`, `enter`, `return`, `tab`,
+    `escape`, `esc`
+  </Tab>
+  <Tab title="Locks & Print">
+    - `capslock`, `numlock`, `scrolllock`, `printscreen`, `prntscrn`, `prtsc`,
+    `prtscr`, `print`
+  </Tab>
+  <Tab title="Numpad">
+    - `num0`–`num9`, `add`, `subtract`, `multiply`, `divide`, `decimal`,
+    `separator`
+  </Tab>
+  <Tab title="Media & Browser">
+    - `playpause`, `stop`, `nexttrack`, `prevtrack`, `volumedown`, `volumeup`,
+    `volumemute` - `browserback`, `browserforward`, `browserrefresh`,
+    `browsersearch`, `browserstop`, `browserfavorites`, `browserhome` -
+    `launchapp1`, `launchapp2`, `launchmail`, `launchmediaselect`
+  </Tab>
+  <Tab title="IME / International">
+    - `hangul`, `hanguel`, `hanja`, `junja`, `kana`, `kanji`, `modechange`,
+    `nonconvert`, `convert`, `final`, `yen`
+  </Tab>
+  <Tab title="Other">- `help`, `select`, `sleep`, `space`</Tab>
+</Tabs>
+
+---
+
+## Example usage
+
+```yaml
+command: press-keys
+keys:
+  - ctrl
+  - space
+```
+
+## Protips
+
+- Use this command to trigger system-wide or application-specific shortcuts, such as the Start menu or the browser elements.
+- 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.

package/docs/v7/commands/remember.mdx

@@ -0,0 +1,49 @@
+---
+title: "remember"
+sidebarTitle: "remember"
+description: "Save a variable to use later."
+icon: "brain"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/remember-replay.mdx";
+import Example from "/snippets/tests/remember-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `remember` command is used to save a variable for later use. This is useful for storing values that you want to reference in subsequent commands or steps, **especially for things that are dynamic or change frequently from run to run**.
+
+## Arguments
+
+|   Argument    |   Type   | Description                                               |
+| :-----------: | :------: | :-------------------------------------------------------- |
+|   `output`    | `string` | The variable name you will use to recall the value later. |
+| `description` | `string` | A prompt describing the value you want to store.          |
+
+---
+
+## Example usage
+
+```yaml
+- command: remember
+  description: The date value shown to the right of 'Order Date'
+  output: my_variable
+```
+
+## Protips
+
+- Use the output later with this syntax `${OUTPUT.my_variable}`.
+- The `remember` command does not persist variables across different test runs. If you need to store values for later use in different test runs, consider using external storage solutions or environment variables.
+- For now, the `remember` command only supports string values. If you need to store complex data types, you may use `remember` multiple times for the values. This may change in a later version.
+
+## Gotchas
+
+- Ensure the variable name is unique to avoid overwriting existing variables.
+- The variable name is case-sensitive, so `my_variable` and `My_Variable` would be treated as different variables.
+
+## Notes
+
+- The `remember` command is ideal for storing values that are generated during the test run, such as timestamps, IDs, the text value of a link you might click later, or any other dynamic data.

package/docs/v7/commands/run.mdx

@@ -0,0 +1,44 @@
+---
+title: "run"
+sidebarTitle: "run"
+description: "Embed and execute another file within the current script."
+icon: "play"
+mode: "wide"
+---
+
+## Description
+
+The `run` command is used to embed and execute another file within the current script. This is **useful for reusing common sequences of commands or modularizing your scripts** for better organization and maintainability.
+
+## Arguments
+
+| Argument | Type     | Description                                                                                   |
+| -------- | -------- | :-------------------------------------------------------------------------------------------- |
+| `file`   | `string` | The path to the file to embed and run. Should be relative to the root of your git repository. |
+
+## Example usage
+
+```yaml
+command: run
+file: relative/path/to/another-script.yaml
+```
+
+## Protips
+
+- Use the `run` command to centralize reusable logic, such as login flows or setup steps, into separate files.
+- Ensure the file path is relative to the current test file's directory. For example, if the test file is at `testdriver/homepage/chat-functionalities.yaml` and say the login snippet is present at the conventional `testdriver/snippets/login.yaml` it should be referrenced as :
+
+```yaml highlight={2}
+command: run
+file: ../snippets/login.yaml
+```
+
+## Gotchas
+
+- If the specified file doesn't exist or contains errors, the command will fail.
+- Ensure the embedded file is compatible with the current script's context, such as variable dependencies or session requirements.
+
+## Notes
+
+- The `run` command is ideal for creating modular and maintainable test scripts by reusing common workflows.
+- This command supports nesting, allowing you to call scripts that themselves use the `run` command.

package/docs/v7/commands/scroll-until-image.mdx

@@ -0,0 +1,66 @@
+---
+title: "scroll-until-image"
+sidebarTitle: "scroll-until-image"
+description: "Scroll the screen until an image matching the description is found."
+icon: "film-simple"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/scroll-until-image-replay.mdx";
+import Example from "/snippets/tests/scroll-until-image-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `scroll-until-image` command is used to scroll the screen in a specified direction until an image matching the given description is found. This is useful for navigating to visual elements that aren't initially visible on the screen.
+
+## Arguments
+
+|   Argument    |   Type    | Description                                                                                                             |
+| :-----------: | :-------: | :---------------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`  | A description of the image and what it represents.                                                                      |
+|  `direction`  | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
+|  `distance`   | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
+|   `method`    | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
+|    `path`     | `string`  | (Optional) The relative path to the image file that needs to be matched on the screen.                                  |
+|   `invert`    | `boolean` | (Optional) If set to `true`, the command will scroll until the specified image is NOT detected. Default is `false`.     |
+
+<Note>
+  Use either the `description` or `path` argument to match an image on the
+  screen. If you are using `path` argument, make sure to upload an accurate
+  representation of the actual image and reference it relative to the current
+  test path.
+</Note>
+
+## Example usage
+
+```yaml
+command: scroll-until-image
+description: Submit at the bottom of the form
+direction: down
+```
+
+Or, you can use the `path` argument to match an image on the screen (similar to [`match-image`](./match-image)):
+
+```yaml testdriver/scroll-until-image.yaml
+command: scroll-until-image
+path: screenshots/button.png
+direction: down
+```
+
+## Protips
+
+- Use clear and concise descriptions for the image to improve detection accuracy.
+- Adjust the `distance` value to control how far the command scrolls before giving up.
+- Combine this command with other commands like `hover-image` or `match-image` to interact with the located image.
+
+## Gotchas
+
+- If the image can't be located within the specified `distance`, the command will fail.
+- Ensure the description accurately represents the image to avoid detection issues.
+
+---
+
+The `scroll-until-image` command is ideal for navigating to visual elements that are off-screen and can't be located using text-based commands.

package/docs/v7/commands/scroll-until-text.mdx

@@ -0,0 +1,60 @@
+---
+title: "scroll-until-text"
+sidebarTitle: "scroll-until-text"
+description: "Scroll the screen until the specified text is found."
+icon: "scroll"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/scroll-until-text-replay.mdx";
+import Example from "/snippets/tests/scroll-until-text-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `scroll-until-text` command is used to scroll the screen in a specified direction until the specified text is found. This is useful for navigating to elements that aren't initially visible on the screen.
+
+## Arguments
+
+|  Argument   |   Type    | Description                                                                                                             |
+| :---------: | :-------: | :---------------------------------------------------------------------------------------------------------------------- |
+|   `text`    | `string`  | The text to find on the screen. Longer and unique are better. Note this is **case sensitive**                           |
+| `direction` | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
+|  `method`   | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
+| `distance`  | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
+|  `invert`   | `boolean` | (Optional) If set to `true`, the command will scroll until the specified text is NOT detected. Default is `false`.      |
+
+<Note>
+If the method is `keyboard` it just searches for the string by doing `ctrl + f`. 
+This is helpful if there is a single string match that you want to operate with.
+
+If you are using `mouse` method, the command will manually scroll the page (based on the `distance`) until the text is found.
+
+</Note>
+
+## Example usage
+
+```yaml
+command: scroll-until-text
+text: Sign Up
+direction: down
+distance: 1000
+```
+
+## Protips
+
+- Use unique and specific text to improve detection accuracy.
+- Adjust the `distance` value to control how far the command scrolls before giving up.
+- If you don't specify a `distance`, the command will scroll 300 pixels at a time, giving up after 5 attempts.
+
+## Gotchas
+
+- If the text can't be located within the specified `distance`, the command will fail.
+- Ensure the text is visible and matches exactly, as variations in font size, style, or screen resolution may affect detection accuracy.
+- Note that `text` is case-sensitive, so **Sign Up** and **sign up** would be treated as different strings.
+
+---
+
+The `scroll-until-text` command is ideal for navigating to elements that are off-screen and can't be located using other commands.

package/docs/v7/commands/scroll.mdx

@@ -0,0 +1,69 @@
+---
+title: "scroll"
+sidebarTitle: "scroll"
+description: "Scroll the screen in a specified direction using the mouse wheel."
+icon: "computer-mouse"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/scroll-replay.mdx";
+import Example from "/snippets/tests/scroll-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `scroll` command is used to scroll the screen in a specified direction using the mouse wheel. This is useful for navigating through content that extends beyond the visible area.
+
+## Arguments
+
+|  Argument   |   Type   | Description                                                                           |
+| :---------: | :------: | :------------------------------------------------------------------------------------ |
+| `direction` | `string` | The direction to scroll. Available directions are: `up`, `down`, `left`, `right`.     |
+|  `method`   | `string` | The method to scroll. Available methods are: `mouse`, `keyboard`. Defaults to `mouse` |
+|  `amount`   | `number` | (Optional) Pixels to scroll. If not specified, a default amount of 300 is used.       |
+
+<Warning>
+  The `amount` should only be used when the `method` is mouse. If the `method`
+  is keyboard, it is redundant as the action performed is pressing the `pageup`
+  or `pagedown` keys.
+</Warning>
+
+## Example usage
+
+```yaml
+- command: scroll
+  direction: down
+  method: mouse
+  amount: 100
+```
+
+## Protips
+
+- Be sure to focus the application and frame you are trying to scroll before using the command.
+- Use precise `amount` values to control the scrolling distance for better accuracy in your tests.
+- Combine the `scroll` command with other commands like `hover-text` or `match-image` to interact with elements that are initially off-screen.
+- If you wish to scroll dynamically till a specific text or image appears, use [scroll-until-text](/commands/scroll-until-text) or [scroll-until-image](/commands/scroll-until-image) commands.
+- The most reliable way to scroll to the top or bottom of the page is to use the `home` and `end` keys:
+
+  ```yaml
+  # Scroll to the top of the page
+  - command: press-keys
+    keys:
+      - home
+  # Scroll to the bottom of the page
+  - command: press-keys
+    keys:
+      - end
+  ```
+
+## Gotchas
+
+- Scrolling too far may cause elements to move out of view. Adjust the `amount` value as needed.
+- Ensure the application or browser window is in focus when using this command to avoid unexpected behavior.
+
+## Notes
+
+- The `scroll` command is ideal for navigating through long pages or lists during automated tests.
+- This command supports both vertical and horizontal scrolling for flexible navigation.

package/docs/v7/commands/type.mdx

@@ -0,0 +1,45 @@
+---
+title: "type"
+sidebarTitle: "type"
+description: "Simulate typing a string using keyboard emulation."
+icon: "typewriter"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/type-replay.mdx";
+import Example from "/snippets/tests/type-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `type` command is used to simulate typing a string using keyboard emulation. This is useful for entering text into input fields or performing text-based interactions.
+
+## Arguments
+
+| Argument |   Type   | Description              |
+| :------: | :------: | :----------------------- |
+|  `text`  | `string` | The text string to type. |
+
+## Example usage
+
+```yaml
+command: type
+text: Hello World
+```
+
+## Protips
+
+- Use this command to input text into fields, such as search bars or forms.
+- Ensure the target application or input field is in focus before using the `type` command to avoid unexpected behavior.
+- It can also be used to insert values from variables, refer our [variable's guide](/guide/variables) for more information.
+
+## Gotchas
+
+- If the input field isn't active or in focus, the text may not be typed correctly.
+- Special characters in the `text` string may require additional handling depending on the application.
+
+---
+
+The `type` command is ideal for automating text input in tests.