@testdriverai/agent 7.11.229-canary → 7.11.232-test

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

@@ -1,179 +1,103 @@
 ---
-title: "Waiting for Elements"
-sidebarTitle: "Waiting for Elements"
-description: "Prefer find() with a timeout over fixed wait() delays when waiting for elements to appear."
+title: "Wait for elements"
+sidebarTitle: "Waiting for elements"
+description: "Wait for elements with find() and a timeout instead of fixed wait() delays."
 icon: "hourglass-half"
 ---
 
-**When waiting for elements to appear, prefer `find()` with a `timeout` option over `wait()`.**
-
-## When to Use `wait()` vs `find()` with Timeout
-
-`wait()` is useful for **simple pauses** — after actions, for animations, or for state changes to settle:
+To wait for something to appear, give [`find()`](/find) a `timeout`. Don't pause with [`wait()`](/wait) and hope it's there.
 
 ```javascript
-await testdriver.find('submit button').click();
-await testdriver.wait(2000); // Wait for animation to complete
+const confirmation = await testdriver.find('Order confirmation heading', { timeout: 30000 });
 ```
 
-However, **don't use `wait()` to wait for elements to appear**. For that, use `find()` with a `timeout`:
-
-```javascript
-// ✅ GOOD: Polls until the element appears (up to 30s)
-const element = await testdriver.find('success message', { timeout: 30000 });
-
-// ❌ BAD: Arbitrary wait then hope the element is there
-await testdriver.wait(5000);
-const element = await testdriver.find('success message');
-```
+- `find()` returns as soon as the element appears, so fast runs stay fast.
+- It keeps checking until the timeout, so slow runs still pass.
+- A fixed `wait()` always takes its full duration, and may still be too short.
 
-## Why Prefer `find()` with Timeout for Element Waiting?
+## How find() waits
 
-Using arbitrary waits for element detection has problems:
+`find()` waits by default. It checks the screen, and if the element isn't there, it tries again:
 
-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
+- It waits 5 seconds between checks.
+- It stops after `timeout` milliseconds. The default is `10000` (10 seconds).
+- `timeout: 0` checks once and returns right away.
 
-## The Right Way: Element Polling with `find()`
+If the element never appears, `find()` doesn't throw. It returns an element whose `found()` is `false`. Calling `click()` or another action on that element throws `ElementNotFoundError`.
 
-TestDriver's `find()` method is designed for element detection. Use it in a polling loop to wait for elements:
+## Wait for a slow page
 
-### Basic Polling Pattern
+Raise the `timeout` for steps that take longer than 10 seconds, such as a page load or a file upload:
 
-```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));
-}
-```
+```javascript tests/checkout.test.mjs
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-### Helper Function for Polling
+it('places an order', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-Create a reusable helper function:
+  // ...sign in and fill the cart
 
-```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}`);
-}
+  const placeOrderButton = await testdriver.find('Place order button');
+  await placeOrderButton.click();
 
-// Usage
-const emailField = await waitForElement(testdriver, "Email input field");
-await emailField.click();
+  // Payment can take a while, so wait up to 30 seconds
+  const confirmation = await testdriver.find('Order confirmation heading', { timeout: 30000 });
+  expect(confirmation.found()).toBe(true);
+});
 ```
 
-## When to Use Polling
+## Handle an element that may not appear
 
-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
+For optional elements, like a cookie banner, use a short `timeout` and check `found()`:
 
 ```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}`);
-}
+const cookieBanner = await testdriver.find('Cookie consent banner', { timeout: 5000 });
 
-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();
-});
+if (cookieBanner.found()) {
+  const acceptButton = await testdriver.find('Accept button in the cookie banner');
+  await acceptButton.click();
+}
 ```
 
-## Advanced: Conditional Polling
+## Wait for an element to disappear
 
-For elements that may or may not appear (like dialogs or notifications):
+`find()` waits for elements to appear, not to go away. To wait for a spinner to disappear, check once per loop with `timeout: 0`:
 
 ```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...");
+const deadline = Date.now() + 30000;
+
+while (Date.now() < deadline) {
+  const spinner = await testdriver.find('Loading spinner', { timeout: 0 });
+  if (!spinner.found()) break;
+  await testdriver.wait(2000);
 }
 ```
 
-## Configuration
+## When to use wait()
 
-Adjust polling parameters based on your needs:
+`wait(ms)` pauses for a fixed time. It defaults to 3000 ms. Use it only when there's nothing on screen to wait for, such as letting an animation finish:
 
 ```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);
