@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/screenshot.mdx

@@ -1,249 +1,95 @@
 ---
 title: "screenshot()"
 sidebarTitle: "screenshot"
-description: "Capture and save screenshots during test execution"
+description: "Save a screenshot of the sandbox screen to a PNG file in your project."
 icon: "camera"
 ---
 
-## Overview
+Save what the sandbox screen shows right now as a PNG file. Use it to record a checkpoint you want to look at later.
 
-Capture a screenshot of the screen. TestDriver saves it to a local file automatically. TestDriver groups the screenshots by test file. This makes debug and review easy.
+```javascript
+const screenshotPath = await testdriver.screenshot('cart-before-checkout');
+```
 
-<Note>
-  **Automatic Screenshots**: TestDriver can capture screenshots automatically before and after each command (click, type, find, and more). It saves them with clear filenames such as `001-click-before-L42-submit-button.png`. The filename includes the line number from your test file. Enable this with `autoScreenshots: true` in your TestDriver options.
-</Note>
+To capture every step without calling it yourself, turn on `autoScreenshots` instead. See [Screenshots](/screenshots).
 
-## Syntax
+## Signature
 
-```javascript
-const filePath = await testdriver.screenshot(filename)
+```typescript
+testdriver.screenshot(filename?: string): Promise<string>
 ```
 
 ## Parameters
 
-<ParamField path="filename" type="string" optional>
-  A custom filename for the screenshot (without the .png extension). If you do not give one, TestDriver makes a filename from the timestamp automatically.
+<ParamField path="filename" type="string">
+  The file name. TestDriver adds `.png` if it's missing. Without it, the file is named `screenshot-<timestamp>.png`.
 </ParamField>
 
 ## Returns
 
-`Promise<string>` - The absolute file path where TestDriver saved the screenshot
+`Promise<string>`. The absolute path of the saved file.
 
-## File Organization
+## Where files are saved
 
-TestDriver saves screenshots automatically to `.testdriver/screenshots/<test-file-name>/` in your project root:
+Screenshots go to `.testdriver/screenshots/<test file>/` in the directory you run tests from. `<test file>` is the test file's name without its last extension, so `tests/login.test.mjs` saves to `.testdriver/screenshots/login.test/`.
 
-```
-.testdriver/
-  screenshots/
-    login.test/
-      001-find-before-L15-email-input.png     # Auto: before find()
-      002-find-after-L15-email-input.png      # Auto: after find()
-      003-click-before-L16-email-input.png    # Auto: before click()
-      004-click-after-L16-email-input.png     # Auto: after click()
-      005-type-before-L17-userexamplecom.png  # Auto: before type()
-      006-type-after-L17-userexamplecom.png   # Auto: after type()
-      custom-screenshot.png                    # Manual: screenshot("custom-screenshot")
-    checkout.test/
-      001-find-before-L12-checkout-button.png
-      ...
+```text
+.testdriver/screenshots/login.test/
+  cart-before-checkout.png
+  screenshot-1729512345678.png
 ```
 
-### Automatic Screenshot Naming
+<Warning>
+  TestDriver clears each test file's folder at the start of every run. Copy any screenshot you want to keep.
+</Warning>
 
-When `autoScreenshots` is enabled, filenames follow this format:
+Add the folder to `.gitignore`:
 
-`<seq>-<action>-<phase>-L<line>-<description>.png`
-
-| Component | Description | Example |
-|-----------|-------------|---------|
-| `seq` | Sequential number (001, 002, ...) | `001` |
-| `action` | Command name | `click`, `type`, `find` |
-| `phase` | Before, after, or error | `before`, `after` |
-| `L<line>` | Line number from test file | `L42` |
-| `description` | Element description or action target | `submit-button` |
-
-<Note>
-  The screenshot folder for each test file is automatically cleared when the test starts. This ensures you only see screenshots from the most recent test run.
-</Note>
+```text .gitignore
+.testdriver/screenshots/
+```
 
 ## Examples
 
