testdriverai 6.2.2 → 7.1.0

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.

package/docs/v7/commands/wait-for-image.mdx

@@ -0,0 +1,54 @@
+---
+title: "wait-for-image"
+sidebarTitle: "wait-for-image"
+description: "Wait until an image matching the description is detected on the screen."
+icon: "clock-three-thirty"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/wait-for-image-replay.mdx";
+import Example from "/snippets/tests/wait-for-image-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `wait-for-image` command waits until the specified image is detected on the screen. This is useful for ensuring that visual elements are present before proceeding with the next steps in a test.
+
+## Arguments
+
+|   Argument    |   Type    | Description                                                                                                       |
+| :-----------: | :-------: | :---------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`  | A description of the image.                                                                                       |
+|   `timeout`   | `number`  | (Optional) The duration in milliseconds to wait for the image to appear. Default is `10000` (10 seconds).         |
+|   `invert`    | `boolean` | (Optional) If set to `true`, the command will wait until the specified image is NOT detected. Default is `false`. |
+
+## Example usage
+
+```yaml
+command: wait-for-image
+description: trash icon
+timeout: 5000
+```
+
+## Protips
+
+- Use clear and concise descriptions for the image to improve detection accuracy.
+- Adjust the `timeout` value based on the expected load time of the image to avoid unnecessary delays.
+
+<Tip>
+  If you are unable to land on an accurate description or experiencing flaky
+  results, try to upload the image to [chatgpt](https://chatgpt.com) and ask it
+  to describe the image and use the generated `description` to get better
+  accuracy and determinism.
+</Tip>
+
+## Gotchas
+
+- If the image doesn't appear within the specified `timeout`, the command will fail.
+- Ensure the description accurately represents the image to avoid detection issues.
+
+---
+
+The `wait-for-image` command is ideal for synchronizing tests with visual elements that may take time to load.

package/docs/v7/commands/wait-for-text.mdx

@@ -0,0 +1,48 @@
+---
+title: "wait-for-text"
+sidebarTitle: "wait-for-text"
+description: "Wait until the specified text is detected on the screen."
+icon: "clock-nine"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/wait-for-text-replay.mdx";
+import Example from "/snippets/tests/wait-for-text-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `wait-for-text` command waits until the specified text is detected on the screen. This is useful for ensuring that textual elements are present before proceeding with the next steps in a test.
+
+## Arguments
+
+| Argument  |   Type    | Description                                                                                                      |
+| :-------: | :-------: | :--------------------------------------------------------------------------------------------------------------- |
+|  `text`   | `string`  | The text to find on the screen.                                                                                  |
+| `timeout` | `number`  | (Optional) The duration in milliseconds to wait for the text to appear. Default is `5000` (5 seconds).           |
+| `method`  |  `enum`   | (Optional) The matching algorithm to use. Possible values are `ai` and `turbo`. Default is `turbo`               |
+| `invert`  | `boolean` | (Optional) If set to `true`, the command will wait until the specified text is NOT detected. Default is `false`. |
+
+## Example usage
+
+```yaml
+command: wait-for-text
+text: Copyright 2024
+timeout: 5000
+```
+
+## Protips
+
+- Use unique and specific text to improve detection accuracy.
+- Adjust the `timeout` value based on the expected load time of the text to avoid unnecessary delays.
+
+## Gotchas
+
+- If the text doesn't appear within the specified `timeout`, the command will fail.
+- Ensure the text matches exactly, as variations in font size, style, or screen resolution may affect detection accuracy.
+
+---
+
+The `wait-for-text` command is ideal for synchronizing tests with textual elements that may take time to load.

package/docs/v7/commands/wait.mdx

@@ -0,0 +1,45 @@
+---
+title: "wait"
+sidebarTitle: "wait"
+description: "Pause the execution of the script for a specified duration."
+icon: "clock"
+"mode": "wide"
+---
+
+import Replay from "/snippets/tests/wait-replay.mdx";
+import Example from "/snippets/tests/wait-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `wait` command pauses the execution of the script for a specified number of milliseconds before continuing. This is useful for adding delays between commands or waiting for certain conditions to stabilize.
+
+## Arguments
+
+| Argument  | Type     | Description                           |
+| --------- | -------- | ------------------------------------- |
+| `timeout` | `number` | The duration in milliseconds to wait. |
+
+## Example usage
+
+```yaml
+command: wait
+timeout: 5000
+```
+
+## Protips
+
+- Use the `wait` command to handle timing issues, such as waiting for animations to complete or elements to load.
+- Avoid using excessively long timeouts to keep tests efficient.
+
+## Gotchas
+
+- Overusing the `wait` command can slow down test execution. Use it only when necessary.
+- Ensure the timeout value is appropriate for the scenario to avoid unnecessary delays.
+
+## Notes
+
+- The `wait` command is ideal for introducing controlled pauses in your test scripts.
+- Whenever you are waiting for something to load, use the [wait-for-text](/commands/wait-for-text) or [wait-for-image](/commands/wait-for-image) commands instead to make the test more efficient.