@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/performing-actions.mdx

@@ -1,149 +1,159 @@
 ---
-title: "Self-Healing"
-sidebarTitle: "Self-Healing"
-description: "Perform actions and handle dynamic, async UI so tests adapt to change"
-icon: "arrows-rotate"
+title: "Perform actions"
+sidebarTitle: "Performing actions"
+description: "Click, type, scroll, and read the screen, and wait for a changing UI."
+icon: "arrow-pointer"
 ---
 
-Real apps move, load, and change. Adapt your tests to these conditions.
+A TestDriver test acts on the screen the way a person does, with the real mouse and keyboard.
 
-You [generated](/generating-tests) and [learned](/caching) your tests. Then you got them to [run](/copilot/running-tests). Now the challenge is the real world: buttons show after a spinner, pages navigate, animations play, and content comes in over the network. To keep the tests reliable, do the correct actions and control the timing. Then your tests adapt to the true behavior of the UI. They do not break.
+- Find an element by describing it.
+- Click it, type into it, or scroll past it.
+- Wait for a UI that loads, animates, or changes as you use it.
 
-## Performing Actions
+## Find an element, then act on it
 
-TestDriver gives you many actions. You can [click](/click), [type](/type), [hover](/hover), and [scroll](/scroll). For a full list, read the [API Reference](/click).
+`find()` returns an element, and the element has methods for mouse actions:
 
 ```javascript
-// Clicking
-await testdriver.find('submit button').click();
-await testdriver.find('file item').doubleClick();
-await testdriver.find('text area').rightClick();
-
-// Typing
-await testdriver.find('email input').type('user@example.com');
-await testdriver.find('password input').type('secret', { secret: true });
+const submitButton = await testdriver.find('Submit button');
+await submitButton.click();
+```
 
-// Keyboard shortcuts
-await testdriver.pressKeys(['enter']);
-await testdriver.pressKeys(['ctrl', 'c']);
+You can also chain the action straight onto `find()`:
 
-// Hovering
-await testdriver.find('dropdown menu').hover();
+```javascript
+await testdriver.find('Submit button').click();
+```
 
-// Scrolling
-await testdriver.scroll('down', 500);
+| Method | What it does |
+| --- | --- |
+| [`click()`](/click) | Left-clicks the element |
+| [`doubleClick()`](/double-click) | Double-clicks the element |
+| [`rightClick()`](/right-click) | Right-clicks the element, for example to open a context menu |
+| [`hover()`](/hover) | Moves the mouse over the element without clicking |
+| [`mouseDown()`](/mouse-down) and [`mouseUp()`](/mouse-up) | Press and release the mouse button separately, for dragging |
 
-// Waiting
-await testdriver.wait(2000); // Wait 2 seconds for animation/state change
+If `find()` can't locate the element, it returns an element whose `found()` is `false`. Calling one of these methods on it throws an `ElementNotFoundError`.
 
-// Extracting information from screen
-const price = await testdriver.extract('the total price');
-const orderNumber = await testdriver.extract('the order confirmation number');
-```
+See [Locate elements](/locating-elements) to write descriptions that find the right element.
 
-### Chaining Actions
+## Type text
 
-TestDriver lets you chain methods for cleaner code:
+[`type()`](/type) types into whatever has keyboard focus, so click the field first:
 
 ```javascript
-// Chain find() with actions
-const button = await testdriver.find('submit button').click();
+const emailField = await testdriver.find('Email input field');
+await emailField.click();
+await testdriver.type('user@example.com');
 ```
 
-Or keep the element reference for later use:
+Pass `secret: true` for passwords and other sensitive values. TestDriver then doesn't log or store the text:
 
 ```javascript
-const button = await testdriver.find('submit button');
-await button.click();
+await testdriver.find('Password input field').click();
+await testdriver.type(process.env.TD_PASSWORD, { secret: true });
 ```
 
-## Waiting for Dynamic Content
+See [Secrets](/secrets) for keeping credentials out of your test code.
 
-By default, `find()` polls automatically for a maximum of 10 seconds. It tries again each 5 seconds until it finds the element. Thus TestDriver finds most elements that show after short async operations. You do not need more configuration.
+## Press keys and shortcuts
 
-For longer operations, make the `timeout` larger:
+[`pressKeys()`](/press-keys) takes an array of keys and presses them together:
 
 ```javascript