-### Basic Screenshot
+### Save a named checkpoint
 
 ```javascript
-// Capture a screenshot with auto-generated filename
-const screenshotPath = await testdriver.screenshot();
-console.log('Screenshot saved to:', screenshotPath);
+await testdriver.find('Checkout button').click();
+await testdriver.screenshot('checkout-page');
 ```
 
-### Custom Filename
+### Log the path
 
 ```javascript
-// Save with a descriptive filename
-await testdriver.screenshot("login-page");
-// Saves to: .testdriver/screenshots/<test>/login-page.png
-
-await testdriver.screenshot("after-click");
-// Saves to: .testdriver/screenshots/<test>/after-click.png
+const screenshotPath = await testdriver.screenshot();
+console.log(screenshotPath);
+// /Users/you/my-app/.testdriver/screenshots/login.test/screenshot-1729512345678.png
 ```
 
-### Debugging with Screenshots
+## Complete example
 
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+```javascript tests/login.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-describe("Login Flow", () => {
-  it("should log in successfully", async (context) => {
+describe('Login', () => {
+  it('shows an error for an empty form', async (context) => {
     const testdriver = TestDriver(context);
-    
-    await testdriver.provision.chrome({
-      url: 'https://myapp.com/login',
-    });
-
-    // Capture initial state
-    await testdriver.screenshot();
-
-    // Fill in login form
-    const emailInput = await testdriver.find("email input");
-    await emailInput.click();
-    await testdriver.type("user@example.com");
-
-    // Capture state after typing
-    await testdriver.screenshot();
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-    const passwordInput = await testdriver.find("password input");
-    await passwordInput.click();
-    await testdriver.type("password123");
+    await testdriver.screenshot('login-empty');
 
-    // Capture before clicking login
-    await testdriver.screenshot();
+    await testdriver.find('Sign in button below the password field').click();
+    await testdriver.screenshot('login-error');
 
-    const loginButton = await testdriver.find("Login button");
-    await loginButton.click();
-
-    // Capture after login attempt
-    await testdriver.screenshot();
-
-    const result = await testdriver.assert("dashboard is visible");
-    expect(result).toBeTruthy();
+    const result = await testdriver.assert('an error says the fields are required');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Automatic Screenshots
-
-By default, TestDriver captures screenshots **automatically** before and after every command. This creates a complete visual timeline of your test execution without any additional code.
-
-### Enabling/Disabling
-
-```javascript
-// Auto-screenshots enabled by default
-const testdriver = TestDriver(context);
-
-// Explicitly disable if needed (not recommended)
-const testdriver = TestDriver(context, {
-  autoScreenshots: false
-});
-```
-
-### What Gets Captured
-
-Automatic screenshots are taken around these commands:
-- `find()` / `findAll()`
-- `click()` / `hover()` / `doubleClick()` / `rightClick()`
-- `type()` / `pressKeys()`
-- `scroll()`
-- `waitForText()` / `waitForImage()`
-- `focusApplication()`
-- `assert()` / `extract()` / `exec()`
-
-### Example Output
-
-For this test code:
-
-```javascript
-// Line 15: Find email input
-const emailInput = await testdriver.find("email input");
-// Line 16: Click it
-await emailInput.click();
-// Line 17: Type email
-await testdriver.type("user@example.com");
-```
-
-TestDriver automatically saves:
-
-```
-001-find-before-L15-email-input.png
-002-find-after-L15-email-input.png
-003-click-before-L16-email-input.png
-004-click-after-L16-email-input.png
-005-type-before-L17-userexamplecom.png
-006-type-after-L17-userexamplecom.png
-```
-
-If an error occurs, the phase will be `error` instead of `after`.
-
-## Best Practices
-
-<AccordionGroup>
-  <Accordion title="Let automatic screenshots do the work">
-    With `autoScreenshots: true`, you get comprehensive coverage without adding manual `screenshot()` calls. Only add manual screenshots for specific named checkpoints.
-  </Accordion>
-  
-  <Accordion title="Use screenshots for debugging flaky tests">
-    When a test fails intermittently, add screenshots at key steps to capture the actual screen state. This helps identify timing issues or unexpected UI states.
-  </Accordion>
-
-  <Accordion title="Capture before assertions">
-    Take a screenshot before making assertions. If the assertion fails, you'll have a visual record of what the screen looked like.
-    
-    ```javascript
-    await testdriver.screenshot();
-    const result = await testdriver.assert("checkout button is visible");
-    ```
-  </Accordion>
-
-  <Accordion title="Add to .gitignore">
-    Add `.testdriver/screenshots/` to your `.gitignore` to avoid committing screenshots to version control:
-    
-    ```
-    # .gitignore
-    .testdriver/screenshots/
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Viewing Saved Screenshots
-
-After saving screenshots during test execution, you can view them using TestDriver MCP commands. This is especially useful for debugging failed tests or verifying test behavior.
-
-### MCP Commands for Screenshot Viewing
-
-**List all saved screenshots:**
-
-```
-list_local_screenshots()
-```
-
-**View a specific screenshot:**
-
-```
-view_local_screenshot({ path: "/full/path/to/screenshot.png" })
-```
-
-These commands allow you to:
-- View screenshots from failed tests to understand what went wrong
-- Review test execution flow by examining screenshots in chronological order
-- Compare screenshots across test runs to identify flaky behavior
-
-<Note>
-  For detailed workflows and examples of using these MCP commands for debugging, see the [Debugging with Screenshots](/debugging-with-screenshots) guide.
-</Note>
-
 ## Related
 
