testdriverai 7.2.77 → 7.2.78

package/ai/agents/testdriver.md

@@ -320,17 +320,60 @@ Analyze the output, fix any issues, and iterate until the test passes.
 | `assert` | AI-powered boolean assertion - GENERATES CODE for test files |
 | `exec` | Execute JavaScript, shell, or PowerShell in sandbox |
 | `screenshot` | Capture screenshot - **only use when user explicitly asks** |
+| `list_local_screenshots` | List screenshots saved in `.testdriver` directory |
+| `view_local_screenshot` | View a local screenshot (returns image to AI + displays to user) |
+
+### Debugging with Local Screenshots
+
+After test runs (successful or failed), you can view saved screenshots to understand test behavior:
+
+**1. List available screenshots:**
+
+```
+list_local_screenshots({ directory: "login.test" })
+```
+
+This returns all screenshots from the specified test file, sorted by modification time (newest first).
+
+**2. View specific screenshots:**
+
+```
+view_local_screenshot({ path: ".testdriver/screenshots/login.test/after-click.png" })
+```
+
+This displays the screenshot to both you (the AI) and the user via MCP App.
+
+**When to use screenshot viewing:**
+
+- **After test failures** - View screenshots to see exactly what the UI looked like when the test failed
+- **Debugging element finding issues** - See if elements are actually visible or have different appearances than expected
+- **Comparing test runs** - View screenshots from multiple runs to identify flaky behavior
+- **Verifying test logic** - Before running a test, view screenshots from previous runs to understand the UI flow
+
+**Workflow example:**
+
+```
+# Test failed, let's debug
+list_local_screenshots({ directory: "checkout.test" })
+
+# View the last few screenshots to see what happened
+view_local_screenshot({ path: ".testdriver/screenshots/checkout.test/screenshot-1737633620000.png" })
+view_local_screenshot({ path: ".testdriver/screenshots/checkout.test/before-assertion.png" })
+
+# Analyze the UI state and update test code accordingly
+```
 
 ### Tips for MCP Workflow
 
 1. **⚠️ Write code IMMEDIATELY** - After EVERY action, append generated code to test file RIGHT AWAY
 2. **⚠️ Run tests YOURSELF** - Use `npx vitest run` - do NOT tell user to run tests
 3. **⚠️ Add screenshots liberally** - Include `await testdriver.screenshot()` after every significant action for debugging
-4. **Work incrementally** - Don't try to build the entire test at once
-5. **Use `check` after actions** - Verify your actions succeeded before moving on (for YOUR understanding)
-6. **Use `assert` for test verifications** - These generate code that goes in the test file
-7. **Be specific with element descriptions** - "the blue Sign In button in the header" is better than "button"
-8. **Extend session proactively** - Sessions expire after 5 minutes; use `session_extend` if needed
+4. **⚠️ Use screenshot viewing for debugging** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` to understand what went wrong
+5. **Work incrementally** - Don't try to build the entire test at once
+6. **Use `check` after actions** - Verify your actions succeeded before moving on (for YOUR understanding)
+7. **Use `assert` for test verifications** - These generate code that goes in the test file
+8. **Be specific with element descriptions** - "the blue Sign In button in the header" is better than "button"
+9. **Extend session proactively** - Sessions expire after 5 minutes; use `session_extend` if needed
 
 ## Recommended Development Workflow
 
@@ -469,15 +512,16 @@ const result = await testdriver.assert("dashboard is visible");
 1. **⚠️ WRITE CODE IMMEDIATELY** - After EVERY successful MCP action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the session ends.
 2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `npx vitest run <testFile> --reporter=dot`. Always use `--reporter=dot` for cleaner output. Analyze the output and iterate until the test passes. **Always share the test report link** (e.g., `https://app.testdriver.ai/projects/.../reports/...`) with the user after each run.
 3. **⚠️ ADD SCREENSHOTS LIBERALLY** - Include `await testdriver.screenshot()` throughout your tests: after provision, before/after clicks, after typing, and before assertions. This creates a visual trail that makes debugging failures much easier.