-// Default behavior - polls for up to 10 seconds automatically
-const element = await testdriver.find('Loading complete indicator');
-await element.click();
+await testdriver.pressKeys(['enter']);
+await testdriver.pressKeys(['ctrl', 'a']);
+await testdriver.pressKeys(['ctrl', 'shift', 'i']);
+```
 
-// Wait up to 30 seconds for slower operations
-const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
-await element.click();
+## Scroll
 
-// Useful after actions that trigger loading states
-await testdriver.find('submit button').click();
-await testdriver.find('success message', { timeout: 15000 });
+[`scroll()`](/scroll) scrolls the page up or down with the mouse wheel. The default `amount` is 300:
 
-// Disable polling for instant checks
-const toast = await testdriver.find('notification toast', { timeout: 0 });
+```javascript
+await testdriver.scroll('down', { amount: 1000 });
 ```
 
-### Flake Prevention
+If scrolling doesn't move the page, click somewhere on it first. That gives the page focus instead of another window.
 
-TestDriver automatically waits for the screen and network to stabilize after each action using **redraw detection**. This prevents flaky tests caused by animations, loading states, or dynamic content updates.
+## Read values from the screen
 
-<Note>
-  Redraw detection adds a small delay after each action but significantly reduces test flakiness.
-</Note>
-
-For example, when clicking a submit button that navigates to a new page:
+[`extract()`](/extract) reads information off the screen in plain language and returns it as a string. Use it for values the test needs later:
 
 ```javascript
-// Click submit - TestDriver automatically waits for the new page to load
-await testdriver.find('submit button').click();
-
-// By the time this runs, the page has fully loaded and stabilized
-await testdriver.assert('dashboard is displayed');
-await testdriver.find('welcome message');
+const orderNumber = await testdriver.extract('the order confirmation number');
+console.log(orderNumber); // for example "A-10482"
 ```
 
-Without redraw detection, you'd need manual waits or retries to handle the page transition. TestDriver handles this automatically by detecting when the screen stops changing and network requests complete.
+## Wait for a changing UI
+
+Most timing problems come from acting before the app is ready. Wait for what the next step depends on, not for a fixed time.
+
+### Wait for an element with find()
 
-You can disable redraw detection or customize its behavior:
+`find()` already waits. It checks the screen every 5 seconds, for up to 10 seconds, until the element appears.
+
+For something slower, such as a page that loads after a form submits, raise the `timeout`:
 
 ```javascript
-// Disable redraw detection for faster tests (less reliable)
-const testdriver = TestDriver(context, { 
-  redraw: false 
-});
+await testdriver.find('Submit button').click();
+
+// Keep looking for up to 30 seconds while the next page loads
+const confirmation = await testdriver.find('Order confirmation message', { timeout: 30000 });
 ```
 
-Here is an example of customizing redraw detection:
+Set `timeout: 0` to check once without waiting. For example, check whether an optional banner is showing:
 
 ```javascript
-// Fine-tune redraw detection
-const testdriver = TestDriver(context, { 
-  redraw: {
-    enabled: true,
-    diffThreshold: 0.1,      // Pixel difference threshold (0-1)
-    screenRedraw: true,      // Monitor screen changes
-    networkMonitor: true,    // Wait for network idle
-  }
-});
+const cookieBanner = await testdriver.find('cookie consent banner', { timeout: 0 });
+if (cookieBanner.found()) {
+  await testdriver.find('Accept all cookies button').click();
+}
 ```
 
-### Simple Delays with `wait()`
+### Pause with wait()
 
-For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+[`wait()`](/wait) pauses for a fixed number of milliseconds. Use it only when there's nothing specific to wait for, such as an animation:
 
 ```javascript