-- [Debugging with Screenshots](/debugging-with-screenshots) - View and analyze saved screenshots using MCP
-- [assert()](/assert) - Make AI-powered assertions
-- [find()](/find) - Locate elements on screen
+- [Screenshots](/screenshots): capture every step automatically with `autoScreenshots`
+- [Debug a failing test](/debugging-with-screenshots): view saved screenshots from your AI client
+- [Dashcam](/dashcam): watch a video replay of the whole test

package/docs/screenshots.mdx

@@ -1,186 +1,136 @@
 ---
-title: "Screenshots"
+title: "Save screenshots"
 sidebarTitle: "Screenshots"
-description: "Capture and manage screenshots during test execution"
+description: "Save screenshots of the sandbox by hand or automatically around each command."
 icon: "camera"
 mode: "wide"
 ---
 
-## Overview
+TestDriver can save screenshots of the sandbox to your machine while a test runs.
 
-TestDriver can capture screenshots by hand at any point during a test. It can also capture them automatically before and after each command. TestDriver saves the screenshots to a structured directory. This makes debug easy.
+- Call [`screenshot()`](/screenshot) to save one at a specific point.
+- Turn on `autoScreenshots` to save one before and after each command, named after the line that ran it.
 
-## Manual Screenshots
+Both kinds are saved as PNG files in `.testdriver/screenshots/<test file>/`.
 
-Use `testdriver.screenshot()` to capture the present screen:
+## Save a screenshot by hand
 
-```javascript
-const path = await testdriver.screenshot();
-console.log('Saved to:', path);
-// .testdriver/screenshots/my-test/screenshot-1719849312345.png
-```
-
-### Options
+Call `screenshot()` with an optional file name. It resolves to the absolute path of the saved file:
 
-```javascript
-await testdriver.screenshot(filename?)
-```
+```javascript tests/login.test.mjs
+import { describe, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-<ParamField path="filename" type="string">
-  A custom filename for the screenshot. TestDriver adds `.png` automatically if it is not there. If you do not give this, the default is `screenshot-<timestamp>.png`.
-</ParamField>
+describe('Login', () => {
+  it('loads the login page', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-**Returns:** `Promise<string>` — the absolute file path of the saved screenshot.
-
-```javascript
-// Default filename
-await testdriver.screenshot();
-// → .testdriver/screenshots/my-test/screenshot-1719849312345.png
+    const filePath = await testdriver.screenshot('login-page');
+    console.log(filePath);
+    // /path/to/project/.testdriver/screenshots/login.test/login-page.png
+  });
+});
+```
 
-// Custom filename
-await testdriver.screenshot('login-page');
-// → .testdriver/screenshots/my-test/login-page.png
+- TestDriver adds `.png` if the name doesn't end with it.
+- Without a name, the file is called `screenshot-<timestamp>.png`.
 
-// With .png extension
-await testdriver.screenshot('dashboard-loaded.png');
-// → .testdriver/screenshots/my-test/dashboard-loaded.png
-```
+See [screenshot()](/screenshot) for the full reference.
 
