@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/focus-application.mdx

@@ -1,294 +1,117 @@
 ---
 title: "focusApplication()"
 sidebarTitle: "focusApplication"
-description: "Bring an application window to the foreground"
+description: "Bring an open application window to the front of the sandbox desktop."
 icon: "window-maximize"
 ---
 
-## Overview
+Bring an app's window to the front, so your next clicks and keystrokes go to it.
 
-Move a specific application window to the front. Make it the active window for interactions.
+```javascript
+await testdriver.focusApplication('Google Chrome');
+```
 
-## Syntax
+Use it when your test works across several apps, or after a dialog or another window has taken focus.
 
-```javascript
-await testdriver.focusApplication(name)
+<Note>
+  The [`provision`](/provision) methods focus the app they launch, so you don't need this right after `provision.chrome()`, `provision.vscode()`, `provision.electron()`, or `provision.installer()`.
+</Note>
+
+## Signature
+
+```typescript
+testdriver.focusApplication(name: string, options?: object): Promise<string>
 ```
 
 ## Parameters
 
 <ParamField path="name" type="string" required>
-  The application name (for example, `'Google Chrome'`, `'Microsoft Edge'`, `'Notepad'`)
+  The app's name, as it appears in its window title. For example `'Google Chrome'`, `'Notepad'`, or `'Visual Studio Code'`.
+</ParamField>
+
+<ParamField path="options" type="object">
+  <Expandable title="properties">
+    <ParamField path="redraw" type="boolean | object">
+      Wait for the screen to settle after focusing. Uses the client's setting when you leave it out. See [Redraw](/redraw).
+    </ParamField>
+  </Expandable>
 </ParamField>
 
 ## Returns
 
-`Promise<string>` - The result message
+`Promise<string>`. Always resolves to `"The application was focused."`.
 
-## Examples
+## Errors
+
+`focusApplication()` doesn't throw when no window matches. It returns the same message either way.
 
-### Common Applications
+To confirm the right app is in front, follow it with an [`assert()`](/assert):
 
 ```javascript
-// Focus Chrome browser
-await testdriver.focusApplication('Google Chrome');
+await testdriver.focusApplication('Notepad');
+await testdriver.assert('a Notepad window is in the foreground');
+```
 
-// Focus Edge browser
-await testdriver.focusApplication('Microsoft Edge');
+## How it matches windows
 
-// Focus Notepad
-await testdriver.focusApplication('Notepad');
+- **Windows:** TestDriver looks for windows whose title contains `name`. It restores a minimized window, then brings it to the front.
+- **Linux:** TestDriver runs `jumpapp -f <name>`. If that fails, it activates the first window whose title matches `name`, using `xdotool`.
 
-// Focus File Explorer
-await testdriver.focusApplication('File Explorer');
+The app must already be running. Launch it first with [`provision`](/provision) or [`exec()`](/exec).
 
-// Focus Visual Studio Code
-await testdriver.focusApplication('Visual Studio Code');
-```
+## Examples
 
-### After Opening Applications
+### Switch between two apps
 
 ```javascript
-// Open Chrome and focus it
-await testdriver.exec('pwsh', `
-  Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "https://example.com"
-`, 5000);
+const orderNumber = await testdriver.extract('the order number');
 
-await new Promise(r => setTimeout(r, 2000)); // Wait for launch
+await testdriver.focusApplication('Notepad');
+await testdriver.type(orderNumber);
 
-// Focus the Chrome window
 await testdriver.focusApplication('Google Chrome');
+await testdriver.find('Confirm order button').click();
 ```
 
