testdriverai 7.1.4 → 7.2.2

package/docs/docs.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "theme": "willow",
+  "theme": "aspen",
   "name": "TestDriver",
   "colors": {
     "primary": "#b3d334",
@@ -12,12 +12,9 @@
   },
   "favicon": "/images/template/icon.png",
   "navigation": {
-    "tabs": [
-      {
-        "tab": "Computer-Use SDK",
         "versions": [
           {
-            "version": "v6 (YAML)",
+            "version": "v6",
             "groups": [
               {
                 "group": "Overview",
@@ -68,24 +65,24 @@
                     "group": "Apps",
                     "icon": "laptop",
                     "pages": [
-                      "apps/static-websites",
-                      "apps/desktop-apps",
-                      "apps/chrome-extensions",
-                      "apps/mobile-apps",
-                      "apps/tauri-apps"
+                      "/v6/apps/static-websites",
+                      "/v6/apps/desktop-apps",
+                      "/v6/apps/chrome-extensions",
+                      "/v6/apps/mobile-apps",
+                      "/v6/apps/tauri-apps"
                     ]
                   },
                   {
                     "group": "Scenarios",
                     "icon": "computer-mouse",
                     "pages": [
-                      "scenarios/ai-chatbot",
-                      "scenarios/cookie-banner",
-                      "scenarios/file-upload",
-                      "scenarios/form-filling",
-                      "scenarios/log-in",
-                      "scenarios/pdf-generation",
-                      "scenarios/spell-check"
+                      "/v6/scenarios/ai-chatbot",
+                      "/v6/scenarios/cookie-banner",
+                      "/v6/scenarios/file-upload",
+                      "/v6/scenarios/form-filling",
+                      "/v6/scenarios/log-in",
+                      "/v6/scenarios/pdf-generation",
+                      "/v6/scenarios/spell-check"
                     ]
                   },
                   {
@@ -156,7 +153,7 @@
                   {
                     "group": "Reporting",
                     "icon": "chart-simple",
-                    "pages": ["exporting/junit", "/v6/bugs/jira"]
+                    "pages": ["/v6/exporting/junit", "/v6/bugs/jira"]
                   }
                 ]
               },
@@ -190,87 +187,140 @@
               }
             ]
           },
-          {
-            "version": "v7 (JS Beta)",
-            "groups": [
-              {
-                "group": "Overview",
-                "icon": "circle-info",
-                "pages": [
-                  "/v7/overview/what-is-testdriver",
-                  {
-                    "group": "Features",
-                    "icon": "star",
-                    "pages": [
-                      "/v7/features/easy-to-write",
-                      "/v7/features/fast",
-                      "/v7/features/stable",
-                      "/v7/features/scalable",
-                      "/v7/features/ai-native",
-                      "/v7/features/powerful",
-                      "/v7/features/observable",
-                      "/v7/features/enterprise"
-                    ]
-                  }
-                ]
-              },
-              {
-                "group": "Getting Started",
-                "icon": "rocket",
-                "pages": [
-                  "/v7/getting-started/installation",
-                  "/v7/getting-started/writing-tests",
-                  "/v7/getting-started/generating-tests",
-                  "/v7/getting-started/running-and-debugging",
-                  "/v7/getting-started/setting-up-in-ci"
-                ]
-              },
-              {
-                "group": "Examples",
-                "icon": "code",
-                "pages": [
-                  "/v7/presets/chrome",
-                  "/v7/presets/chrome-extension",
-                  "/v7/presets/vscode",
-                  "/v7/presets/electron"
-                ]
-              },
-              {
-                "group": "Actions",
-                "icon": "bolt",
-                "pages": [
-                  "/v7/api/act",
-                  "/v7/api/assert",
-                  "/v7/api/assertions",
-                  "/v7/api/click",
-                  "/v7/api/doubleClick",
-                  "/v7/api/exec",
-                  "/v7/api/find",
-                  "/v7/api/focusApplication",
-                  "/v7/api/hover",
-                  "/v7/api/mouseDown",
-                  "/v7/api/mouseUp",
-                  "/v7/api/pressKeys",
-                  "/v7/api/rightClick",
-                  "/v7/api/type",
-                  "/v7/api/scroll"
-                ]
-              },
-              {
-                "group": "API Reference",
-                "icon": "book",
-                "pages": [
-                  "/v7/api/client",
-                  "/v7/api/elements",
-                  "/v7/api/sandbox",
-                  "/v7/api/dashcam"
-                ]
-              }
-            ]
-          }
+        {
+  "version": "v7",
+  "groups": [
+    {
+      "group": "Getting Started",
+      "icon": "rocket",
+      "pages": [
+        "/v7/getting-started/quickstart"
+      ]
+    },
+    {
+      "group": "Guides",
+      "icon": "book",
+      "pages": [
+        "/v7/getting-started/writing-tests",
+        "/v7/getting-started/running-tests",
+        "/v7/getting-started/debugging-tests",
+        "/v7/getting-started/setting-up-in-ci"
+      ]
+    },
+    {
+      "group": "Examples",
+      "icon": "code",
+      "pages": [
+        "/v7/presets/chrome",
+        "/v7/presets/chrome-extension",
+        "/v7/presets/vscode",
+        "/v7/presets/electron"
+      ]
+    },
+    {
+      "group": "Features",
+      "icon": "layer-group",
+      "pages": [
+        {
+          "group": "Selectorless Testing",
+          "icon": "sparkles",
+          "pages": [
+            "/v7/features/easy-to-write",
+            "/v7/features/coverage",
+            "/v7/features/powerful",
+            "/v7/features/ai-native"
+          ]
+        },
+        {
+          "group": "Sandbox Environments",
+          "icon": "cube",
+          "pages": [
+            "/v7/features/managed-sandboxes",
+            "/v7/features/sandbox-customization",
+            "/v7/features/enterprise"
+          ]
+        },
+        {
+          "group": "Test Observability",
+          "icon": "microscope",
+          "pages": [
+            "/v7/features/application-logs",
+            "/v7/features/browser-logs",
+            "/v7/features/network-monitoring",
+            "/v7/features/system-performance"
+          ]
+        },
+        {
+          "group": "Performance & Reliability",
+          "icon": "gauge-high",
+          "pages": [
+            "/v7/features/fast",
+            "/v7/features/stable",
+            "/v7/features/parallel-execution",
+            "/v7/features/cache-management"
+          ]
+        },
+        {
+          "group": "Testing at Scale",
+          "icon": "arrow-up-right-dots",
+          "pages": [
+            "/v7/features/data-driven-testing",
+            "/v7/features/continuous-testing"
+          ]
+        },
+        {
+          "group": "Reports & Analytics",
+          "icon": "chart-line",
+          "pages": [
+            "/v7/features/test-reports",
+            "/v7/features/test-analytics",
+            "/v7/features/test-cases",
+            "/v7/features/test-replays"
+          ]
+        }
+      ]
+    },
+    {
+      "group": "Reference",
+      "icon": "book",
+      "pages": [
+        {
+          "group": "Actions",
+          "icon": "bolt",
+          "pages": [
+            "/v7/api/act",
+            "/v7/api/assert",
+            "/v7/api/assertions",
+            "/v7/api/click",
+            "/v7/api/doubleClick",
+            "/v7/api/exec",
+            "/v7/api/find",
+            "/v7/api/focusApplication",
+            "/v7/api/hover",
+            "/v7/api/mouseDown",
+            "/v7/api/mouseUp",
+            "/v7/api/pressKeys",
+            "/v7/api/rightClick",
+            "/v7/api/type",
+            "/v7/api/scroll"
+          ]
+        },
+        {
+          "group": "Client SDK",
+          "icon": "code",
+          "pages": [
+            "/v7/api/client",
+            "/v7/api/elements",
+            "/v7/api/sandbox",
+            "/v7/api/dashcam"
+          ]
+        }
+      ]
+    }
+  ]
+}
+
         ]
-      }
-    ]
   },
   "logo": {
     "light": "/images/template/light.png",
@@ -307,15 +357,75 @@
   "redirects": [
     {
       "source": "/guides/github-actions",
-      "destination": "/action/setup"
+      "destination": "/v6/action/setup"
     },
     {
       "source": "/reference/test-steps",
-      "destination": "/features/selectorless"
+      "destination": "/v6/features/selectorless"
     },
     {
       "source": "/guides/debugging-test-runs",
-      "destination": "/getting-started/editing"
+      "destination": "/v6/getting-started/editing"
+    },
+    {
+      "source": "/overview/:slug*",
+      "destination": "/v6/overview/:slug*"
+    },
+    {
+      "source": "/features/:slug*",
+      "destination": "/v6/features/:slug*"
+    },
+    {
+      "source": "/getting-started/:slug*",
+      "destination": "/v6/getting-started/:slug*"
+    },
+    {
+      "source": "/cli/:slug*",
+      "destination": "/v6/cli/:slug*"
+    },
+    {
+      "source": "/interactive/:slug*",
+      "destination": "/v6/interactive/:slug*"
+    },
+    {
+      "source": "/guide/:slug*",
+      "destination": "/v6/guide/:slug*"
+    },
+    {
+      "source": "/action/:slug*",
+      "destination": "/v6/action/:slug*"
+    },
+    {
+      "source": "/account/:slug*",
+      "destination": "/v6/account/:slug*"
+    },
+    {
+      "source": "/apps/:slug*",
+      "destination": "/v6/apps/:slug*"
+    },
+    {
+      "source": "/scenarios/:slug*",
+      "destination": "/v6/scenarios/:slug*"
+    },
+    {
+      "source": "/integrations/:slug*",
+      "destination": "/v6/integrations/:slug*"
+    },
+    {
+      "source": "/importing/:slug*",
+      "destination": "/v6/importing/:slug*"
+    },
+    {
+      "source": "/exporting/:slug*",
+      "destination": "/v6/exporting/:slug*"
+    },
+    {
+      "source": "/bugs/:slug*",
+      "destination": "/v6/bugs/:slug*"
+    },
+    {
+      "source": "/commands/:slug*",
+      "destination": "/v6/commands/:slug*"
     }
   ],
   "integrations": {

package/docs/snippets/tests/type-repeated-replay.mdx

@@ -1,4 +1,4 @@
-<div className="replay-block">
+st<div className="replay-block">
   <iframe
     src="https://app.dashcam.io/replay/683f9c23dc453b7caa0e0d0c?share=gIH46G6NMy3tV8V0KssxA&embed=true&timestamp=90000&playbackRate=5"
     width="1000"

package/docs/v7/_drafts/caching-selectors.mdx

@@ -51,6 +51,30 @@ const button = await testdriver.find('submit button', {
 });
 ```
 
+**Use Case - Variables in Test Steps:**
+
+Custom cache keys are especially useful when you use variables in your test steps, ensuring consistent caching regardless of the variable values:
+
+```javascript
+// Without custom cache key - each variable value creates a new cache entry
+const userName = 'john.doe@example.com';
+await testdriver.find(`input field for ${userName}`); // Cache miss every time
+
+// With custom cache key - all values share the same cache
+const userName = 'john.doe@example.com';
+await testdriver.find(`input field for ${userName}`, {
+  cacheKey: 'email-input-field'  // Same cache key regardless of userName value
+});
+
+// Another example with dynamic data
+const productId = '12345';
+await testdriver.find(`product card for ${productId}`, {
+  cacheKey: 'product-card'  // Reuses cache for any productId
+});
+```
+
+This prevents cache pollution and improves cache hit rates when your prompts include dynamic values.
+
 ### Global Cache Key
 
 Enable caching for all finds in your test:

package/docs/v7/api/act.mdx

@@ -184,7 +184,7 @@ describe('E-commerce Flow with AI', () => {
     const cartIcon = await testdriver.find('shopping cart icon');
     await cartIcon.click();
     
-    const total = await testdriver.remember('the cart total amount');
+    const total = await testdriver.extract('the cart total amount');
     console.log('Cart total:', total);
     
     // Use AI for checkout flow

package/docs/v7/api/assert.mdx

@@ -98,7 +98,7 @@ await testdriver.assert('the modal dialog is open');
   expect(result).toBeTruthy();
   
   // Extract for detailed comparison
-  const message = await testdriver.remember('the success message text');
+  const message = await testdriver.extract('the success message text');
   expect(message).toContain('successfully');
   ```
 </Check>

package/docs/v7/api/assertions.mdx

@@ -264,9 +264,9 @@ describe('E2E Shopping Flow', () => {
     // Verify cart updated
     await testdriver.assert('cart badge shows 1 item');
     
-    // Remember product details
-    const productName = await testdriver.remember('the name of the product just added');
-    const price = await testdriver.remember('the price of the product');
+    // Extract product details
+    const productName = await testdriver.extract('the name of the product just added');
+    const price = await testdriver.extract('the price of the product');
     
     console.log(`Added ${productName} at ${price}`);
     
@@ -302,7 +302,7 @@ describe('E2E Shopping Flow', () => {
     await testdriver.assert('success message is shown');
     
     // Extract order number
-    const orderNumber = await testdriver.remember('the order number');
+    const orderNumber = await testdriver.extract('the order number');
     console.log('Order placed:', orderNumber);
     expect(orderNumber).toBeTruthy();
   });
@@ -377,10 +377,10 @@ describe('E2E Shopping Flow', () => {
   </Accordion>
   
   <Accordion title="Extract before comparing">
-    Use `remember()` to extract values for detailed comparisons:
+    Use `extract()` to extract values for detailed comparisons:
     
     ```javascript
-    const actualTotal = await testdriver.remember('the cart total');
+    const actualTotal = await testdriver.extract('the cart total');
     const expectedTotal = '$99.99';
     
     expect(actualTotal).toBe(expectedTotal);
@@ -395,7 +395,7 @@ describe('E2E Shopping Flow', () => {
     await testdriver.assert('success message is displayed');
     
     // Extract and use traditional assertion for exact values
-    const message = await testdriver.remember('the success message text');
+    const message = await testdriver.extract('the success message text');
     expect(message).toContain('successfully');
     expect(message).toMatch(/order #\d+/i);
     ```

package/docs/v7/api/elements.mdx

@@ -418,6 +418,84 @@ if (element.confidence !== null) {
   Properties marked with ⚠️ may be `null` depending on what the AI could detect from the screenshot.
 </Note>
 
+## JSON Serialization
+
+Element objects can be safely serialized using `JSON.stringify()` for logging, debugging, and data storage. Circular references are automatically removed:
+
+```javascript
+const element = await testdriver.find('login button');
+
+// Safe to stringify - no circular reference errors!
+console.log(JSON.stringify(element, null, 2));
+```
+
+**Serialized output includes:**
+
+```json
+{
+  "description": "login button",
+  "coordinates": { "x": 100, "y": 200, "centerX": 150, "centerY": 225 },
+  "found": true,
+  "threshold": 0.01,
+  "x": 100,
+  "y": 200,
+  "cache": {
+    "hit": true,
+    "strategy": "pixel-diff",
+    "createdAt": "2025-12-09T10:30:00.000Z",
+    "diffPercent": 0.0023,
+    "imageUrl": "https://cache.testdriver.ai/..."
+  },
+  "similarity": 0.98,
+  "confidence": 0.95,
+  "selector": "button#login",
+  "aiResponse": "Found the blue login button in the center of the form..."
+}
+```
+
+**Serialized properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | string | Element search description |
+| `coordinates` | object | Full coordinate object `{x, y, centerX, centerY}` |
+| `found` | boolean | Whether element was located |
+| `threshold` | number | Cache threshold used for this find |
+| `x`, `y` | number | Top-left coordinates |
+| `cache.hit` | boolean | Whether cache was used |
+| `cache.strategy` | string | Cache strategy (e.g., "pixel-diff") |
+| `cache.createdAt` | string | ISO timestamp when cache was created |
+| `cache.diffPercent` | number | Pixel difference from cached image |
+| `cache.imageUrl` | string | URL to cached screenshot |
+| `similarity` | number | Similarity score (0-1) |
+| `confidence` | number | AI confidence score (0-1) |
+| `selector` | string | CSS/XPath selector if available |
+| `aiResponse` | string | AI's explanation of what it found |
+
+**Use cases:**
+
+```javascript
+// Debugging element detection
+const element = await testdriver.find('submit button');
+if (!element.found()) {
+  console.error('Element not found:', JSON.stringify(element, null, 2));
+}
+
+// Logging cache performance
+const data = JSON.parse(JSON.stringify(element));
+if (data.cache.hit) {
+  console.log(`Cache hit! Diff: ${(data.cache.diffPercent * 100).toFixed(2)}%`);
+}
+
+// Sharing element data across processes
+const elementData = JSON.stringify(element);
+// Send to another process, log to file, etc.
+```
+
+<Tip>
+  Use JSON serialization when you need to log element data or when debugging why an element wasn't found. The serialized output excludes large binary data (screenshots) and circular references.
+</Tip>
+
 ## Polling for Elements
 
 Use polling to wait for elements that may not be immediately visible:

package/docs/v7/api/find.mdx

@@ -103,6 +103,44 @@ The returned `Element` object provides:
 
 See [Elements Reference](/v7/api/elements) for complete details.
 
+### JSON Serialization
+
+Elements can be safely serialized using `JSON.stringify()` for logging and debugging. Circular references are automatically removed:
+
+```javascript
+const element = await testdriver.find('login button');
+
+// Safe to stringify - no circular reference errors
+console.log(JSON.stringify(element, null, 2));
+
+// Output includes useful debugging info:
+// {
+//   "description": "login button",
+//   "coordinates": { "x": 100, "y": 200, "centerX": 150, "centerY": 225 },
+//   "found": true,
+//   "threshold": 0.01,
+//   "x": 100,
+//   "y": 200,
+//   "cache": {
+//     "hit": true,
+//     "strategy": "pixel-diff",
+//     "createdAt": "2025-12-09T10:30:00Z",
+//     "diffPercent": 0.0023,
+//     "imageUrl": "https://..."
+//   },
+//   "similarity": 0.98,
+//   "confidence": 0.95,
+//   "selector": "button#login",
+//   "aiResponse": "Found the blue login button..."
+// }
+```
+
+This is useful for:
+- Debugging element detection issues
+- Logging test execution details
+- Sharing element information across processes
+- Analyzing cache performance
+
 ## Best Practices
 
 <Check>

package/docs/v7/api/focusApplication.mdx

@@ -113,7 +113,7 @@ await testdriver.focusApplication('Google Chrome');
     ```javascript
     // Test workflow across multiple apps
     await testdriver.focusApplication('Google Chrome');
-    const data = await testdriver.remember('the order number');
+    const data = await testdriver.extract('the order number');
     
     await testdriver.focusApplication('Notepad');
     await testdriver.type(data);
@@ -221,7 +221,7 @@ describe('Multi-Application Workflow', () => {
     await testdriver.focusApplication('Google Chrome');
     
     // Get data from web page
-    const orderNumber = await testdriver.remember('the order number');
+    const orderNumber = await testdriver.extract('the order number');
     console.log('Order:', orderNumber);
     
     // Open Notepad

package/docs/v7/api/hover.mdx

@@ -130,7 +130,7 @@ await new Promise(r => setTimeout(r, 1000));
     await new Promise(r => setTimeout(r, 1000));
     
     // Read tooltip content
-    const tooltipText = await testdriver.remember('the tooltip text');
+    const tooltipText = await testdriver.extract('the tooltip text');
     console.log('Tooltip:', tooltipText);
     ```
   </Accordion>
@@ -225,7 +225,7 @@ describe('Hover Interactions', () => {
     await testdriver.assert('tooltip is displayed');
     
     // Extract tooltip text
-    const tooltipText = await testdriver.remember('the tooltip message');
+    const tooltipText = await testdriver.extract('the tooltip message');
     console.log('Tooltip says:', tooltipText);
   });