-## Auto Screenshots
+## Save screenshots automatically
 
-Enable automatic screenshots before and after every command:
+Set `autoScreenshots: true` when you create the client:
 
 ```javascript
-const testdriver = new TestDriver({
-  autoScreenshots: true,
-});
+const testdriver = TestDriver(context, { autoScreenshots: true });
 ```
 
-<ParamField path="autoScreenshots" type="boolean" default={false}>
-  When `true`, captures a screenshot before and after every SDK command (`click`, `type`, `find`, `scroll`, `hover`, `pressKeys`, `assert`, `exec`, etc.). On error, an error-phase screenshot replaces the after-phase screenshot.
-</ParamField>
-
-### Filename Format
-
-Auto-screenshots follow this naming convention:
-
-```
-<seq>-<action>-<phase>-L<line>-<description>.png
-```
+TestDriver then saves a screenshot before each command and another after it. When a command fails, it saves an `error` screenshot instead of the `after` one. A failed screenshot never fails the command.
 
-| Part | Description | Example |
-|---|---|---|
-| `seq` | 3-digit zero-padded sequence number | `001` |
-| `action` | Command name | `click`, `type`, `find` |
-| `phase` | `before`, `after`, or `error` | `before` |
-| `L<line>` | Source line number from your test file | `L42` |
-| `description` | Sanitized from command arguments (max 30 chars) | `submit-button` |
+Automatic screenshots are off by default because each one is an extra capture from the sandbox.
 
-**Examples:**
-```
-001-find-before-L15-login-button.png
-002-find-after-L15-login-button.png
-003-click-before-L16-login-button.png
-004-click-after-L16-login-button.png
-005-type-before-L18-username-field.png
-006-type-error-L18-username-field.png
-```
+### Which commands are captured
 
-### Phases
+- `find()` and `findAll()`.
+- Methods you call on the client, such as `testdriver.click()`, `type()`, `pressKeys()`, `scroll()`, `hover()`, `wait()`, `assert()`, `extract()`, `exec()`, and `focusApplication()`.
 
-| Phase | When | Description |
-|---|---|---|
-| `before` | Before command executes | Captures the screen state before the action |
-| `after` | After successful command | Captures the result of the action |
-| `error` | After failed command | Captures the screen at the point of failure (replaces `after`) |
+<Note>
+  Methods you call on an element, such as `element.click()` or `element.hover()`, aren't captured. The `find()` that returned the element is.
+</Note>
 
-## Screenshot Directory
+### File names
 
-Screenshots are saved to:
+Each automatic screenshot is named:
 
-```
-<cwd>/.testdriver/screenshots/<testFileName>/
+```text
+<sequence>-<command>-<phase>-L<line>-<description>.png
 ```
 
-Where `<testFileName>` is the test file name without its extension. For example, a test at `tests/login.test.mjs` saves screenshots to `.testdriver/screenshots/login.test/`.
+| Part | Meaning | Example |
+| --- | --- | --- |
+| `sequence` | Three-digit counter, in the order screenshots were taken | `001` |
+| `command` | The method that ran | `find`, `type`, `assert` |
+| `phase` | `before`, `after`, or `error` | `before` |
+| `L<line>` | The line in your test file that called the command | `L15` |
+| `description` | Taken from the command's arguments, as below | `email-input` |
 
-### Directory Cleanup
+The description comes from:
 
-The screenshot directory for each test file is **automatically cleaned** at the start of a test run. This happens once per process per test file to prevent concurrent tests from the same file from interfering with each other.
+- The description passed to `find()` or `findAll()`.
+- The first 20 characters typed by `type()`.
+- The keys passed to `pressKeys()`, joined with `+`.
+- The direction passed to `scroll()`.
+- The first 30 characters of the text passed to `assert()` or `extract()`.
 
-## Debug Screenshots
+TestDriver lowercases it, drops anything other than letters, digits, spaces, and hyphens, turns spaces into hyphens, and keeps the first 30 characters.
 
-Elements have a `saveDebugScreenshot()` method for debugging element detection:
+<Warning>
+  The description for `type()` uses the typed text even when you pass `secret: true`. Don't turn on `autoScreenshots` for tests that type passwords, or the start of the password ends up in a file name.
+</Warning>
 
-```javascript
-const el = await testdriver.find('submit button');
+### Example
 