-## Best Practices
-
-<Check>
-  **Focus before UI interactions**
-  
-  Always focus the target application before interacting with its UI:
-  
-  ```javascript
-  await testdriver.focusApplication('Google Chrome');
-  
-  const button = await testdriver.find('submit button');
-  await button.click();
-  ```
-</Check>
-
-<Check>
-  **Wait after launching apps**
-  
-  Give applications time to open before focusing:
-  
-  ```javascript
-  await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
-  await new Promise(r => setTimeout(r, 1000)); // Wait for launch
-  await testdriver.focusApplication('Notepad');
-  ```
-</Check>
-
-<Check>
-  **Use exact application names**
-  
-  ```javascript
-  // ✅ Correct
-  await testdriver.focusApplication('Google Chrome');
-  
-  // ❌ May not work
-  await testdriver.focusApplication('Chrome');
-  await testdriver.focusApplication('chrome.exe');
-  ```
-</Check>
-
-<Warning>
-  **Application must be running**
-  
-  The application must already be running. `focusApplication()` won't launch applications, only bring existing windows to the foreground.
-</Warning>
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Multi-Application Testing">
-    ```javascript
-    // Test workflow across multiple apps
-    await testdriver.focusApplication('Google Chrome');
-    const data = await testdriver.extract('the order number');
-    
-    await testdriver.focusApplication('Notepad');
-    await testdriver.type(data);
-    await testdriver.pressKeys(['ctrl', 's']);
-    
-    await testdriver.focusApplication('Google Chrome');
-    const nextButton = await testdriver.find('next button');
-    await nextButton.click();
-    ```
-  </Accordion>
-  
-  <Accordion title="Browser Switching">
-    ```javascript
-    // Compare behavior in different browsers
-    await testdriver.focusApplication('Google Chrome');
-    await testdriver.assert('page loaded correctly in Chrome');
-    
-    await testdriver.focusApplication('Microsoft Edge');
-    await testdriver.assert('page loaded correctly in Edge');
-    ```
-  </Accordion>
-  
-  <Accordion title="Desktop Application Testing">
-    ```javascript
-    // Launch and focus desktop app
-    await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
-    await new Promise(r => setTimeout(r, 1000));
-    
-    await testdriver.focusApplication('Notepad');
-    await testdriver.type('Test content');
-    ```
-  </Accordion>
-  
-  <Accordion title="Window Management">
-    ```javascript
-    // Show desktop first
-    await testdriver.pressKeys(['winleft', 'd']);
-    
-    // Click desktop icon
-    const icon = await testdriver.find('Chrome icon on desktop');
-    await icon.click();
-    
-    await new Promise(r => setTimeout(r, 2000));
-    
-    // Focus the opened window
-    await testdriver.focusApplication('Google Chrome');
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Common Application Names
-
-### Browsers
-- `'Google Chrome'`
-- `'Microsoft Edge'`
-- `'Mozilla Firefox'`
-- `'Safari'` (macOS)
-
-### Office Applications
-- `'Microsoft Word'`
-- `'Microsoft Excel'`
-- `'Microsoft PowerPoint'`
-- `'Microsoft Outlook'`
-
-### Development Tools
-- `'Visual Studio Code'`
-- `'Visual Studio'`
-- `'IntelliJ IDEA'`
-- `'Sublime Text'`
-
-### System Applications
-- `'Notepad'`
-- `'File Explorer'`
-- `'Command Prompt'`
-- `'Windows PowerShell'`
-- `'Task Manager'`
-
-### Communication
-- `'Microsoft Teams'`
-- `'Slack'`
-- `'Discord'`
-- `'Zoom'`
-
-## Complete Example
+### Launch an app and focus it on Windows
 
 ```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
