testdriverai 5.3.12 → 5.3.14

package/agent.js

@@ -28,7 +28,6 @@ const path = require("path");
 const chalk = require("chalk");
 const yaml = require("js-yaml");
 const sanitizeFilename = require("sanitize-filename");
-const macScreenPerms = require("mac-screen-capture-permissions");
 
 // local modules
 const { server } = require("./lib/ipc.js");
@@ -123,7 +122,7 @@ let getArgs = () => {
   // turn args[file] into local path
   if (args[file]) {
     args[file] = path.join(workingDir, args[file]);
-    if (!args[file].endsWith(".yaml")) {
+    if (!args[file].endsWith(".yaml") && !args[file].endsWith(".yml")) {
       args[file] += ".yaml";
     }
   }
@@ -378,7 +377,7 @@ const runCommand = async (command, depth, shouldSave) => {
     }
 
     if (response && typeof response === "string") {
-      return await actOnMarkdown(response, depth, true, false);
+      return await actOnMarkdown(response, depth, false, false, false);
     }
   } catch (error) {
     return await haveAIResolveError(
@@ -403,6 +402,7 @@ const executeCommands = async (
 ) => {
   if (commands?.length) {
     for (const command of commands) {
+
       if (pushToHistory) {
         executionHistory[executionHistory.length - 1]?.commands.push(command);
       }
@@ -738,7 +738,7 @@ const actOnMarkdown = async (
   depth,
   pushToHistory = false,
   dry = false,
-  shouldSave,
+  shouldSave = false,
 ) => {
   logger.debug("%j", {
     message: "actOnMarkdown called",
@@ -771,18 +771,24 @@ const ensureMacScreenPerms = async () => {
   // if os is mac, check for screen capture permissions
   if (
     !config.TD_VM &&
-    process.platform === "darwin" &&
-    !macScreenPerms.hasScreenCapturePermission()
+    process.platform === "darwin"
   ) {
-    logger.info(chalk.red("Screen capture permissions not enabled."));
-    logger.info(
-      "You must enable screen capture permissions for the application calling `testdriverai`.",
-    );
-    logger.info(
-      "Read More: https://docs.testdriver.ai/faq/screen-recording-permissions-mac-only",
-    );
-    analytics.track("noMacPermissions");
-    return exit();
+
+    const macScreenPerms = require("mac-screen-capture-permissions");
+    if (!macScreenPerms.hasScreenCapturePermission()) {
+
+      logger.info(chalk.red("Screen capture permissions not enabled."));
+      logger.info(
+        "You must enable screen capture permissions for the application calling `testdriverai`.",
+      );
+      logger.info(
+        "Read More: https://docs.testdriver.ai/faq/screen-recording-permissions-mac-only",
+      );
+      analytics.track("noMacPermissions");
+      return exit();
+      
+    }
+    
   }
 };
 
@@ -1039,9 +1045,6 @@ let save = async ({ filepath = thisFile, silent = false } = {}) => {
 ${regression}
 \`\`\``);
 
-    // logger.info(csv.join('\n'))
-
-    const fileName = filepath.split("/").pop();
     if (!silent) {
       logger.info(chalk.dim(`saved as ${filepath}`));
     }

package/docs/30x30.mdx

@@ -75,7 +75,7 @@ For more details, see the [Contract Details](#contract-details).
 - **Payment**: A payment method is required to begin the trial.
 - **Renewal**: The contract renews monthly.
 - **Cancellation**: Cancel anytime, for any reason.
-- **Credits**: Unused credits do not roll over and expire at the end of each month.
+- **Credits**: Unused credits don't roll over and expire at the end of each month.
 - **Additional Usage**: Additional usage is billed at standard rates.
 
 ---

package/docs/action/secrets.mdx

@@ -6,7 +6,7 @@ icon: "mask"
 ---
 
 ## Overview
-When using TestDriver to test your application, you may need to securely store and use sensitive information such as usernames, passwords, API keys, or other secrets. GitHub Actions provides a secure way to manage these secrets, ensuring they are not exposed in your test files or logs.
+When using TestDriver to test your application, you may need to securely store and use sensitive information such as usernames, passwords, API keys, or other secrets. GitHub Actions provides a secure way to manage these secrets, ensuring they aren't exposed in your test files or logs.
 
 ---
 

package/docs/commands/assert.mdx

@@ -4,7 +4,7 @@ icon: "check"
 ---
 
 ## 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.
+The `assert` command validates that a specific condition is true. It ensures that a task completed successfully by checking the screen for the expected outcome. If the condition isn't met, the test will fail.
 
 ## Arguments
 | Argument   | Type      | Description                                                                 |
@@ -12,7 +12,8 @@ The `assert` command is used to validate that a specific condition is true. It e
 | `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
+## Example usage
+
 ```yaml
 command: assert
 expect: the video is playing
@@ -27,6 +28,5 @@ 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.
+- Use `async: true` to speed up tests by allowing non-blocking assertions. However, the test will still fail if the condition isn't met.
 - Ensure the `expect` string clearly describes the condition to avoid ambiguity.

package/docs/commands/exec.mdx

@@ -9,35 +9,45 @@ The `exec` command allows you to execute custom NodeJS scripts within your TestD
 ## Arguments
 | Argument   | Type      | Description                                                                 |
 |------------|-----------|-----------------------------------------------------------------------------|
-| `js`       | `string`  | The NodeJS script to execute. The script must define the output as `result`. |
+| `lang`     | `string`  | The language of the script to execute. Supported values are `shell` and `js`. |
 | `output`   | `string`  | The variable name to store the result of the script. This variable can be accessed as `${OUTPUT.<var>}` in future steps. |
+| `linux`    | `string`  | The script to execute on Linux systems. For `js`, the script must define the output as `result`. |
+| `windows`  | `string`  | The script to execute on Windows systems. For `js`, the script must define the output as `result`. |
+| `mac`      | `string`  | The script to execute on macOS systems. For `js`, the script must define the output as `result`. |
 
 ## Example Usage
+
+This example demonstrates how to use the `exec` command to generate a TOTP (Time-based One-Time Password) using the `totp-generator` library.
+
 ```yaml
-version: 5.1.0
-session: 67e57d614dc25283aa0872a9
+version: 5.3.8
 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}
+  - commands:
+    - command: exec
+      lang: shell
+      linux: |
+        npm install totp-generator
+    - command: exec
+      lang: js
+      output: totp
+      linux: |
+        const { TOTP } = require("totp-generator");
+        let otp = TOTP.generate("JBSWY3DPEB3W64TMMQQQ").otp;
+        console.log(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.
+## Additional Details
 
-## 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.
+- The `exec` command now takes a `lang` argument and supports different operating systems (`linux`, `mac`, and `windows`).
+- Supported `lang` values are `js` or `shell`:
+  - `js` code is executed in a NodeJS VM on the host machine (your computer).
+  - `shell` code is executed in the shell on the runner.
+- Code specified in `linux`, `mac`, and `windows` is executed based on the platform of the runner machine.
 
-## 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.
+## Protips
+
+- Overwrite the `result` variable in your script, as it is used to store the output.
+- 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.

package/docs/commands/focus-application.mdx

@@ -4,7 +4,7 @@ icon: "window-restore"
 ---
 
 ## 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.
+The `focus-application` command brings a specific application window to the foreground. This ensures that subsequent commands interact with the correct application during a test.
 
 ## Arguments
 | Argument   | Type      | Description                                                                 |
@@ -22,9 +22,9 @@ name: Google Chrome
 - 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.
+- If the specified application isn't 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.
+- Supported on both Windows and macOS environments.

package/docs/commands/hover-image.mdx

@@ -4,14 +4,17 @@ icon: "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. |
+| `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`. |
 
+The `hover-image` command is useful for interacting with visual elements that can't be identified using text-based selectors.
+
 ## Example Usage
 ```yaml
 command: hover-image
@@ -22,12 +25,9 @@ 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.
+- 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 cannot be located based on the description, the command will fail.
+- 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.
 
-## 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

@@ -10,7 +10,7 @@ The `hover-text` command is used to locate text on the screen based on a descrip
 | 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. |
+| `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`. |
 | `method`      | `enum`   | The matching algorithm to use. Possible values are `turbo` (default) and `ai`. |
 
@@ -30,9 +30,9 @@ action: click
 - 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.
+- If the text can't 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.
+- 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/commands/if.mdx

@@ -35,7 +35,7 @@ else:
 - 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.
+- 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.
 
 ## Notes

package/docs/commands/match-image.mdx

@@ -4,12 +4,12 @@ icon: "images"
 ---
 
 ## 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.
+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 relative path to the image file that needs to be matched on the screen. Do not include `testdriver/screenshots/*/` in the path. |
+| `path`         | `string` | The relative path to the image file that needs to be matched on the screen. don't 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
@@ -27,7 +27,7 @@ action: click
 ## 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.
+  - 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.
 
@@ -37,6 +37,6 @@ action: click
 - 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`.
+- 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/commands/run.mdx

@@ -22,7 +22,7 @@ file: path/to/another-script.yaml
 - Ensure the file path is correct and relative to the root of your git repository to avoid errors.
 
 ## Gotchas
-- If the specified file does not exist or contains errors, the command will fail.
+- 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

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

@@ -4,9 +4,11 @@ icon: "scroll"
 ---
 
 ## 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 are not initially visible on the screen.
+
+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.                         |
@@ -14,6 +16,7 @@ The `scroll-until-image` command is used to scroll the screen in a specified dir
 | `distance`    | `number` | (Optional) The maximum number of pixels to scroll before giving up. Default is `1200`. |
 
 ## Example Usage
+
 ```yaml
 command: scroll-until-image
 description: Submit at the bottom of the form
@@ -26,9 +29,9 @@ direction: down
 - Combine this command with other commands like `hover-image` or `match-image` to interact with the located image.
 
 ## Gotchas
-- If the image cannot be located within the specified `distance`, the command will fail.
+- 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.
 
 ## Notes
-- The `scroll-until-image` command is ideal for navigating to visual elements that are off-screen and cannot be located using text-based commands.
+- 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.
 - This command supports both vertical and horizontal scrolling for flexible navigation.

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

@@ -4,7 +4,7 @@ icon: "scroll"
 ---
 
 ## 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 are not initially visible on the screen.
+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                                                                 |
@@ -29,10 +29,10 @@ direction: down
 - Adjust the `distance` value to control how far the command scrolls before giving up.
 
 ## Gotchas
-- If the text cannot be located within the specified `distance`, the command will fail.
+- 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.
 
 ## Notes
-- The `scroll-until-text` command is ideal for navigating to elements that are off-screen and cannot be located using other commands.
+- The `scroll-until-text` command is ideal for navigating to elements that are off-screen and can't be located using other commands.
 - This command supports both vertical and horizontal scrolling for flexible navigation.
 

package/docs/commands/type.mdx

@@ -22,7 +22,7 @@ text: Hello World
 - Ensure the target application or input field is in focus before using the `type` command to avoid unexpected behavior.
 
 ## Gotchas
-- If the input field is not active or in focus, the text may not be typed correctly.
+- 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.
 
 ## Notes

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

@@ -24,7 +24,7 @@ timeout: 5000
 - Adjust the `timeout` value based on the expected load time of the image to avoid unnecessary delays.
 
 ## Gotchas
-- If the image does not appear within the specified `timeout`, the command will fail.
+- 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.
 
 ## Notes

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

@@ -28,7 +28,7 @@ timeout: 5000
 - Adjust the `timeout` value based on the expected load time of the text to avoid unnecessary delays.
 
 ## Gotchas
-- If the text does not appear within the specified `timeout`, the command will fail.
+- 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.
 
 ## Notes

package/docs/docs.json

@@ -43,7 +43,7 @@
               "/guide/assertions",
               "/guide/variables",
               "/guide/authentication",
-              "/guide/setup-teardown",
+              "/guide/lifecycle",
               "/guide/code"
             ]
           },

package/docs/features/auto-healing.mdx

@@ -7,7 +7,7 @@ icon: "bandage"
 
 Auto-healing is a powerful feature in TestDriver.ai that ensures your tests remain resilient even when the application under test changes. 
 
-When TestDriver steps fail, the AI will progressively fall back to attemp to complete the test.
+When TestDriver steps fail, the AI will progressively fall back to attempt to complete the test.
 
 If running on CI, TestDriver will open a pull request (PR) with the updated test, ensuring your test suite stays up-to-date with minimal manual intervention.
 

package/docs/features/cross-platform.mdx

@@ -80,7 +80,7 @@ TestDriver.ai uses **selectorless testing**, meaning tests are written in a gene
 ### Benefits of Selectorless Testing
 
 - **Reduced Maintenance**: No need to update selectors when UI changes.
-- **Cross-Platform Compatibility**: Tests are not tied to platform-specific configurations.
+- **Cross-Platform Compatibility**: Tests aren't tied to platform-specific configurations.
 - **Ease of Use**: Write high-level, natural language prompts, and let TestDriver handle the rest.
 
 ### Example Test