-// Wait for an animation to complete
-await testdriver.find('menu toggle').click();
-await testdriver.wait(2000);
-
-// Wait for a page transition to settle
-await testdriver.find('next page button').click();
+await testdriver.find('Menu toggle').click();
 await testdriver.wait(1000);
 ```
 
-<Note>
-  For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.
-</Note>
+### Wait for the screen to settle with redraw detection
+
+For apps with a lot of animation or loading states, turn on redraw detection. After each action, TestDriver waits until the screen stops changing:
+
+```javascript
+const testdriver = TestDriver(context, { redraw: true });
+```
+
+Redraw detection is off by default because it adds a short delay after every action.
+
+To also wait for network activity to finish, enable network monitoring:
 
-Once your tests can reliably act on a changing UI and [assert](/making-assertions) the results, the next step is figuring out what happened when something does go wrong.
+```javascript
+const testdriver = TestDriver(context, {
+  redraw: { thresholds: { network: true } },
+});
+```
 
-<Card title="Next: Debug" icon="bug" href="/debugging-with-screenshots">
-  Use screenshots and run output to see exactly what your test saw and pinpoint failures.
-</Card>
+See [Redraw](/redraw) for every option.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Check the result of your actions in plain language.
+  </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">
+    See what the screen showed at each step.
+  </Card>
+  <Card title="Prevent regressions" icon="shield-check" href="/copilot/auto-healing">
+    Catch regressions in CI and repair tests when your UI changes.
+  </Card>
+</CardGroup>

package/docs/press-keys.mdx

@@ -1,349 +1,109 @@
 ---
 title: "pressKeys()"
 sidebarTitle: "pressKeys"
-description: "Press keyboard keys and shortcuts"
+description: "Press a key or a keyboard shortcut, like Enter, Tab or Ctrl+A."
 icon: "keyboard"
 ---
 
-## Overview
+Press a single key or a keyboard shortcut in the sandbox:
 
-Push one or more keyboard keys at the same time. Use this for keyboard shortcuts, navigation, and special keys.
+```javascript
+await testdriver.pressKeys(['enter']);
+await testdriver.pressKeys(['ctrl', 'a']);
+```
 
-## Syntax
+To enter text, use [`type()`](/type) instead.
 
-```javascript
-await testdriver.pressKeys(keys)
+## Signature
+
+```typescript
+testdriver.pressKeys(keys: KeyboardKey[]): Promise<void>
 ```
 
 ## Parameters
 