+await testdriver.wait(1000);
 ```
 
-## Summary
-
-| Pattern | Use Case |
-|---------|----------|
-| **Polling with `find()`** | ✅ Waiting for UI elements to appear or disappear |
-| **`wait()`** | ✅ Simple delays (animations, state changes) — ❌ Don't 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()` with a `timeout` option, not `wait()`. Use `wait()` for simple pauses between actions.**
+`waitForText()` and `waitForImage()` are deprecated. Use `find()` with a `timeout` instead.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="find()" icon="magnifying-glass" href="/find">
+    Every find() option, including timeout.
+  </Card>
+  <Card title="Locate elements" icon="crosshairs" href="/locating-elements">
+    Write descriptions that find the right element.
+  </Card>
+  <Card title="Debug a failing test" icon="bug" href="/debugging-with-screenshots">
+    Find out why an element wasn't found.
+  </Card>
+  <Card title="Redraw detection" icon="arrows-rotate" href="/redraw">
+    Wait for the screen to settle after each action.
+  </Card>
+</CardGroup>

package/docs/hosted.mdx

@@ -1,157 +1,93 @@
 ---
-title: "Hosted"
+title: "Hosted plans"
 sidebarTitle: "Hosted"
-description: "The fastest way to get started with TestDriver. Just set your API key and start testing."
+description: "Run tests on TestDriver's cloud sandboxes, billed by testing minutes, with no infrastructure to manage."
 icon: "cloud"
 mode: "wide"
 ---
 
-The hosted price uses **device-seconds**: the time that your tests run on **our infrastructure**.
+import { EnterpriseBadge, EnterpriseCta } from '/snippets/enterprise.mdx';
 
-- **Zero Setup**. Start tests immediately. You do not need DevOps.
-- **Free Tier** — Start with a limited preview at no cost.
-- **Pay As You Go** — Pay only for the device-seconds that you use.
+By default, your tests run on TestDriver's cloud. Each test gets a fresh sandbox, and you don't manage any machines.
 
-## Hosted Plans
+- Hosted is the default. When you follow the [Quickstart](/quickstart), you're using it.
+- You're billed in **testing minutes**: the time a sandbox is running.
+- Your plan sets how many sandboxes can run at the same time.
 