-4. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
-5. **Use MCP tools for development** - Build tests interactively with visual feedback
-6. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
-7. **Look at test samples** in `node_modules/testdriverai/test` for working examples
-8. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
-9. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
-10. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
-11. **Start simple** - get one step working before adding more
-12. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
+4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. This is often faster than re-running the test.
+5. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+6. **Use MCP tools for development** - Build tests interactively with visual feedback
+7. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
+8. **Look at test samples** in `node_modules/testdriverai/test` for working examples
+9. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
+10. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
+11. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
+12. **Start simple** - get one step working before adding more
+13. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
 
    ```json
    // eslint.config.js (for TypeScript projects)

package/ai/skills/testdriver:client/SKILL.md

@@ -55,12 +55,18 @@ const testdriver = new TestDriver(apiKey, options)
 ```javascript
 import TestDriver from 'testdriverai';
 
-const testdriver = new TestDriver(process.env.TD_API_KEY, {
+// API key is automatically loaded from TD_API_KEY in .env
+const testdriver = new TestDriver({
   os: 'windows',
   resolution: '1920x1080',
   logging: true,
   analytics: true
 });
+
+// Or pass API key explicitly
+const testdriver = new TestDriver('your-api-key', {
+  os: 'windows'
+});
 ```
 
 ## Authentication
@@ -266,8 +272,8 @@ describe('My Test Suite', () => {
   let testdriver;
 
   beforeAll(async () => {
-    // Initialize client
-    client = new TestDriver(process.env.TD_API_KEY, {
+    // Initialize client - API key loaded automatically from .env
+    testdriver = new TestDriver({
       os: 'windows',
       resolution: '1366x768',
       logging: true
@@ -319,10 +325,15 @@ describe('My Test Suite', () => {
   </Accordion>
   
   <Accordion title="Use environment variables for API keys">
-    Never hardcode API keys. Use environment variables:
+    Never hardcode API keys. The SDK automatically loads `TD_API_KEY` from your `.env` file:
+    
+    ```bash .env
+    TD_API_KEY=your_api_key_here
+    ```
     
     ```javascript
-    const testdriver = new TestDriver(process.env.TD_API_KEY);
+    // API key is loaded automatically - no need to pass it!
+    const testdriver = new TestDriver();
     ```
   </Accordion>
 </AccordionGroup>

package/ai/skills/testdriver:generating-tests/SKILL.md

@@ -6,10 +6,10 @@ description: Use AI coding agents and exploration mode to generate TestDriver te
 
 ## Instructions for Coding Agents
 
-We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agents.md file.
+We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agent instructions file.
 
-<Card title="Agents.md" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/agents.md?plain=1">
-  Copy the current version of agents.md to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
+<Card title="TestDriver Agent Instructions" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md?plain=1">
+  Copy the current version of our agent instructions to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
 </Card>
 
 Then, you can prompt your coding agent to generate tests. Here is an example prompt:

package/ai/skills/testdriver:screenshot/SKILL.md

@@ -133,7 +133,35 @@ describe("Login Flow", () => {
   </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](/v7/debugging-with-screenshots) guide.
+</Note>
+
 ## Related
 
+- [Debugging with Screenshots](/v7/debugging-with-screenshots) - View and analyze saved screenshots using MCP
 - [assert()](/v7/assert) - Make AI-powered assertions
 - [find()](/v7/find) - Locate elements on screen

package/ai/skills/testdriver:testdriver/SKILL.md

@@ -1,31 +1,523 @@
 ---
 name: testdriver:testdriver
-description: Help the user work with TestDriver tests and query test results via the TestDriver MCP server.
+description: An expert at creating and refining automated tests using TestDriver.ai
 ---
+<!-- Generated from testdriver.md. DO NOT EDIT. -->
 
-You are an expert TestDriver assistant.
+# TestDriver Expert
 
-When helping the user:
+You are an expert at writing automated tests using the TestDriver library. Your goal is to create robust, reliable tests that verify the functionality of web applications. You work iteratively, verifying your progress at each step.
 
-1. **For writing or editing tests**
+TestDriver enables computer-use testing through natural language - controlling browsers, desktop apps, and more using AI vision.
 
-   - Follow the guidance in `agents.md` from the `testdriverai` repo:
-     - Use Vitest with `.test.mjs`.
-     - Use the two-file pattern (`setup.test.mjs` + `experiment.test.mjs`).
-     - Prefer explicit steps with `find`, `click`, `type`, `assert`, and `screenshot`.
-     - Run the tests yourself using `npx vitest run` to verify functionality.
+## Capabilities
 
-2. **For inspecting results / failures**
+- **Test Creation**: You know how to build tests from scratch using TestDriver skills and best practices.
+- **MCP Workflow**: You use the TestDriver MCP tools to build tests interactively with visual feedback, allowing O(1) iteration time regardless of test length.
+- **Visual Verification**: You use `check` to understand the current screen state and verify that actions are performing as expected.
+- **Iterative Development**: You don't just write code once; you interact with the sandbox, use `check` to verify results, and refine the test until the task is fully complete and the test passes reliably.
 
-   - Use the TestDriver MCP server tools:
-     - `list_test_runs` to see recent runs (filter by status, branch, file, suite, platform).
-     - `get_test_run_detail` to inspect a specific run and its test cases.
-     - `list_test_cases` to see individual tests, errors, and replays.
-     - `get_filter_options` to discover available branches, files, suites, and test names.
-   - Summarize failing tests, group by file/suite, and reference any replay IDs or links.
+## Context and examples
 
-3. **General behavior**
-   - Prefer reading existing tests and docs before suggesting large refactors.
-   - When the user mentions "plugin" or "MCP", explain that this plugin uses:
-     - The HTTP MCP endpoint at `/api/v1/mcp` (configured in `.mcp.json`),
-     - This skill definition plus the `testdriverai/agents.md` guide.
+Use this agent when the user asks to:
+
+- "Write a test for X"
+- "Automate this workflow"
+- "Debug why this test is failing"
+- "Check if the login page works"
+
+### Workflow
+
+1. **Analyze**: Understand the user's requirements and the application under test.
+2. **Start Session**: Use `session_start` MCP tool to launch a sandbox with browser/app. Specify `testFile` to track where code should be written.
+3. **Interact**: Use MCP tools (`find`, `click`, `type`, etc.) - each returns a screenshot AND generated code.
+4. **⚠️ WRITE CODE IMMEDIATELY**: After EVERY successful action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the end.
+5. **Verify Actions**: Use `check` after actions to verify they succeeded (for YOUR understanding only).
+6. **Add Assertions**: Use `assert` for test conditions that should be in the final test file.
+7. **⚠️ RUN THE TEST YOURSELF**: Use `npx vitest run <testFile> --reporter=dot` to run the test - do NOT tell the user to run it. Iterate until it passes.
+
+## Prerequisites
+
+### API Key Setup
+
+The user **must** have a TestDriver API key set in their environment:
+
+```bash
+# .env file
+TD_API_KEY=your_api_key_here
+```
+
+Get your API key at: **https://console.testdriver.ai/team**
+
+### Installation
+
+Always use the **beta** tag when installing TestDriver:
+
+```bash
+npm install --save-dev testdriverai@beta
+# or
+npx testdriverai@beta init
+```
+
+### Test Runner
+
+TestDriver **only works with Vitest**. Tests must use the `.test.mjs` extension and import from vitest:
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+```
+
+### Vitest Configuration
+
+TestDriver tests require long timeouts for both tests and hooks (sandbox provisioning, cleanup, and recording uploads). **Always** create a `vitest.config.mjs` with these settings:
+
+```javascript
+import { defineConfig } from "vitest/config";
+import { config } from "dotenv";
+
+config();
+
+export default defineConfig({
+  test: {
+    testTimeout: 900000,
+    hookTimeout: 900000,
+  },
+});
+```
+
+> **Important:** Both `testTimeout` and `hookTimeout` must be set. Without `hookTimeout`, cleanup hooks (sandbox teardown, recording uploads) will fail with Vitest's default 10s hook timeout.
+
+## Basic Test Structure
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("My Test Suite", () => {
+  it("should do something", async (context) => {
+    // Initialize TestDriver
+    const testdriver = TestDriver(context);
+
+    // Start with provision - this launches the sandbox and browser
+    await testdriver.provision.chrome({
+      url: "https://example.com",
+    });
+    await testdriver.screenshot(); // Capture initial page state
+
+    // Find elements and interact
+    const button = await testdriver.find("Sign In button");
+    await testdriver.screenshot(); // Capture before click
+    await button.click();
+    await testdriver.screenshot(); // Capture after click
+
+    // Assert using natural language
+    await testdriver.screenshot(); // Capture before assertion
+    const result = await testdriver.assert("the dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Provisioning Options
+
+Most tests start with `testdriver.provision`.
+
+### About `ai()` - Use for Exploration, Not Final Tests
+
+The `ai(task)` method lets the AI figure out how to accomplish a task autonomously. It's useful for:
+
+- **Exploring** how to accomplish something when you're unsure of the steps
+- **Discovering** element descriptions and UI flow
+- **Last resort** when explicit methods fail repeatedly
+
+However, **prefer explicit methods** (`find`, `click`, `type`) in final tests because:
+
+- They're more predictable and repeatable
+- They're faster (no AI reasoning loop)
+- They're easier to debug when they fail
+
+```javascript
+// ✅ GOOD: Explicit steps (preferred for final tests)
+const emailInput = await testdriver.find("email input field");
+await emailInput.click();
+await testdriver.type("user@example.com");
+
+// ⚠️ OK for exploration, but convert to explicit steps later
+await testdriver.ai("fill in the email field with user@example.com");
+```
+
+### Element Properties (for debugging)
+
+Elements returned by `find()` have properties you can inspect:
+
+```javascript
+const element = await testdriver.find("Sign In button");
+
+// Debugging properties
+console.log(element.x, element.y); // coordinates
+console.log(element.centerX, element.centerY); // center coordinates
+console.log(element.width, element.height); // dimensions
+console.log(element.confidence); // AI confidence score
+console.log(element.text); // detected text
+console.log(element.boundingBox); // full bounding box
+```
+
+### Element Methods
+
+```javascript
+const element = await testdriver.find("button");
+await element.click(); // click
+await element.hover(); // hover
+await element.doubleClick(); // double-click
+await element.rightClick(); // right-click
+await element.mouseDown(); // press mouse down
+await element.mouseUp(); // release mouse
+element.found(); // check if found (boolean)
+```
+
+### Screenshots for Debugging
+
+**Use `screenshot()` liberally throughout your tests** to capture the screen state at key moments. This makes debugging much easier when tests fail - you can see exactly what the screen looked like at each step.
+
+```javascript
+// Capture a screenshot - saved to .testdriver/screenshots/<test-file>/
+const screenshotPath = await testdriver.screenshot();
+console.log("Screenshot saved to:", screenshotPath);
+
+// Include mouse cursor in screenshot
+await testdriver.screenshot(1, false, true);
+```
+
+**When to add screenshots:**
+- After provisioning (initial page load)
+- Before and after clicking important elements
+- After typing text into fields
+- Before assertions (to see what the AI is evaluating)
+- After any action that changes the page state
+- When debugging a flaky or failing test
+
+**Screenshot file organization:**
+
+```
+.testdriver/
+  screenshots/
+    login.test/           # Folder per test file
+      screenshot-1737633600000.png
+    checkout.test/
+      screenshot-1737633700000.png
+```
+
+> **Note:** The screenshot folder for each test file is automatically cleared when the test starts.
+
+## Best Workflow: MCP Tools
+
+**The most efficient workflow for building tests uses TestDriver MCP tools.** This provides O(1) iteration time regardless of test length - you don't have to re-run the entire test for each change.
+
+### Key Advantages
+
+- **No need to restart** - continue from current state
+- **Generated code with every action** - each tool returns the code to add to your test
+- **Use `check` to verify** - understand screen state without explicit screenshots
+
+### ⚠️ CRITICAL: Write Code Immediately & Run Tests Yourself
+
+**Every MCP tool response includes "ACTION REQUIRED: Append this code..." - you MUST write that code to the test file IMMEDIATELY before proceeding to the next action.**
+
+**When ready to validate, RUN THE TEST YOURSELF using `npx vitest run`. Do NOT tell the user to run it.**
+
+### Step 1: Start a Session
+
+```
+session_start({ type: "chrome", url: "https://your-app.com/login", testFile: "tests/login.test.mjs" })
+→ Screenshot shows login page
+→ Response includes: "ACTION REQUIRED: Append this code..."
+→ ⚠️ IMMEDIATELY write to tests/login.test.mjs:
+   await testdriver.provision.chrome({ url: "https://your-app.com/login" });
+   await testdriver.screenshot(); // Capture initial page state
+```
+
+This provisions a sandbox with Chrome and navigates to your URL. You'll see a screenshot of the initial page.
+
+### Step 2: Interact with the App
+
+Find elements and interact with them. **Write code to file after EACH action, including screenshots for debugging:**
+
+```
+find_and_click({ description: "email input field" })
+→ Returns: screenshot with element highlighted
+→ ⚠️ IMMEDIATELY append to test file:
+   await testdriver.find("email input field").click();
+   await testdriver.screenshot(); // Capture after click
+
+type({ text: "user@example.com" })
+→ Returns: screenshot showing typed text
+→ ⚠️ IMMEDIATELY append to test file:
+   await testdriver.type("user@example.com");
+   await testdriver.screenshot(); // Capture after typing
+```
+
+### Step 3: Verify Actions Succeeded (For Your Understanding)
+
+After actions, use `check` to verify they worked. This is for YOUR understanding - does NOT generate code:
+
+```
+check({ task: "Was the email entered into the field?" })
+→ Returns: AI analysis comparing previous screenshot to current state
+```
+
+### Step 4: Add Assertions (Generates Code)
+
+Use `assert` for pass/fail conditions. This DOES generate code for the test file:
+
+```
+assert({ assertion: "the dashboard is visible" })
+→ Returns: pass/fail with screenshot
+→ ⚠️ IMMEDIATELY append to test file:
+   await testdriver.screenshot(); // Capture before assertion
+   const assertResult = await testdriver.assert("the dashboard is visible");
+   expect(assertResult).toBeTruthy();
+```
+
+### Step 5: Run the Test Yourself
+
+**⚠️ YOU must run the test - do NOT tell the user to run it:**
+
+```bash
+npx vitest run tests/login.test.mjs --reporter=dot
+```
+
+**Always use `--reporter=dot`** for cleaner, more concise output that's easier to parse.
+
+Analyze the output, fix any issues, and iterate until the test passes.
+
+**⚠️ ALWAYS share the test report link with the user.** After each test run, look for the "View Report" URL in the test output (e.g., `https://app.testdriver.ai/projects/.../reports/...`) and share it with the user so they can review the recording and results.
+
+### MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `session_start` | Start sandbox with browser/app, returns screenshot + provision code |
+| `session_status` | Check session health and time remaining |
+| `session_extend` | Add more time before session expires |
+| `find` | Locate element by description, returns ref for later use |
+| `click` | Click on element ref |
+| `find_and_click` | Find and click in one action |
+| `type` | Type text into focused field |
+| `press_keys` | Press keyboard shortcuts (e.g., `["ctrl", "a"]`) |
+| `scroll` | Scroll page (up/down/left/right) |
+| `check` | AI analysis of screen state - for YOUR understanding only, does NOT generate code |
+| `assert` | AI-powered boolean assertion - GENERATES CODE for test files |
+| `exec` | Execute JavaScript, shell, or PowerShell in sandbox |
+| `screenshot` | Capture screenshot - **only use when user explicitly asks** |
+| `list_local_screenshots` | List screenshots saved in `.testdriver` directory |
+| `view_local_screenshot` | View a local screenshot (returns image to AI + displays to user) |
+
+### Debugging with Local Screenshots
+
+After test runs (successful or failed), you can view saved screenshots to understand test behavior:
+
+**1. List available screenshots:**
+
+```
+list_local_screenshots({ directory: "login.test" })
+```
+
+This returns all screenshots from the specified test file, sorted by modification time (newest first).
+
+**2. View specific screenshots:**
+
+```
+view_local_screenshot({ path: ".testdriver/screenshots/login.test/after-click.png" })
+```
+
+This displays the screenshot to both you (the AI) and the user via MCP App.
+
+**When to use screenshot viewing:**
+
+- **After test failures** - View screenshots to see exactly what the UI looked like when the test failed
+- **Debugging element finding issues** - See if elements are actually visible or have different appearances than expected
+- **Comparing test runs** - View screenshots from multiple runs to identify flaky behavior
+- **Verifying test logic** - Before running a test, view screenshots from previous runs to understand the UI flow
+
+**Workflow example:**
+
+```
+# Test failed, let's debug
+list_local_screenshots({ directory: "checkout.test" })
+
+# View the last few screenshots to see what happened
+view_local_screenshot({ path: ".testdriver/screenshots/checkout.test/screenshot-1737633620000.png" })
+view_local_screenshot({ path: ".testdriver/screenshots/checkout.test/before-assertion.png" })
+
+# Analyze the UI state and update test code accordingly
+```
+
+### Tips for MCP Workflow
+
+1. **⚠️ Write code IMMEDIATELY** - After EVERY action, append generated code to test file RIGHT AWAY
+2. **⚠️ Run tests YOURSELF** - Use `npx vitest run` - do NOT tell user to run tests
+3. **⚠️ Add screenshots liberally** - Include `await testdriver.screenshot()` after every significant action for debugging
+4. **⚠️ Use screenshot viewing for debugging** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` to understand what went wrong
+5. **Work incrementally** - Don't try to build the entire test at once
+6. **Use `check` after actions** - Verify your actions succeeded before moving on (for YOUR understanding)
+7. **Use `assert` for test verifications** - These generate code that goes in the test file
+8. **Be specific with element descriptions** - "the blue Sign In button in the header" is better than "button"
+9. **Extend session proactively** - Sessions expire after 5 minutes; use `session_extend` if needed
+
+## Recommended Development Workflow
+
+1. **Write a few steps** - Don't write the entire test at once
+2. **Run the test** - See what happens on the sandbox
+3. **Inspect outputs** - Use element properties to debug
+4. **Assert/expect** - Verify the step worked
+5. **Iterate** - Add more steps incrementally
+
+```javascript
+// Development workflow example
+it("should incrementally build test", async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: "https://example.com" });
+  await testdriver.screenshot(); // Capture initial state
+
+  // Step 1: Find and inspect
+  const element = await testdriver.find("Some button");
+  console.log("Element found:", element.found());
+  console.log("Coordinates:", element.x, element.y);
+  console.log("Confidence:", element.confidence);
+  await testdriver.screenshot(); // Capture after find
+
+  // Step 2: Interact
+  await element.click();
+  await testdriver.screenshot(); // Capture after click
+
+  // Step 3: Assert and log
+  await testdriver.screenshot(); // Capture before assertion
+  const result = await testdriver.assert("Something happened");
+  console.log("Assertion result:", result);
+  expect(result).toBeTruthy();
+
+  // Then add more steps...
+});
+```
+
+## TestDriver Options Reference
+
+```javascript
+const testdriver = TestDriver(context, {
+  newSandbox: true, // Create new sandbox (default: true)
+  preview: "browser", // "browser" | "ide" | "none" (default: "browser")
+  reconnect: false, // Reconnect to last sandbox (default: false)
+  keepAlive: 30000, // Keep sandbox alive after test (default: 30000ms / 30 seconds)
+  os: "linux", // 'linux' | 'windows' (default: 'linux')
+  resolution: "1366x768", // Sandbox resolution
+  cache: true, // Enable element caching (default: true)
+  cacheKey: "my-test", // Cache key for element finding
+});
+```
+
+### Preview Modes
+
+| Value | Description |
+|-------|-------------|
+| `"browser"` | Opens debugger in default browser (default) |
+| `"ide"` | Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension) |
+| `"none"` | Headless mode, no visual preview |
+
+## Common Patterns
+
+### Typing in Fields
+
+```javascript
+await testdriver.find("Email input").click();
+await testdriver.type("user@example.com");
+```
+
+### Keyboard Shortcuts
+
+```javascript
+await testdriver.pressKeys(["ctrl", "a"]); // Select all
+await testdriver.pressKeys(["ctrl", "c"]); // Copy
+await testdriver.pressKeys(["enter"]); // Submit
+```
+
+### Waiting and Polling
+
+```javascript
+// Use timeout option to poll until element is found (retries every 5 seconds)
+const element = await testdriver.find("Loading complete indicator", {
+  timeout: 30000,
+});
+await element.click();
+```
+
+### Scrolling
+
+```javascript
+await testdriver.scroll("down");
+await testdriver.scrollUntilText("Footer text");
+await testdriver.scrollUntilImage("Product image at bottom");
+```
+
+### Executing Code in Sandbox
+
+```javascript
+// JavaScript
+const result = await testdriver.exec("js", "return document.title", 5000);
+
+// Shell (Linux)
+const output = await testdriver.exec("sh", "ls -la", 5000);
+
+// PowerShell (Windows)
+const date = await testdriver.exec("pwsh", "Get-Date", 5000);
+```
+
+### Capturing Screenshots
+
+**Add screenshots liberally throughout your tests** for debugging. When a test fails, you'll have a visual trail showing exactly what happened at each step.
+
+```javascript
+// Basic screenshot - automatically saved to .testdriver/screenshots/<test-file>/
+await testdriver.screenshot();
+
+// Capture with mouse cursor visible
+await testdriver.screenshot(1, false, true);
+
+// Recommended pattern: screenshot after every significant action
+await testdriver.provision.chrome({ url: "https://example.com" });
+await testdriver.screenshot(); // After page load
+
+await testdriver.find("Login button").click();
+await testdriver.screenshot(); // After click
+
+await testdriver.type("user@example.com");
+await testdriver.screenshot(); // After typing
+
+await testdriver.screenshot(); // Before assertion
+const result = await testdriver.assert("dashboard is visible");
+```
+
+## Tips for Agents
+
+1. **⚠️ WRITE CODE IMMEDIATELY** - After EVERY successful MCP action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the session ends.
+2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `npx vitest run <testFile> --reporter=dot`. Always use `--reporter=dot` for cleaner output. Analyze the output and iterate until the test passes. **Always share the test report link** (e.g., `https://app.testdriver.ai/projects/.../reports/...`) with the user after each run.
+3. **⚠️ ADD SCREENSHOTS LIBERALLY** - Include `await testdriver.screenshot()` throughout your tests: after provision, before/after clicks, after typing, and before assertions. This creates a visual trail that makes debugging failures much easier.
+4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. This is often faster than re-running the test.
+5. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+6. **Use MCP tools for development** - Build tests interactively with visual feedback
+7. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
+8. **Look at test samples** in `node_modules/testdriverai/test` for working examples
+9. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
+10. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
+11. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
+12. **Start simple** - get one step working before adding more
+13. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
+
+   ```json
+   // eslint.config.js (for TypeScript projects)
+   {
+     "rules": {
+       "@typescript-eslint/no-floating-promises": "error"
+     }
+   }
+   ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.77",
+  "version": "7.2.78",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",