testdriverai 5.7.4 → 5.7.6

package/agent.js

@@ -225,6 +225,7 @@ const haveAIResolveError = async (
   undo = true,
   shouldSave,
 ) => {
+  
   if (error.fatal) {
     return await dieOnFatal(error);
   }
@@ -1152,7 +1153,7 @@ const iffy = async (condition, then, otherwise, depth) => {
 
   logger.info(generator.jsonToManual({ command: "if", condition }));
 
-  let response = await commands.assert(condition);
+  let response = await commands.assert(condition, false);
 
   depth = depth + 1;
 

package/docs/action/pre-post-scripts.mdx

@@ -5,6 +5,8 @@ description: "How to handle pre and post test tasks."
 icon: "hammer"
 ---
 
+import LifecycleWarning from '/snippets/lifecycle-warning.mdx'
+
 ## Overview
 Prerun scripts are commands executed on a TestDriver virtual machine (VM) before each test in a CI/CD pipeline. They are used to prepare the environment by provisioning the VM, installing dependencies, configuring settings, or building the application. This ensures a consistent and reproducible environment for every test execution.
 
@@ -22,6 +24,8 @@ Prerun scripts are ideal for:
 - Configuring the VM to match specific test requirements.
 - Preparing staging environments or accessing private resources.
 
+<LifecycleWarning/>
+
 ---
 
 ## Example: Installing Arc Browser

package/docs/apps/chrome-extensions.mdx

@@ -7,6 +7,16 @@ icon: "puzzle-piece"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+<iframe
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/UUSXqAnau0Q"
+  title="Testing Chrome Extensions with TestDriver"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
 # Testing Chrome extensions with TestDriver
 TestDriver can be used to test Chrome extensions. This guide provides an overview of how to set up and run tests for your Chrome extension using TestDriver.
 
@@ -26,16 +36,7 @@ You can test a preinstalled extension or test by installing an extension. If the
 6. Click the 'puzzle piece' icon to pin the extension to the toolbar.
 7. Click on the extension icon to open it.
 
-## TestDriver in action
-<iframe
-  width="560"
-  height="315"
-  src="https://www.youtube.com/embed/czfq4It6-pQ"
-  title="Testing Chrome Extensions with TestDriver"
-  frameborder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowfullscreen
-></iframe>
+---
 
 ## Now what?
 Once you have installed your extension, simply create a TestDriver test to test any functionality a user would use. 

package/docs/apps/desktop-apps.mdx

@@ -7,22 +7,28 @@ icon: "desktop"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
-TestDriver is designed to work with any desktop application, including Electron, Java, and .NET apps. This guide provides an overview of how to use TestDriver with desktop applications, including installation, configuration, and running tests.
-
-<TestPrereqs />
-
-## Sample test steps
-
-## TestDriver in action
 <iframe
-  width="560"
-  height="315"
-  src="https://www.youtube.com/embed/IwJwGxHH8cA"
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/DzgZf2b5XJs"
   title="Assert 2+2=4"
   frameborder="0"
   allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
   allowfullscreen
 ></iframe>
+---
+# Using TestDriver with Desktop Apps
+
+TestDriver is designed to work with any desktop application, including Electron, Java, and .NET apps. This guide provides an overview of how to use TestDriver with desktop applications, including installation, configuration, and running tests.
+
+<TestPrereqs />
+
+## Sample test steps
+1. **Launch the application**: Use the `exec` command to launch the application. You can specify the path to the executable file and any command-line arguments needed to start the application.
+2. **Wait for the application to load**: Use the `wait-for-text` command to wait for a specific text or element to appear in the application window. This ensures that the application is fully loaded before proceeding with the test.
+3. **Interact with the application**: Use the `focus-application` command to bring the application window to the foreground. Then, use the `hover-image` command to interact with specific elements in the application, such as buttons or text fields.
+4. **Perform actions**: Use the `hover-image` command to click on buttons or enter text in input fields. You can also use the `wait-for-text` command to verify that the expected output appears after performing an action.
+5. **Verify results**: Use the `assert` command to check if the expected result matches the actual output. This step is crucial for validating the functionality of the application.
 
 ## Supported desktop applications
 TestDriver supports a wide range of desktop applications, including:

package/docs/apps/mobile-apps.mdx

@@ -4,13 +4,12 @@ sidebarTitle: "Mobile Apps"
 description: "Test mobile apps with TestDriver"
 icon: "mobile"
 ---
+
 # Testing mobile apps with TestDriver
 
 ## How do I test mobile apps?
 TestDriver provides a powerful solution for testing mobile apps. With our platform, you can easily create and run tests to ensure your mobile app functions as expected across different devices and operating systems.
 
-
-
 <Tip>You will need to install a mobile emulator for your deployed tests or use a device farm to test your mobile app.</Tip>
 
 ## Gettins started

package/docs/apps/static-websites.mdx

@@ -4,19 +4,22 @@ sidebarTitle: "Static Websites"
 description: "Test static websites with TestDriver"
 icon: "browser"
 ---
-TestDriver provides a powerful solution for testing static websites. With our platform, you can easily create and run tests to ensure your static website functions as expected across different browsers and devices.
-
-## TestDriver in action
 <iframe
-  width="560"
-  height="315"
-  src="https://www.youtube.com/embed/CqdRN_5_3I0"
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/Jgj1sZRpDiU"
   title="Form Filling with TestDriver"
   frameborder="0"
   allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
   allowfullscreen
 ></iframe>
 
+---
+# Testing Static Websites with TestDriver
+
+TestDriver provides a powerful solution for testing static websites. With our platform, you can easily create and run tests to ensure your static website functions as expected across different browsers and devices.
+
+
 ## Getting started
 To get started with testing static websites using TestDriver, follow these steps:
 1. **Follow our [quick start guide](/getting-started/setup) to set up your TestDriver account.**

package/docs/commands/remember.mdx

@@ -0,0 +1,40 @@
+---
+title: "remember"
+sidebarTitle: "remember"
+description: "Save a variable to use later."
+icon: "brain"
+---
+
+## 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.
+
+**The `remember` command is only availble form `v5.7.0` and later.**
+
+## 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
+  output: my_variable
+  description: The date value shown to the right or 'Order Date'
+```
+## 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
+- The `remeember` command is only available from `v5.7.0` and later.
+- 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/docs.json

@@ -175,6 +175,7 @@
                             "/commands/if",
                             "/commands/match-image",
                             "/commands/press-keys",
+                            "/commands/remember",
                             "/commands/run",
                             "/commands/scroll",
                             "/commands/scroll-until-image",
@@ -256,7 +257,20 @@
             "youtube": "https://www.youtube.com/@testdriverai"
         }
     },
-    "redirects": [],
+    "redirects": [
+        {
+            "source": "/guides/github-actions",
+            "destination": "/action/setup"
+        },
+        {
+            "source": "/reference/test-steps",
+            "destination": "/features/selectorless"
+        },
+        {
+            "source": "/guides/debugging-test-runs",
+            "destination": "/getting-started/editing"
+        }
+    ],
     "integrations": {
         "segment": {
             "key": "oh4PK60u4Qvm2DKIjxfhxd0KCdRbQsQE"
@@ -265,4 +279,4 @@
             "apiKey": "phc_ovOQ2HFpqFwPVqaxE5plJmI9buPMsz024FB2iajItqn"
         }
     }
-}
+}

package/docs/getting-started/vscode.mdx

@@ -38,28 +38,6 @@ import YmlWarning from '/snippets/yml-warning.mdx'
 
       Finally, install the extension in VS Code. You can do this by dragging and dropping the downloaded `.vsix` file into the VS Code window.
 
-      </Tab>
-      <Tab title="Cursor">
-
-      First, install the following recommended extension:
-
-      - [VS Code YAML](vscode://redhat.vscode-yaml) (Optional, but recommended for YAML validation)
-
-      Then download the TestDriver extension:
-
-      <Card
-        title="Download the VS Code Extension"
-        icon="download"
-        href="https://github.com/testdriverai/vscode/releases/latest/download/testdriver.vsix"
-      >
-        Install the TestDriver extension from the VS Code Marketplace.
-      </Card>
-
-      Finally, install the extension in Cursor. For more information on installing extensions in Cursor, check out the [Cursor documentation](https://forum.cursor.com/t/how-to-install-vsix-format-extension/1667).
-
-      </Tab>
-      <Tab title="Everything Else">
-
     Use JetBrains IDEs, VIM, or other editors? No problem! You can use TestDriver with the CLI. This quickstart contains both GUI and terminal commands to help you get started.
     </Tab>
     </Tabs>

package/docs/guide/lifecycle-prerun.mdx

@@ -5,8 +5,12 @@ description: "Learn how to customize and set up your TestDriver environment to o
 icon: "terminal"
 ---
 
+import LifecycleWarning from '/snippets/lifecycle-warning.mdx'
+
 ## Prerun configuration
 
+<LifecycleWarning/>
+
 ## The default `prerun` script
 When setting up your TestDriver environment, a default prerun script is automatically generated when you run:
 ```bash
@@ -20,7 +24,7 @@ testdriver
 │   └── prerun.yaml
 ```
 
-This script includes essential commands to ensure your VM is ready for testing. You can customize this script to suit your specific needs, but it's important to understand that it serves as a baseline for your test environment. It looks like this:
+This script includes essential commands to ensure your **local agent or sandbox** VM is ready for testing. You can customize this script to suit your specific needs, but it's important to understand that it serves as a baseline for your test environment. It looks like this:
  
 
 ```yaml ./lifecycle/prerun.yaml
@@ -51,14 +55,18 @@ The `wait-For-text` command is crucial for ensuring that the browser is fully lo
 
 If a file is found at `./lifecycle/prerun.yaml`, it's executed _before_ the test begins. _This will happen even if you have a pre or post test script defined in your GitHub Actions workflow._ This file works like any other TestDriver file and is commonly used to perform tasks such as opening a browser, navigating to a specific page, or resetting the application state.
 
-### Prerun diagram
+Note that the `prerun` script is found in the GitHub Actions workflow file for deployed tests.
+
+### Prerun flow
 ```mermaid
 graph TD
-    A{Is prerun available at ./lifecycle/prerun.yaml and a testfile present in ./somedirectory?}
-    A -->|Yes| B[Run ./lifecycle/prerun.yaml]
-    B --> C[Run ./somedirectory/testfile.yaml]
-    A -->|No| D{Is ./somedirectory/testfile.yaml present?}
-    D -->|Yes| C
+    A{Is the test deployed to CI?}
+    A -->|Yes| B[Run .github/workflows/testdriver.yml]
+    B --> F
+    A -->|No| C{Is prerun available at ./lifecycle/prerun.yaml}
+    C -->|Yes| D[Run ./lifecycle/prerun.yaml]
+    C -->|No| F
+    D --> F[Run ./testdriver/testfile.yaml]
 ```
 ---
 

package/docs/scenarios/ai-chatbot.mdx

@@ -7,6 +7,7 @@ icon: "message-bot"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+# Testing AI Chatbots with TestDriver
 TestDriver can be used to test AI chatbots, or any two way assertions like: 
 - Approval workflows
 - Chatbots

package/docs/scenarios/cookie-banner.mdx

@@ -7,6 +7,18 @@ icon: "cookie"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+<iframe
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/VUmjDQ4rM9M"
+  title="Testing Cookie Banners with TestDriver"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+---
+# Testing Cookie Banners with TestDriver
 With TestDriver, you can automate the testing of cookie banners on your web application. This scenario demonstrates how to check if a cookie banner appears when a user visits the site and how to interact with it.
 
 <TestPrereqs />
@@ -15,16 +27,3 @@ With TestDriver, you can automate the testing of cookie banners on your web appl
 1. **Visit the Site**: The test will navigate to the target URL.
 2. **Check for Cookie Banner**: It will verify if the cookie banner is displayed.
 3. **Decline Cookies**: The test will simulate a user clicking the "Decline All" button on the cookie banner.
-
-
-
-## TestDriver in action
-<iframe
-  width="560"
-  height="315"
-  src="https://www.youtube.com/embed/mhTffX0SG94"
-  title="Testing Cookie Banners with TestDriver"
-  frameborder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowfullscreen
-></iframe>

package/docs/scenarios/file-upload.mdx

@@ -7,6 +7,18 @@ icon: "upload"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+<iframe
+  width="600"
+  height="400"  
+  src="https://www.youtube.com/embed/9fMAJ0AC6Qw"
+  title="File Upload Testing with TestDriver"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+---
+## Testing file upload functionality with TestDriver
 This scenario demonstrates how to automate testing the file upload functionality of a web application using TestDriver's capabilities. The test will check if the file upload process works correctly and if the uploaded file is processed as expected.
 
 <TestPrereqs />
@@ -16,15 +28,3 @@ This scenario demonstrates how to automate testing the file upload functionality
 2. Generate a file that will be used for the upload.
 3. Use TestDriver to perform the file upload process. 
 4. Check if the uploaded file is processed correctly by the application.
-
-
-## TestDriver in action
-<iframe
-  width="560"
-  height="315"
-  src="https://www.youtube.com/embed/50AN5hDnwAg"
-  title="File Upload Testing with TestDriver"
-  frameborder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowfullscreen
-></iframe>

package/docs/scenarios/form-filling.mdx

@@ -7,22 +7,23 @@ icon: "list"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
-<TestPrereqs />
-
-## Scenario overview
-1. Open a webpage containing a form (Log in, Registration, etc.).
-2. Use TestDriver to fill in the form fields with test data.
-3. Submit the form and verify the expected outcome (for example, successful login, registration confirmation, redirect etc.).
-
-
-
-## TestDriver in action
 <iframe
-  width="560"
-  height="315"
-  src="https://www.youtube.com/embed/CqdRN_5_3I0"
+  width="600"
+  height="400"
+  src="https://www.youtube.com/embed/R0xHyuaBy3A"
   title="Form Filling With TestDriver"
   frameborder="0"
   allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
   allowfullscreen
 ></iframe>
+
+---
+# Testing Form Filling with TestDriver
+TestDriver provides a powerful solution for testing form filling functionality on web applications. This scenario demonstrates how to automate the process of filling out forms, such as login or registration forms, using TestDriver's capabilities.
+
+<TestPrereqs />
+
+## Scenario overview
+1. Open a webpage containing a form (Log in, Registration, etc.).
+2. Use TestDriver to fill in the form fields with test data.
+3. Submit the form and verify the expected outcome (for example, successful login, registration confirmation, redirect etc.).

package/docs/scenarios/log-in.mdx

@@ -7,6 +7,7 @@ icon: "lock"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+# Testing Login Functionality with TestDriver
 Test login functionality with TestDriver. This scenario demonstrates how to automate testing the login process for a web application using TestDriver.
 
 <TestPrereqs />

package/docs/scenarios/pdf-generation.mdx

@@ -7,6 +7,7 @@ icon: "file-pdf"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+# Testing PDF Generation with TestDriver
 Test PDF generation functionality with TestDriver. This scenario demonstrates how to automate testing the PDF generation process for a web application using TestDriver's capabilities.
 
 <TestPrereqs />

package/docs/scenarios/spell-check.mdx

@@ -7,6 +7,7 @@ icon: "spell-check"
 
 import TestPrereqs from '/snippets/test-prereqs.mdx'
 
+# Testing Spell Check with TestDriver
 This scenario demonstrates how to automate testing the spell check functionality of a web application using TestDriver's capabilities. The test will check if the spell checker correctly identifies and suggests corrections for misspelled words in a text input field.
 
 <TestPrereqs />

package/docs/snippets/lifecycle-warning.mdx

@@ -0,0 +1 @@
+<Warning>Prerun scripts for deployed tests happen in your GitHub Actions workflow setup file as per below. Prerun scripts that are part of the test lifecycle are run during local and sandbox runners only. This is likely to change in a future version.</Warning>

package/docs/snippets/test-prereqs.mdx

@@ -1,15 +1,14 @@
 ## Prerequisites
 Before running the tests, ensure you have performed the following steps:
 
-1. Install the [VS Code extension](/getting-started/vscode) for TestDriver
-2. If you haven't already, signup for a Free Trial on the [TestDriver website](https://testdriver.ai/pricing)
-3. Install the [TestDriver CLI](/cli/overview) globally using npm or just follow the VS Code Extension Setup Walkthrough:
+1. If you haven't already, signup for a Free Trial on the [TestDriver website](https://testdriver.ai/pricing)
+2. Install the [TestDriver CLI](/cli/overview) globally using npm or just follow the VS Code Extension Setup Walkthrough:
 ```bash
 npm install -g @testdriverai@beta
 ```
-4. Run the `init` command to set up the TestDriver configuration using the API key you got when you signed up for the trial:
+3. Run the `init` command to set up the TestDriver configuration using the API key you got when you signed up for the trial:
 ```bash
 testdriverai init
 ```
 
-<Check>Now you are ready to run the tests!</Check>
+<Check>Now you are ready to run the tests!</Check>

package/lib/focus-application.js

@@ -38,6 +38,13 @@ end tell`;
 //     set value of attribute "AXMinimized" of every window of application process "${windowName}" to true
 // end tell`;
 
+// const appleScriptActivate = (windowName) => `
+// tell application "${windowName}"
+//   reopen
+//   activate
+// end tell
+// `;
+
 const appleScriptActivate = (windowName) => `
 tell application "${windowName}"
   reopen
@@ -94,7 +101,7 @@ async function showTerminal(appName) {
     try {
       if (platform() == "mac") {
         await execSync(`osascript -e '${appleScriptActivate(appName)}'`, { stdio: [] });
-        await execSync(`osascript -e '${appleScriptSetFrontmost(appName)}'`, { stdio: [] });
+        // await execSync(`osascript -e '${appleScriptSetFrontmost(appName)}'`, { stdio: [] });
 
       } else if (platform() == "windows") {
         return runPwsh(appName, "Restore");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "5.7.4",
+  "version": "5.7.6",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "index.js",
   "bin": {