-<CardGroup cols={3}>
-  <Card title="Free Trial" icon="gift" href="https://docs.testdriver.ai">
-    **$0/month**
-    
-    - 1 Concurrent Sandbox
-    - 60 Minutes Included
-    - 1 Team User
-    - Community Support
+## Plans
+
+| | Free | Pro | Team |
+| --- | --- | --- | --- |
+| **Price** | $0 | $20 per seat per month | $600 per month |
+| **Testing minutes included** | 30 | 120 | 10,000 |
+| **Extra minutes** | Not available | $0.14 per minute | $0.14 per minute |
+| **Sandboxes at once** | 2 | 4 | 8 |
+| **Users** | Unlimited | One per seat | 5 |
+| **Test analytics** | No | Yes | Yes |
+| **CPU, RAM, and network profiles** | No | Yes | Yes |
+| **Support** | Community | Community | Private |
+
+<EnterpriseCta feature="Windows sandboxes, custom screen resolutions, and self-hosting" plural />
+
+Pro starts with a 14-day free trial. Start a plan from the [TestDriver console](https://console.testdriver.ai/checkout/pro).
+
+On the Free plan, new sandboxes are refused once you've used your 30 minutes. Upgrade to keep testing.
+
+<Note>
+  If you install TestDriver from GitHub Marketplace, GitHub bills you instead. The **Open Source** plan is free with 300 testing minutes per month. The **Team** plan is $20 per seat per month with 120 testing minutes per seat.
+</Note>
+
+## How testing minutes are counted
+
+Testing minutes run while a sandbox is running. That includes sandboxes started by:
+
+- Your test runs, locally and in CI.
+- The TestDriver agent, when it reviews a pull request or writes a test.
+
+A sandbox kept running with [`keepAlive`](/customizing-devices#keep-a-sandbox-alive) uses minutes until it shuts down. Keep `keepAlive` as short as you need.
+
+## Concurrency
+
+Each running sandbox uses one of your plan's slots. A slot frees up when its sandbox shuts down.
+
+When every slot is busy, a new test waits for a free slot instead of failing. The SDK retries every 10 seconds, for up to 60 seconds by default. Set `TD_CONCURRENCY_MAX_WAIT` to change the wait. See [Concurrency limits](/ci-cd#concurrency-limits).
+
+To stay within your slots, limit how many test files Vitest runs at once:
+
+```bash
+npx vitest run --maxWorkers=4
+```
+
+In GitHub Actions, a `concurrency` group stops two runs on the same branch from competing for slots. A new push cancels the older run:
+
+```yaml .github/workflows/testdriver.yml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+## When to self-host
+
+Consider [self-hosting](/self-hosted) when you need to:
+
+- Run tests on your own infrastructure, without per-minute billing.
+- Use your own AI provider keys.
+- Run custom VM images with your software preinstalled.
+- Run more tests in parallel than the hosted plans allow.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="play" href="/quickstart">
+    Run your first test on a hosted sandbox.
   </Card>
-  
-  <Card title="Pro" icon="rocket" href="https://console.testdriver.ai/checkout/pro">
-    **$20/month per user**
-    
-    - 2 Concurrent Sandboxes
-    - 120 Minutes Included
-    - Overage: $0.001/second
-    - Test Recordings
-    - Community Support
+  <Card title="Run tests in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your tests on every push and pull request.
   </Card>
-  
-  <Card title="Team" icon="users" href="https://console.testdriver.ai/checkout/team">
-    **$600/month**
-    
-    - 8 Concurrent Sandboxes
-    - 10,000 Minutes Included
-    - Overage: $0.001/second
-    - 5 Team Users
-    - Test Recordings
-    - Private Support
-    - Test Analytics
-    - CPU, RAM, & Network Profiles
+  <Card title="Self-hosted" icon="server" href="/self-hosted">
+    Run sandboxes on your own infrastructure.
+  </Card>
+  <Card title="Run tests" icon="play" href="/copilot/running-tests">
+    Run tests locally and in parallel.
   </Card>
 </CardGroup>
-
-## Get Started
-Hosted is the default when you follow the Quickstart guide. 
-<Card
-  title="Try the Quickstart"  
-  icon="play"
-  href="/quickstart"
->
-  Set your API key and start testing in minutes.
-</Card>
-
-## Parallel Testing Limits
-
-Your account has a set number of **license slots** that determine how many devices can run simultaneously. You can view your available slots in the [TestDriver Dashboard](https://console.testdriver.ai).
-
-<Info>
-  **When is a slot in use?** A license slot is occupied when a test client is connected. As soon as your device is destroyed the slot becomes available immediately.
-</Info>
-
-## Avoiding Slot Conflicts
-
-To prevent tests from failing due to exceeding your license slot limit, we recommend two key configurations:
-
-<AccordionGroup>
-  <Accordion title="Set Maximum Concurrency in Vitest">
-    Limit concurrent tests to match your available license slots:
-
-    ```javascript vitest.config.mjs
-    import { defineConfig } from 'vitest/config';
-    import TestDriver from 'testdriverai/vitest';
-
-    export default defineConfig({
-      test: {
-        testTimeout: 900000,
-        hookTimeout: 900000,
-        maxConcurrency: 5, // Set to your license slot limit
-        reporters: ['default', TestDriver()],
-        setupFiles: ['testdriverai/vitest/setup'],
-      },
-    });
-    ```
-
-    <Tip>
-      Check your slot count at [console.testdriver.ai](https://console.testdriver.ai) and set `maxConcurrency` to that number or lower.
-    </Tip>
-  </Accordion>
-
-  <Accordion title="Use GitHub Concurrency Keys">
-    Prevent multiple workflow runs from competing for the same slots by using [GitHub's concurrency controls](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs):
-
-    ```yaml .github/workflows/test.yml
-    name: Tests
-
-    on:
-      push:
-        branches: [main]
-      pull_request:
-
-    # Prevent concurrent runs from competing for license slots
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
-      cancel-in-progress: true
-
-    jobs:
-      test:
-        runs-on: ubuntu-latest
-        steps:
-          - uses: actions/checkout@v4
-          
-          - name: Setup Node.js
-            uses: actions/setup-node@v4
-            with:
-              node-version: '20'
-          
-          - name: Install dependencies
-            run: npm install
-          
-          - name: Run tests
-            run: vitest run
-            env:
-              TD_API_KEY: ${{ secrets.TD_API_KEY }}
-    ```
-
-    The `concurrency` block ensures:
-    - Only one workflow run per branch runs at a time
-    - New pushes cancel in-progress runs on the same branch
-    - Different branches/PRs can run in parallel (up to your slot limit)
-  </Accordion>
-</AccordionGroup>
-
-## When to Consider Self-Hosted
-
-Hosted is perfect for getting started and for teams that want zero infrastructure management. However, you might consider [Self-Hosted](/self-hosted) if you:
-
-- Want to escape per-second billing with a flat license fee
-- Require greater concurrency than offered in Cloud plans
-- Need full control over your infrastructure and privacy
-- Want to use your own AI API keys
-- Require custom hardware configurations
-- Have high test volumes that make self-hosting more economical
-
-<Card
-  title="Explore Self-Hosted"
-  icon="server"
-  href="/self-hosted"
->
-  Learn about self-hosting for unlimited test execution at a flat rate.
-</Card>