-// Save the screenshot that was used to detect this element
-const debugPath = await el.saveDebugScreenshot();
-console.log('Debug screenshot:', debugPath);
-// → ./debug-screenshot-1719849312345.png
+This test:
 
-// Custom path
-await el.saveDebugScreenshot('./my-debug.png');
+```javascript
+await testdriver.find('Email input field').click(); // line 15
+await testdriver.type('user@example.com');          // line 16
+await testdriver.assert('the email is filled in');  // line 17
 ```
 
-This saves the screenshot that was captured during the `find()` call, which can be useful for understanding what the AI "saw" when locating the element.
+saves:
 
-## Complete Example
-
-```javascript
-import { describe, it, beforeAll, afterAll } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('Screenshot Example', () => {
-  let testdriver;
-
-  beforeAll(async () => {
-    testdriver = new TestDriver({
-      autoScreenshots: true,   // capture every step
-    });
-    await testdriver.ready();
-    await testdriver.provision.chrome({ url: 'https://example.com' });
-  });
+```text
+.testdriver/screenshots/login.test/
+  001-find-before-L15-email-input-field.png
+  002-find-after-L15-email-input-field.png
+  003-type-before-L16-userexamplecom.png
+  004-type-after-L16-userexamplecom.png
+  005-assert-before-L17-the-email-is-filled-in.png
+  006-assert-after-L17-the-email-is-filled-in.png
+```
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+## Where screenshots are saved
 
-  it('captures the login flow', async () => {
-    // Auto-screenshots capture before/after each command
+Screenshots go in a folder named after the test file, without its last extension:
 
-    // Manual screenshot for a specific moment
-    await testdriver.screenshot('initial-page-load');
+| Test file | Folder |
+| --- | --- |
+| `tests/login.test.mjs` | `.testdriver/screenshots/login.test/` |
+| `tests/checkout.spec.js` | `.testdriver/screenshots/checkout.spec/` |
 
-    const username = await testdriver.find('username input');
-    await username.click();
-    await testdriver.type('testuser@example.com');
+The `.testdriver` folder is created in the directory you run the tests from.
 
-    await testdriver.screenshot('after-username-entry');
+TestDriver deletes a test file's screenshot folder when that file's first test connects to a sandbox. Each folder only holds screenshots from the latest run. Tests in the same file running at the same time don't delete each other's screenshots.
 
-    const password = await testdriver.find('password input');
-    await password.click();
-    await testdriver.type('password123');
+## Review the screenshots
 
-    await testdriver.find('login button').click();
+Open the folder after a run, or ask your AI assistant to find and show screenshots by line number. [Debug a failing test](/debugging-with-screenshots#inspect-screenshots-with-your-ai-assistant) explains how to do that with the TestDriver MCP server.
 
-    await testdriver.screenshot('after-login-click');
-  });
-});
-```
+## Related
 
-After running, your screenshot directory will contain:
-```
-.testdriver/screenshots/login-flow.test/
-├── initial-page-load.png
-├── 001-find-before-L18-username-input.png
-├── 002-find-after-L18-username-input.png
-├── 003-click-before-L19-username-input.png
-├── 004-click-after-L19-username-input.png
-├── 005-type-before-L20-testuser-example-com.png
-├── 006-type-after-L20-testuser-example-com.png
-├── after-username-entry.png
-├── 007-find-before-L24-password-input.png
-├── ...
-```
+- [screenshot()](/screenshot): the reference for manual screenshots
+- [Debug a failing test](/debugging-with-screenshots): use replays and screenshots to find out why a test failed
+- [Dashcam](/dashcam): the video recording of each run
+- [Options](/options#preview-and-recording): every client option