-<ParamField path="keys" type="Array&lt;string&gt;" required>
-  An array of the keys to push at the same time
+<ParamField path="keys" type="KeyboardKey[]" required>
+  The keys to press, as a shortcut. TestDriver presses them in order, holds them all down, then releases them in reverse order. So `['ctrl', 'shift', 'i']` is Ctrl+Shift+I.
+
+  Each name must be a valid `KeyboardKey`. See [Key names](#key-names).
 </ParamField>
 
-## Returns
+Because the keys are pressed together, `['enter', 'enter']` doesn't press Enter twice. Call `pressKeys()` once per key press instead.
 
-`Promise<void>`
+## Key names
 
-## Common Keys
+Key names are lowercase. The most common ones:
 
-### Special Keys
-- `'enter'`, `'tab'`, `'escape'`, `'backspace'`, `'delete'`
-- `'space'`, `'up'`, `'down'`, `'left'`, `'right'`
-- `'home'`, `'end'`, `'pageup'`, `'pagedown'`
+| Kind | Names |
+| --- | --- |
+| Letters, digits, symbols | `'a'`–`'z'`, `'0'`–`'9'`, and single characters like `'/'` or `'.'` |
+| Editing | `'enter'`, `'tab'`, `'space'`, `'backspace'`, `'delete'`, `'escape'` |
+| Navigation | `'up'`, `'down'`, `'left'`, `'right'`, `'home'`, `'end'`, `'pageup'`, `'pagedown'` |
+| Modifiers | `'ctrl'`, `'shift'`, `'alt'`, `'win'`, and left/right forms like `'ctrlleft'` |
+| Function keys | `'f1'`–`'f24'` |
 
-### Modifier Keys
-- `'ctrl'`, `'alt'`, `'shift'`
-- `'command'` (macOS), `'win'` (Windows)
-- `'ctrlleft'`, `'ctrlright'`, `'shiftleft'`, `'shiftright'`
+The full list is the `KeyboardKey` type in `sdk.d.ts`, which your editor autocompletes.
 
-### Function Keys
-- `'f1'` through `'f24'`
+<Note>
+  Sandboxes run Linux by default, or Windows. Use `'ctrl'` for shortcuts like copy and paste, not `'command'`.
+</Note>
 
 ## Examples
 
-### Navigation
+### Move between form fields
 
 ```javascript
-// Tab to next field
+await testdriver.find('Email input field').click();
+await testdriver.type('user@example.com');
 await testdriver.pressKeys(['tab']);
-
-// Shift+Tab to previous field
-await testdriver.pressKeys(['shift', 'tab']);
-
-// Arrow keys
-await testdriver.pressKeys(['down']);
-await testdriver.pressKeys(['up']);
-await testdriver.pressKeys(['left']);
-await testdriver.pressKeys(['right']);
-
-// Home/End
-await testdriver.pressKeys(['home']);  // Start of line
-await testdriver.pressKeys(['end']);   // End of line
-
-// Page navigation
-await testdriver.pressKeys(['pagedown']);
-await testdriver.pressKeys(['pageup']);
+await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+await testdriver.pressKeys(['enter']);
 ```
 
-### Keyboard Shortcuts
+### Replace the text in a field
 
 ```javascript
-// Copy (Ctrl+C / Cmd+C)
-await testdriver.pressKeys(['ctrl', 'c']);
-
-// Paste (Ctrl+V / Cmd+V)
-await testdriver.pressKeys(['ctrl', 'v']);
-
-// Save (Ctrl+S)
-await testdriver.pressKeys(['ctrl', 's']);
-
-// Select All (Ctrl+A)
+await testdriver.find('Search input').click();
 await testdriver.pressKeys(['ctrl', 'a']);
-
-// Undo (Ctrl+Z)
-await testdriver.pressKeys(['ctrl', 'z']);
-
-// Redo (Ctrl+Y)
-await testdriver.pressKeys(['ctrl', 'y']);
-
-// Find (Ctrl+F)
-await testdriver.pressKeys(['ctrl', 'f']);
-
-// New tab (Ctrl+T)
-await testdriver.pressKeys(['ctrl', 't']);
-
-// Close tab (Ctrl+W)
-await testdriver.pressKeys(['ctrl', 'w']);
-
-// Refresh (F5 or Ctrl+R)
-await testdriver.pressKeys(['f5']);
-await testdriver.pressKeys(['ctrl', 'r']);
-```
-
-### System Shortcuts
-
-```javascript
-// Alt+Tab (Windows - switch apps)
-await testdriver.pressKeys(['alt', 'tab']);
-
-// Alt+F4 (Windows - close window)
-await testdriver.pressKeys(['alt', 'f4']);
-
-// Win+D (Windows - show desktop)
-await testdriver.pressKeys(['winleft', 'd']);
-
-// Win+L (Windows - lock screen)
-await testdriver.pressKeys(['winleft', 'l']);
-
-// Cmd+Tab (macOS - switch apps)
-await testdriver.pressKeys(['command', 'tab']);
-
-// Cmd+Q (macOS - quit app)
-await testdriver.pressKeys(['command', 'q']);
+await testdriver.type('wireless headphones');
 ```
 
-### Form Submission
+### Go to a URL in Chrome
 
 ```javascript
-// Submit form
+await testdriver.pressKeys(['ctrl', 'l']);
+await testdriver.type('https://testdriver-sandbox.vercel.app/login');
 await testdriver.pressKeys(['enter']);
-
-// Cancel/Close
-await testdriver.pressKeys(['escape']);
-
-// Check checkbox
-await testdriver.pressKeys(['space']);
 ```
 
-### Text Editing
-
-```javascript
-// Delete selected text
-await testdriver.pressKeys(['delete']);
-
-// Backspace
-await testdriver.pressKeys(['backspace']);
-
-// Select all and delete
-await testdriver.pressKeys(['ctrl', 'a']);
-await testdriver.pressKeys(['delete']);
+## Complete example
 
-// Cut text
-await testdriver.pressKeys(['ctrl', 'x']);
-```
+```javascript tests/keyboard-login.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-## Best Practices
+describe('Login', () => {
+  it('submits the form from the keyboard', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-<Check>
-  **Wait after shortcuts**
-  
-  Some keyboard shortcuts trigger animations or navigation:
-  
-  ```javascript
-  await testdriver.pressKeys(['ctrl', 't']); // New tab
-  await new Promise(r => setTimeout(r, 500)); // Wait for tab
-  await testdriver.pressKeys(['ctrl', 'l']); // Focus URL bar
-  ```
-</Check>
+    // The sandbox login page shows its test password on screen
+    const password = await testdriver.extract('the password');
 
-<Check>
-  **Use Tab for form navigation**
-  
-  Tab is more reliable than clicking multiple fields:
-  
-  ```javascript
-  const firstField = await testdriver.find('email input');
-  await firstField.click();
-  await testdriver.type('user@example.com');
-  
-  await testdriver.pressKeys(['tab']);
-  await testdriver.type('password123');
-  
-  await testdriver.pressKeys(['tab']);
-  await testdriver.pressKeys(['enter']); // Submit
-  ```
-</Check>
-
-<Warning>
-  **Platform-specific keys**
-  
-  Use the appropriate modifier key for the platform:
-  - Windows/Linux: `'ctrl'`
-  - macOS: `'command'`
-  
-  ```javascript
-  // For cross-platform, you might need to detect OS
-  const modKey = process.platform === 'darwin' ? 'command' : 'ctrl';
-  await testdriver.pressKeys([modKey, 'c']); // Copy
-  ```
-</Warning>
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Form Navigation">
-    ```javascript
-    // Fill form using Tab
-    const firstField = await testdriver.find('name field');
-    await firstField.click();
-    await testdriver.type('John Doe');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('john@example.com');
-    
+    await testdriver.find('Username input field').click();
+    await testdriver.type('standard_user');
     await testdriver.pressKeys(['tab']);
-    await testdriver.type('555-0123');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.pressKeys(['enter']); // Submit
-    ```
-  </Accordion>
-  
-  <Accordion title="Text Manipulation">
-    ```javascript
-    const textArea = await testdriver.find('comment textarea');
-    await textArea.click();
-    
-    // Select all existing text
-    await testdriver.pressKeys(['ctrl', 'a']);
-    
-    // Copy it
-    await testdriver.pressKeys(['ctrl', 'c']);
-    
-    // Type new text
-    await testdriver.type('New comment');
-    
-    // Undo if needed
-    await testdriver.pressKeys(['ctrl', 'z']);
-    ```
-  </Accordion>
-  
-  <Accordion title="Browser Navigation">
-    ```javascript
-    // Open new tab
-    await testdriver.pressKeys(['ctrl', 't']);
-    await new Promise(r => setTimeout(r, 500));
-    
-    // Focus address bar
-    await testdriver.pressKeys(['ctrl', 'l']);
-    await testdriver.type('https://example.com');
+    await testdriver.type(password, { secret: true });
     await testdriver.pressKeys(['enter']);
-    
-    // Refresh page
-    await testdriver.pressKeys(['f5']);
-    
-    // Close tab
-    await testdriver.pressKeys(['ctrl', 'w']);
-    ```
-  </Accordion>
-  
-  <Accordion title="Application Shortcuts">
-    ```javascript
-    // Save document
-    await testdriver.pressKeys(['ctrl', 's']);
-    
-    // Print
-    await testdriver.pressKeys(['ctrl', 'p']);
-    
-    // Find in page
-    await testdriver.pressKeys(['ctrl', 'f']);
-    await testdriver.type('search term');
-    await testdriver.pressKeys(['escape']); // Close find
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Complete Example
 
-```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('Keyboard Navigation', () => {
-  let testdriver;
-
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
-
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
-
-  it('should navigate form with keyboard', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Find first field
-    const emailField = await testdriver.find('email input');
-    await emailField.click();
-    await testdriver.type('user@example.com');
-    
-    // Tab through fields
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('John');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('Doe');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('password123');
-    
-    // Submit with Enter
-    await testdriver.pressKeys(['tab']);
-    await testdriver.pressKeys(['enter']);
-    
-    await testdriver.assert('form submitted successfully');
-  });
-
-  it('should use keyboard shortcuts', async () => {
-    // Open new browser tab
-    await testdriver.pressKeys(['ctrl', 't']);
-    await new Promise(r => setTimeout(r, 500));
-    
-    // Focus address bar
-    await testdriver.pressKeys(['ctrl', 'l']);
-    await testdriver.type('https://example.com');
-    await testdriver.pressKeys(['enter']);
-    
-    await new Promise(r => setTimeout(r, 2000));
-    
-    // Select all page content
-    await testdriver.pressKeys(['ctrl', 'a']);
-    
-    // Copy
-    await testdriver.pressKeys(['ctrl', 'c']);
-    
-    // Refresh page
-    await testdriver.pressKeys(['f5']);
+    const result = await testdriver.assert('the product list is shown');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`type()`](/type) - Type text
-- [`click()`](/click) - Click elements
-- [`scroll()`](/scroll) - Scroll pages
+- [type()](/type): enter text into the focused field
+- [click()](/click): focus a field before you type or press keys
+- [Perform actions](/performing-actions): every kind of action in one guide