testdriverai 6.2.2 → 7.1.0

package/docs/docs.json

@@ -12,175 +12,309 @@
   },
   "favicon": "/images/template/icon.png",
   "navigation": {
-    "groups": [
+    "tabs": [
       {
-        "group": "Overview",
-        "pages": [
-          "/overview/what-is-testdriver",
+        "tab": "Computer-Use SDK",
+        "versions": [
           {
-            "group": "Concepts",
-            "icon": "book",
-            "pages": [
-              "/features/selectorless",
-              "/overview/comparison",
-              "/overview/performance",
-              "/overview/faq"
+            "version": "7.0.0 (SDK)",
+            "groups": [
+              {
+                "group": "Getting Started",
+                "pages": [
+                  "/v7/getting-started/quickstart",
+                  {
+                    "group": "Configuration",
+                    "icon": "gear",
+                    "pages": [
+                      "/v7/getting-started/configuration",
+                      {
+                        "group": "Platforms",
+                        "icon": "server",
+                        "pages": [
+                          "/v7/platforms/linux",
+                          "/v7/platforms/windows",
+                          "/v7/platforms/macos"
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Examples",
+                "icon": "code",
+                "pages": [
+                  "/v7/presets/chrome",
+                  "/v7/presets/chrome-extension",
+                  "/v7/presets/vscode",
+                  "/v7/presets/electron"
+                ]
+              },
+              {
+                "group": "Interactions",
+                "icon": "bolt",
+                "pages": [
+                  "/v7/api/find",
+                  "/v7/api/ai",
+                  "/v7/api/click",
+                  "/v7/api/doubleClick",
+                  "/v7/api/rightClick",
+                  "/v7/api/hover",
+                  "/v7/api/mouseDown",
+                  "/v7/api/mouseUp",
+                  "/v7/api/type",
+                  "/v7/api/pressKeys",
+                  "/v7/api/scroll",
+                  "/v7/api/focusApplication",
+                  "/v7/api/assert",
+                  "/v7/api/exec"
+                ]
+              },
+              {
+                "group": "Core Concepts",
+                "icon": "book",
+                "pages": [
+                  "/v7/api/client",
+                  "/v7/api/sandbox",
+                  "/v7/api/elements",
+                  "/v7/api/dashcam",
+                  "/v7/api/assertions"
+                ]
+              },
+              {
+                "group": "Progressive APIs",
+                "icon": "layer-group",
+                "pages": [
+                  "/v7/progressive-apis/PROGRESSIVE_DISCLOSURE",
+                  "/v7/progressive-apis/PROVISION",
+                  "/v7/progressive-apis/HOOKS"
+                ]
+              },
+            
+              {
+                "group": "Guides",
+                "icon": "book-open",
+                "pages": [
+                  "/v7/guides/vitest",
+                  "/v7/guides/vitest-plugin",
+                  "/v7/guides/debugging",
+                  "/v7/guides/best-practices",
+                  "/v7/guides/troubleshooting",
+                  "/v7/guides/faq",
+                  {
+                    "group": "Caching",
+                    "icon": "bolt",
+                    "pages": [
+                      "/v7/guides/caching-ai",
+                      "/v7/guides/caching-selectors"
+                    ]
+                  },
+                  {
+                    "group": "CI/CD Integration",
+                    "icon": "arrows-spin",
+                    "pages": [
+                      "/v7/guides/ci-cd/overview",
+                      "/v7/guides/ci-cd/github-actions",
+                      "/v7/guides/ci-cd/gitlab",
+                      "/v7/guides/ci-cd/circleci",
+                      "/v7/guides/ci-cd/jenkins",
+                      "/v7/guides/ci-cd/azure",
+                      "/v7/guides/ci-cd/travis"
+                    ]
+                  },
+                  "/v7/guides/performance",
+                  "/v7/guides/self-hosting",
+                  "/v7/guides/migration"
+                ]
+              }
             ]
           },
-          "/account/enterprise"
-        ]
-      },
-      {
-        "group": "Get Started",
-        "pages": [
-          "/overview/quickstart",
           {
-            "group": "CLI",
-            "icon": "terminal",
-            "pages": [
-              "/cli/overview",
+            "version": "6.X.X (YAML)",
+            "groups": [
+              {
+                "group": "Overview",
+                "pages": [
+                  "/v6/overview/what-is-testdriver",
+                  {
+                    "group": "Concepts",
+                    "icon": "book",
+                    "pages": [
+                      "/v6/features/selectorless",
+                      "/v6/overview/comparison",
+                      "/v6/overview/performance",
+                      "/v6/overview/faq"
+                    ]
+                  },
+                  "/v6/account/enterprise"
+                ]
+              },
+              {
+                "group": "Get Started",
+                "pages": [
+                  "/v6/overview/quickstart",
+                  {
+                    "group": "CLI",
+                    "icon": "terminal",
+                    "pages": [
+                      "/v6/cli/overview",
+                      {
+                        "group": "Commands",
+                        "icon": "command",
+                        "pages": [
+                          "/v6/interactive/explore",
+                          "/v6/interactive/run",
+                          "/v6/interactive/save"
+                        ]
+                      }
+                    ]
+                  },
+                  "/v6/getting-started/self-hosting",
+                  "/v6/getting-started/playwright",
+                  "/v6/getting-started/vscode"
+                ]
+              },
+              {
+                "group": "Examples",
+                "pages": [
+                  {
+                    "group": "Apps",
+                    "icon": "laptop",
+                    "pages": [
+                      "apps/static-websites",
+                      "apps/desktop-apps",
+                      "apps/chrome-extensions",
+                      "apps/mobile-apps",
+                      "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"
+                    ]
+                  },
+                  {
+                    "group": "Build Systems",
+                    "icon": "helmet-safety",
+                    "pages": [
+                      "/v6/integrations/electron",
+                      "/v6/integrations/netlify",
+                      "/v6/integrations/vercel"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Guide",
+                "pages": [
+                  {
+                    "group": "Configuration",
+                    "icon": "desktop",
+                    "pages": [
+                      "/v6/guide/authentication",
+                      "/v6/guide/variables",
+                      "/v6/guide/lifecycle",
+                      "/v6/guide/dashcam",
+                      "/v6/guide/environment-variables",
+                      "/v6/action/ami"
+                    ]
+                  },
+                  {
+                    "group": "Writing",
+                    "icon": "pencil",
+                    "pages": [
+                      "/v6/features/generation",
+                      "/v6/guide/locating",
+                      "/v6/guide/waiting",
+                      "/v6/guide/assertions",
+                      "/v6/guide/code",
+                      "/v6/features/reusable-snippets",
+                      "/v6/guide/protips"
+                    ]
+                  },
+                  {
+                    "group": "Importing",
+                    "icon": "file-import",
+                    "pages": [
+                      "/v6/importing/csv",
+                      "/v6/importing/gherkin",
+                      "/v6/importing/jira",
+                      "/v6/importing/testrail"
+                    ]
+                  },
+                  {
+                    "group": "Running",
+                    "icon": "play",
+                    "pages": [
+                      "/v6/getting-started/running",
+                      "/v6/getting-started/ci",
+                      "/v6/features/parallel-testing",
+                      "/v6/action/performance",
+                      "/v6/action/secrets"
+                    ]
+                  },
+                  {
+                    "group": "Maintaining",
+                    "icon": "wrench",
+                    "pages": ["/v6/getting-started/editing", "/v6/features/auto-healing"]
+                  },
+                  {
+                    "group": "Reporting",
+                    "icon": "chart-simple",
+                    "pages": ["exporting/junit", "/v6/bugs/jira"]
+                  }
+                ]
+              },
               {
-                "group": "Commands",
-                "icon": "command",
+                "group": "Reference",
                 "pages": [
-                  "/interactive/explore",
-                  "/interactive/run",
-                  "/interactive/save"
+                  {
+                    "group": "YAML",
+                    "icon": "file-code",
+                    "pages": [
+                      "/v6/commands/assert",
+                      "/v6/commands/exec",
+                      "/v6/commands/focus-application",
+                      "/v6/commands/hover-image",
+                      "/v6/commands/hover-text",
+                      "/v6/commands/if",
+                      "/v6/commands/match-image",
+                      "/v6/commands/press-keys",
+                      "/v6/commands/remember",
+                      "/v6/commands/run",
+                      "/v6/commands/scroll",
+                      "/v6/commands/scroll-until-image",
+                      "/v6/commands/scroll-until-text",
+                      "/v6/commands/type",
+                      "/v6/commands/wait",
+                      "/v6/commands/wait-for-image",
+                      "/v6/commands/wait-for-text"
+                    ]
+                  }
                 ]
               }
             ]
-          },
-          "/getting-started/self-hosting",
-          "/getting-started/playwright",
-          "/getting-started/vscode"
+          }
         ]
       },
       {
-        "group": "Examples",
-        "pages": [
-          {
-            "group": "Apps",
-            "icon": "laptop",
-            "pages": [
-              "apps/static-websites",
-              "apps/desktop-apps",
-              "apps/chrome-extensions",
-              "apps/mobile-apps",
-              "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"
-            ]
-          },
-          {
-            "group": "Build Systems",
-            "icon": "helmet-safety",
-            "pages": [
-              "/integrations/electron",
-              "/integrations/netlify",
-              "/integrations/vercel"
-            ]
-          }
-        ]
+        "tab": "Playwright SDK",
+        "pages": ["v7/playwright"]
       },
       {
-        "group": "Guide",
-        "pages": [
-          {
-            "group": "Configuration",
-            "icon": "desktop",
-            "pages": [
-              "/guide/authentication",
-              "/guide/variables",
-              "/guide/lifecycle",
-              "/guide/dashcam",
-              "/guide/environment-variables",
-              "/action/ami"
-            ]
-          },
-          {
-            "group": "Writing",
-            "icon": "pencil",
-            "pages": [
-              "/features/generation",
-              "/guide/locating",
-              "/guide/waiting",
-              "/guide/assertions",
-              "/guide/code",
-              "/features/reusable-snippets",
-              "/guide/protips"
-            ]
-          },
-          {
-            "group": "Importing",
-            "icon": "file-import",
-            "pages": [
-              "/importing/csv",
-              "/importing/gherkin",
-              "/importing/jira",
-              "/importing/testrail"
-            ]
-          },
-          {
-            "group": "Running",
-            "icon": "play",
-            "pages": [
-              "/getting-started/running",
-              "/getting-started/ci",
-              "/features/parallel-testing",
-              "/action/performance",
-              "/action/secrets"
-            ]
-          },
-          {
-            "group": "Maintaining",
-            "icon": "wrench",
-            "pages": ["/getting-started/editing", "/features/auto-healing"]
-          },
-          {
-            "group": "Reporting",
-            "icon": "chart-simple",
-            "pages": ["exporting/junit", "/bugs/jira"]
-          }
-        ]
+        "tab": "Playwright Studio"
       },
       {
-        "group": "Reference",
-        "pages": [
-          {
-            "group": "YAML",
-            "icon": "file-code",
-            "pages": [
-              "/commands/assert",
-              "/commands/exec",
-              "/commands/focus-application",
-              "/commands/hover-image",
-              "/commands/hover-text",
-              "/commands/if",
-              "/commands/match-image",
-              "/commands/press-keys",
-              "/commands/remember",
-              "/commands/run",
-              "/commands/scroll",
-              "/commands/scroll-until-image",
-              "/commands/scroll-until-text",
-              "/commands/type",
-              "/commands/wait",
-              "/commands/wait-for-image",
-              "/commands/wait-for-text"
-            ]
-          }
-        ]
+        "tab": "Dashcam CLI"
       }
     ]
   },

package/docs/guide/best-practices-polling.mdx

@@ -0,0 +1,154 @@
+# Best Practices: Element Polling
+
+**⚠️ CRITICAL: Never use `wait()` for waiting for elements to appear.**
+
+## Why Avoid `wait()`?
+
+Arbitrary waits with `wait()` have several problems:
+
+1. **Brittle**: Fixed timeouts may be too short (causing flaky tests) or too long (wasting time)
+2. **Slow**: You always wait the full duration, even if the element appears sooner
+3. **Unreliable**: Network conditions, system load, and other factors affect timing
+4. **Hard to debug**: When tests fail, you don't know if it was a timing issue or actual failure
+
+## The Right Way: Element Polling with `find()`
+
+TestDriver's `find()` method is designed for element detection. Use it in a polling loop to wait for elements:
+
+### Basic Polling Pattern
+
+```javascript
+// ❌ WRONG: Using wait()
+await testdriver.wait(2000);
+const button = await testdriver.find("Submit button");
+
+// ✅ CORRECT: Polling with find()
+let button;
+for (let i = 0; i < 10; i++) {
+  try {
+    button = await testdriver.find("Submit button");
+    if (button.found()) break;
+  } catch (e) {
+    if (i === 9) throw e; // Re-throw on last attempt
+  }
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+```
+
+### Helper Function for Polling
+
+Create a reusable helper function:
+
+```javascript
+async function waitForElement(testdriver, description, maxAttempts = 10, delayMs = 1000) {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      const element = await testdriver.find(description);
+      if (element.found()) {
+        return element;
+      }
+    } catch (e) {
+      if (i === maxAttempts - 1) throw e;
+    }
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+  }
+  throw new Error(`Element not found after ${maxAttempts} attempts: ${description}`);
+}
+
+// Usage
+const emailField = await waitForElement(testdriver, "Email input field");
+await emailField.click();
+```
+
+## When to Use Polling
+
+Use element polling in these scenarios:
+
+- **After navigation**: Waiting for a new page to load
+- **After user action**: Waiting for UI updates (form submission, modal opening, etc.)
+- **Dynamic content**: Waiting for AJAX-loaded elements
+- **State transitions**: Waiting for loading spinners to disappear or success messages to appear
+
+## Example: Complete Login Flow
+
+```javascript
+import { chrome } from "testdriverai/presets";
+
+// Helper function
+async function waitForElement(testdriver, description, maxAttempts = 10, delayMs = 1000) {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      const element = await testdriver.find(description);
+      if (element.found()) return element;
+    } catch (e) {
+      if (i === maxAttempts - 1) throw e;
+    }
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+  }
+  throw new Error(`Element not found after ${maxAttempts} attempts: ${description}`);
+}
+
+it("should log in successfully", async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com/login',
+  });
+
+  // Wait for login page to load
+  const emailField = await waitForElement(testdriver, "Email input field");
+  await emailField.click();
+  await testdriver.type("user@example.com");
+
+  const passwordField = await testdriver.find("Password input field");
+  await passwordField.click();
+  await testdriver.type("password123");
+
+  const loginButton = await testdriver.find("Login button");
+  await loginButton.click();
+
+  // Wait for dashboard to load after login
+  await waitForElement(testdriver, "Dashboard welcome message");
+  
+  // Verify login successful
+  const isLoggedIn = await testdriver.assert("user is logged in to dashboard");
+  expect(isLoggedIn).toBeTruthy();
+});
+```
+
+## Advanced: Conditional Polling
+
+For elements that may or may not appear (like dialogs or notifications):
+
+```javascript
+// Try to find and dismiss optional dialog
+try {
+  const dialog = await waitForElement(testdriver, "Cookie consent dialog", 3, 500);
+  const acceptButton = await testdriver.find("Accept button");
+  await acceptButton.click();
+  console.log("Dismissed cookie dialog");
+} catch {
+  console.log("No cookie dialog found, continuing...");
+}
+```
+
+## Configuration
+
+Adjust polling parameters based on your needs:
+
+```javascript
+// Quick polling for fast UI updates (check every 300ms, up to 3 seconds)
+await waitForElement(testdriver, "Success message", 10, 300);
+
+// Patient polling for slow operations (check every 2s, up to 20 seconds)
+await waitForElement(testdriver, "Processing complete indicator", 10, 2000);
+```
+
+## Summary
+
+| Pattern | Use Case |
+|---------|----------|
+| **Polling with `find()`** | ✅ Waiting for UI elements to appear or disappear |
+| **`wait()`** | ❌ NEVER use for element waiting |
+| **Helper function** | ✅ Recommended for cleaner, reusable code |
+| **Conditional polling** | ✅ For optional elements (dialogs, notifications) |
+
+Remember: **If you're waiting for something to appear on screen, use `find()` in a polling loop, not `wait()`.**