+await testdriver.exec({ language: 'pwsh', code: 'Start-Process notepad' });
+await testdriver.focusApplication('Notepad');
+await testdriver.type('Meeting notes');
+```
 
-describe('Multi-Application Workflow', () => {
-  let testdriver;
+### Return to the browser after a dialog
 
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
+```javascript
+await testdriver.find('Download report button').click();
+await testdriver.focusApplication('Google Chrome');
+```
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+## Complete example
+
+```javascript tests/notepad.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-  it('should work across multiple applications', async () => {
-    // Start in browser
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Get data from web page
-    const orderNumber = await testdriver.extract('the order number');
-    console.log('Order:', orderNumber);
-    
-    // Open Notepad
-    await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
-    await new Promise(r => setTimeout(r, 1500));
-    
-    // Focus Notepad and save data
+describe('Notepad', () => {
+  it('types into Notepad', async (context) => {
+    // Windows sandboxes are available on Enterprise plans
+    const testdriver = TestDriver(context, { os: 'windows' });
+
+    await testdriver.exec({ language: 'pwsh', code: 'Start-Process notepad' });
     await testdriver.focusApplication('Notepad');
-    await testdriver.type(`Order Number: ${orderNumber}`);
-    await testdriver.type('\n');
-    await testdriver.type(`Date: ${new Date().toISOString()}`);
-    
-    // Save file
-    await testdriver.pressKeys(['ctrl', 's']);
-    await new Promise(r => setTimeout(r, 500));
-    
-    await testdriver.type('C:\\order-info.txt');
-    await testdriver.pressKeys(['enter']);
-    
-    // Return to browser
-    await testdriver.focusApplication('Google Chrome');
-    
-    const confirmButton = await testdriver.find('confirm order button');
-    await confirmButton.click();
-    
-    await testdriver.assert('order confirmed');
-  });
 
-  it('should switch between browser tabs', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Open new tab
-    await testdriver.pressKeys(['ctrl', 't']);
-    await new Promise(r => setTimeout(r, 500));
-    
-    // Navigate to URL
-    await testdriver.pressKeys(['ctrl', 'l']);
-    await testdriver.type('https://example.com');
-    await testdriver.pressKeys(['enter']);
-    
-    await new Promise(r => setTimeout(r, 2000));
-    
-    // Ensure Chrome is still focused
-    await testdriver.focusApplication('Google Chrome');
-    
-    await testdriver.assert('example.com page is loaded');
-  });
+    await testdriver.type('Hello from TestDriver');
 
-  it('should handle dialog boxes', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    const deleteButton = await testdriver.find('delete account button');
-    await deleteButton.click();
-    
-    await new Promise(r => setTimeout(r, 500));
-    
-    // Dialog appears - make sure it's focused
-    await testdriver.focusApplication('Google Chrome');
-    
-    const confirmBtn = await testdriver.find('confirm deletion button');
-    await confirmBtn.click();
+    const result = await testdriver.assert('Notepad shows "Hello from TestDriver"');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`exec()`](/exec) - Launch applications with PowerShell
-- [`pressKeys()`](/press-keys) - Use Alt+Tab to switch windows
-- [`find()`](/find) - Locate elements in the focused window
+- [Launch apps](/provision): open an app and focus it in one step
+- [exec()](/exec): start an app with a shell command
+- [pressKeys()](/press-keys): switch windows with keyboard shortcuts

package/docs/generating-tests.mdx

@@ -1,192 +1,158 @@
 ---
-title: "Explore"
+title: "Generate tests with AI"
 sidebarTitle: "Generating tests"
-description: "Generate tests by exploring your app with the AI vision agent"
+description: "Describe a flow in plain language, and the agent writes and runs the test."
 icon: "compass"
 ---
 
-Start with an exploration of your app. Tests begin here: you describe a flow in plain English. Then the TestDriver vision agent clicks, types, and reads the screen to understand it. Then it writes the test for you. There are no selectors, no DOM, and no weak locators. Only describe what you want to test. Let the agent find the other parts.
+Describe a flow in plain language, and the TestDriver agent writes the test for you.
 
-There are two methods for an exploration. You can chat with your AI assistant through the TestDriver MCP server. Or you can give a coding agent our instructions file and tell it to generate a test.
+- The agent runs in your AI coding assistant.
+- It runs the flow in a live sandbox and writes a Vitest test.
+- It finds elements by looking at the screen, so you never write selectors.
 
-<Info>
-  Both paths need an MCP-capable AI coding assistant. If you don't have one yet, start with **GitHub Copilot** — there's a [free tier](https://github.com/features/copilot/plans), no credit card required. See [Run → Setup](/copilot/running-tests#setup) for the full install and sign-in walkthrough.
-</Info>
+## Before you begin
 
-## Instructions for Coding Agents
+Install TestDriver in an AI coding assistant that can edit files in your repository:
 
-Start with [our quickstart](./quickstart). Then give your coding agent our agent instructions file.
+- **Claude Code:** [install the plugin](/quickstart-claude).
+- **VS Code or Cursor:** [install the extension](/quickstart-vscode).
+- **Any other assistant:** run `npx testdriverai init` in your repository and choose your assistant. See [Set up a project](/quickstart-manual).
 
-<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>
+## Start the agent
 
-Then, you can prompt your coding agent to generate tests. Here is an example prompt:
+Ask for the TestDriver agent by name in your assistant's chat:
 
-```md
-Make me a TestDriver test that does the following steps:
-
-Navigate to practicetestautomation.com
-Type username student into Username field
-Type password Password123 into Password field
-Push Submit button
-Verify new page contains expected text 'logged in'
-```
-
-<Info>Use explicit commands for production tests. They are at a lower cost, faster, and more reliable.</Info>
-
-## Start a Conversation
-
-Use the TestDriver MCP server and your AI assistant (GitHub Copilot, Cursor, or Claude Desktop) to make tests. You chat with an AI agent. The agent starts a virtual machine, does actions, and writes the test code for you.
-
-Open the chat of your AI assistant. If your project has no other agents, TestDriver uses the TestDriver agent by default. If not, select **testdriver** from the agent dropdown in the chat panel.
-
-Describe what you want to test:
-
-```
-Create a test that logs into my app at https://myapp.com
+```text
+Use the testdriver agent to write a test that logs in to https://testdriver-sandbox.vercel.app/login
 ```
 
-The agent will:
-1. Start a new session and spawn a Linux virtual machine
-2. Launch Chrome and navigate to your URL
-3. Execute actions based on your instructions
-4. Write the test code to a `.test.mjs` file
+In VS Code, you can also pick **testdriver** from the agent dropdown in the Copilot chat panel.
 
-<Note>
-  The TestDriver agent appears in the agent selection dropdown if you have other agents configured (like `copilot-instructions.md` or other `.agent.md` files). Make sure to select **testdriver** to use TestDriver's MCP tools.
-</Note>
+If your assistant doesn't support agent files, give it the [TestDriver agent instructions](https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md?plain=1) directly.
 
-## Live Preview Panel
+## Describe the test
 
-When the agent starts a session, a **live preview panel** opens in your editor. This lets you:
+Write the flow as the steps a user takes and what they should see at the end.
 
-- **Watch tests execute** in real-time
-- **Interact with the VM** — click, type, and navigate manually
-- **Debug issues** — see exactly what the AI sees
+Explicit steps make a test faster, cheaper, and more reliable than one where the agent works out the flow itself:
 
-<Note>
-  The live preview panel requires the TestDriver VS Code extension. Set `TD_PREVIEW=ide` in your MCP configuration to enable it. See the [Run page](/copilot/running-tests) for all device and preview options.
-</Note>
+```text
+Write a TestDriver test that does the following:
 
-## Interactive Workflow
-
-The recommended workflow for exploring and creating tests:
-
-<Steps>
-  <Step title="Describe Your Test">
-    Tell the agent what you want to test:
-
-    ```
-    Test the checkout flow on https://shop.example.com
-    ```
-  </Step>
-
-  <Step title="Watch and Guide">
-    The agent will start executing. Watch the preview panel and provide guidance if needed:
-
-    ```
-    The login modal appeared. Use test@example.com and password123
-    ```
-  </Step>
-
-  <Step title="Add Assertions">
-    Ask the agent to verify specific conditions:
+1. Open https://practicetestautomation.com/practice-test-login/
+2. Type "student" into the Username field
+3. Type "Password123" into the Password field
+4. Click the Submit button
+5. Verify the new page says "Logged In Successfully"
+```
 
-    ```
-    Assert that the order confirmation page is shown with the order number
-    ```
-  </Step>
+## Watch and steer the run
 
-  <Step title="Review the Code">
-    The agent writes test code as it works. Review the generated `.test.mjs` file and make any adjustments.
-  </Step>
-</Steps>
+The agent sends a screenshot after every action, so you see what it sees.
 
-## Example Conversation
+- In clients that support MCP Apps, each screenshot appears inline in the chat, with the targeted element highlighted.
+- With the [TestDriver extension](/quickstart-vscode) in VS Code or Cursor, the sandbox also plays live in a panel beside your code.
 
-Here's a complete example of exploring and creating a login test:
+If the agent gets stuck or takes a wrong turn, tell it what to do next:
 
+```text
+A cookie banner is covering the form. Accept it, then continue.
 ```
-You: Create a test for the login flow at https://console.testdriver.ai
-
-Agent: I'll create a test for the login flow. Starting a session...
-       [Screenshot: Login page loaded]
 
-       I can see the login page. Let me find the email input.
-       [Screenshot: Email input highlighted]
+You can also ask for more checks at any point:
 
-       Now I'll type the email and find the password field...
-
-You: Use test@example.com for the email
-
-Agent: Got it. Typing test@example.com...
-       [Screenshot: Email entered]
+```text
+Also assert that the page shows a Log out button.
+```
 
-       Now entering the password and clicking Sign In...
-       [Screenshot: Dashboard loaded]
+## What the agent does
 
-       ✅ Login successful! I've written the test to tests/login.test.mjs
-```
+1. **Starts a session.** It provisions a sandbox (Linux by default) and opens your app, for example Chrome at the URL you gave it.
+2. **Performs each step.** It finds each element from a description, acts on it, and checks the screenshot to confirm the step worked.
+3. **Writes code as it goes.** After each successful action, it appends the matching SDK code to a test file under `tests/`. The file always reflects what has actually run.
+4. **Runs the test.** It runs the file with `vitest run` and keeps fixing it until it passes.
 
-## Generated Test Code
+## Review the generated test
 
-The agent generates standard Vitest test files:
+The result is an ordinary Vitest file. Read, edit, commit, and run it in CI like any other test:
 
 ```javascript tests/login.test.mjs
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-describe("Login Flow", () => {
-  it("should log in successfully", async (context) => {
+describe('Practice login', () => {
+  it('logs in with valid credentials', async (context) => {
     const testdriver = TestDriver(context);
 
     await testdriver.provision.chrome({
-      url: "https://console.testdriver.ai"
+      url: 'https://practicetestautomation.com/practice-test-login/',
     });
 
-    const emailInput = await testdriver.find("email input field");
-    await emailInput.click();
-    await testdriver.type("test@example.com");
+    const usernameField = await testdriver.find('Username input field');
+    await usernameField.click();
+    await testdriver.type('student');
 
-    const passwordInput = await testdriver.find("password input field");
-    await passwordInput.click();
-    await testdriver.type("password123");
+    const passwordField = await testdriver.find('Password input field');
+    await passwordField.click();
+    await testdriver.type('Password123', { secret: true });
 
-    const signInButton = await testdriver.find("Sign In button");
-    await signInButton.click();
+    const submitButton = await testdriver.find('Submit button');
+    await submitButton.click();
 
-    const result = await testdriver.assert("dashboard is visible");
-    expect(result).toBeTruthy();
+    const result = await testdriver.assert('the page says "Logged In Successfully"');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Tips for Better Tests
+Before you commit, check two things:
+
+- Each `find()` description would still pick the right element if the page changed.
+- The assertions cover what you care about.
+
+<Tip>
+  If the test calls `ai()`, which works out a step on its own at run time, ask the agent to replace it with explicit `find()`, `click()`, and `type()` steps before you commit. Explicit steps run faster and do the same thing every time.
+</Tip>
+
+## Tips for better tests
 
 <AccordionGroup>
-  <Accordion title="Be specific with element descriptions">
-    Instead of "click the button", say "click the blue Sign In button in the header". More context helps the AI find the right element.
+  <Accordion title="Describe elements by what they look like">
+
+    "The blue Sign In button in the header" works better than "the button". Include the visible label. Add position or color when several elements look alike. See [Locate elements](/locating-elements).
+
   </Accordion>
-  <Accordion title="Add waits for dynamic content">
-    If your app has animations or loading states, tell the agent to wait:
-    ```
-    Wait for the loading spinner to disappear before continuing
-    ```
+  <Accordion title="Mention loading and animations">
+
+    If part of your app loads slowly, say so. For example: "wait for the loading spinner to disappear before continuing". The agent then waits instead of acting too early.
+
   </Accordion>
-  <Accordion title="Use assertions liberally">
-    Add assertions after each major action to catch regressions early:
-    ```
-    Assert that the product was added to the cart
-    ```
+  <Accordion title="Assert after each important step">
+
+    Assert after each meaningful action, such as "the item appears in the cart". When the test fails later, you see where the regression starts.
+
   </Accordion>
-  <Accordion title="Break complex flows into steps">
-    For long workflows, create the test incrementally and verify each step works before moving on.
+  <Accordion title="Build long flows in pieces">
+
+    Don't describe a long workflow all at once. Have the agent get the first part passing, then describe the next.
+
   </Accordion>
 </AccordionGroup>
 
-## Next
-
-<Card title="Learn" icon="brain" arrow="true" horizontal href="/caching">
-  Once the agent has explored your app, TestDriver caches what it discovers so your tests replay instantly without re-reasoning over the screen every time.
-</Card>
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Run tests" icon="play" href="/copilot/running-tests">
+    Choose a device, preview mode, and how to run your tests.
+  </Card>
+  <Card title="Speed up reruns with caching" icon="bolt" href="/caching">
+    Reuse what TestDriver found so reruns skip the AI.
+  </Card>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Write checks that catch the regressions you care about.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Run generated tests on every pull request.
+  </Card>
+</CardGroup>