@testdriverai/agent 7.11.240-test → 7.11.241-test

package/ai/skills/testdriver-wait/SKILL.md

@@ -1,50 +1,52 @@
 ---
 name: testdriver:wait
-description: Pause the execution of the script for a specified duration.
+description: Pause the test for a fixed number of milliseconds.
 ---
 <!-- Generated from wait.mdx. DO NOT EDIT. -->
 
-## Description
+Pause the test for a fixed time, for example while an animation finishes:
 
-The `wait` method stops the test for a number of milliseconds. Then it continues. Use this to add delays between actions, to wait for animations to complete, or to let state changes become stable.
+```javascript
+await testdriver.find('Menu toggle').click();
+await testdriver.wait(1000);
+```
 
-## Syntax
+To wait for an element to appear, don't use `wait()`. Use [`find()`](/find) with a `timeout`, which continues as soon as the element shows up:
 
 ```javascript
-await testdriver.wait(timeout);
+await testdriver.find('Order confirmation message', { timeout: 30000 });
+```
+
+## Signature
+
+```typescript
+testdriver.wait(timeout?: number): Promise<void>
 ```
 
-## Arguments
+## Parameters
 
-| Argument  | Type     | Default | Description                           |
-| --------- | -------- | ------- | ------------------------------------- |
-| `timeout` | `number` | `3000`  | The duration in milliseconds to wait. |
+<ParamField path="timeout" type="number" default="3000">
+  How long to pause, in milliseconds.
+</ParamField>
 
 ## Examples
 
+### Let a transition finish
+
 ```javascript
-// Wait 2 seconds for an animation to complete
-await testdriver.find('submit button').click();
-await testdriver.wait(2000);
+await testdriver.find('Settings tab').click();
+await testdriver.wait(500);
+await testdriver.assert('the Settings panel is fully open');
+```
 
-// Wait 5 seconds
-await testdriver.wait(5000);
+### Pause for the default time
 
-// Wait with default timeout (3 seconds)
-await testdriver.wait();
+```javascript
+await testdriver.wait(); // 3 seconds
 ```
 
-## Best Practices
-
-- **Use it for simple delays**. Wait for animations, transitions, or state changes after an action.
-- **Do not use it to wait for an element**. If you wait for a specific element to show, use `find()` with a `timeout` option:
-  ```javascript
-  // ✅ Better for waiting for elements
-  const element = await testdriver.find('success message', { timeout: 30000 });
+## Related
 
-  // ❌ Don't do this for element waiting
-  await testdriver.wait(5000);
-  const element = await testdriver.find('success message');
-  ```
-- Do not use very long timeouts. This keeps the tests efficient.
-- Use it only when necessary. The TestDriver [redraw detection](/performing-actions#waiting-for-dynamic-content) waits automatically for the screen and the network to become stable after each action.
+- [find()](/find): wait for an element with a `timeout`
+- [Wait for a changing UI](/performing-actions#wait-for-a-changing-ui): choose the right way to wait
+- [Redraw detection](/redraw): wait for the screen to settle after each action

package/ai/skills/testdriver-what-is-testdriver/SKILL.md

@@ -1,54 +1,102 @@
 ---
 name: testdriver:what-is-testdriver
-description: Reliably test your most difficult user flows
+description: TestDriver tests apps by seeing the screen and controlling a real machine, without selectors.
 ---
 <!-- Generated from what-is-testdriver.mdx. DO NOT EDIT. -->
 
-## The problem with usual test tools
+TestDriver is an end-to-end testing platform that tests your app the way a person uses it.
 
-Usual test tools such as Playwright test one web application. They use one browser tab and they use selectors.
+- It looks at the screen.
+- It finds elements from plain-language descriptions.
+- It controls a real machine with the mouse and keyboard.
 
-But selectors are frequently not reliable, or they are not available. This makes tests weak and not stable:
+It doesn't rely on CSS or XPath selectors. So it can test flows that selector-based tools can't reach, such as desktop apps, browser extensions, and content that changes every time it renders.
 
-| Challenge | Problem | Examples |
-|-----------|---------|----------|
-| **Teams that move quickly** | They change the UI structure frequently. This breaks the CSS and XPath selectors. | Agile teams, startups, vibe-coders |
-| **Dynamic content** | You cannot select it with selectors. | AI chatbots, PDFs, images, videos |
-| **Software that you do not own** | It can have no correct accessibility attributes. | Other websites, extensions, third-party applications |
-| **Workflows with more than one application** | You cannot test them with web-only tools. | Desktop apps, browser extensions, IDEs |
-| **Visual states** | You cannot make a check of them with code selectors. | Charts, graphs, videos, images, spelling errors, UI layout |
+## Where selector-based tests fall short
 
-## The TestDriver solution
+Tools such as Playwright and Cypress drive a single web page through its DOM. They locate elements with selectors.
 
-TestDriver is a complete test platform. It handles these conditions. It has a Javascript SDK, hosted infrastructure, and debug tools. These tools make it easy to write, run, and keep tests for your most difficult user flows.
+That works until a test needs something the DOM can't describe reliably:
 
-### Javascript SDK
+| Situation | Why selectors break down | Examples |
+| --- | --- | --- |
+| **A fast-changing UI** | Each redesign changes the markup and breaks CSS and XPath selectors. | Startups, teams shipping AI-generated code |
+| **Dynamic content** | Generated content has no stable structure to select. | AI chat responses, PDFs, images, video |
+| **Software you don't own** | Third-party markup often lacks stable IDs or accessibility attributes. | Other websites, embedded widgets, third-party apps |
+| **More than one application** | Web-only tools can't leave the browser tab. | Desktop apps, browser extensions, IDEs, installers |
+| **Visual state** | Whether something *looks* right isn't in the DOM. | Charts, layout, spelling, rendered media |
 
-This is an example of a TestDriver test. The test installs a production Chrome extension from the Chrome Web Store. Then it makes sure that the extension is in the extensions menu:
+## How TestDriver works
 
-```javascript Installing Loom from the Chrome Web Store
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+A TestDriver test is a [Vitest](https://vitest.dev) test. It runs against a cloud sandbox, a fresh Linux machine, or Windows on [Enterprise](https://testdriver.ai/enterprise/) plans.
 
-describe("Chrome Extension Test", () => {
-  const testdriver = TestDriver(context);
+Each step describes what a user would see or do:
 
-  // Launch Chrome with Loom loaded by its Chrome Web Store ID
-  await testdriver.provision.chromeExtension({
-    extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
-  });
+1. **[Provision](/provision)** launches the app under test in the sandbox, such as Chrome at a URL, a Chrome extension, VS Code, an Electron app, or a downloaded installer.
+2. **[Find](/locating-elements)** takes a description like `'Sign in button'` and uses AI vision to locate the matching element on screen.
+3. **[Act](/performing-actions)** clicks, types, scrolls, and presses keys on the real machine. The app receives the same input a person would produce.
+4. **[Assert](/making-assertions)** checks a plain-language statement about the screen, such as `'the cart shows one item'`.
+
+This test installs the Loom extension from the Chrome Web Store. It checks that Loom appears in Chrome's extensions menu, a flow that a DOM-only tool can't drive:
+
+```javascript tests/loom-extension.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Loom extension', () => {
+  it('appears in the Chrome extensions menu', async (context) => {
+    const testdriver = TestDriver(context);
 
-  // Click on the extensions button (puzzle piece icon) in Chrome toolbar
-  const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
-  await extensionsButton.click();
+    // Launch Chrome with Loom installed by its Chrome Web Store ID
+    await testdriver.provision.chromeExtension({
+      extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb',
+    });
 
-  // Look for Loom in the extensions menu
-  const loomExtension = await testdriver.find("Loom extension in the extensions dropdown");
-  expect(loomExtension.found()).toBeTruthy();
+    const extensionsButton = await testdriver.find('puzzle-piece extensions icon in the Chrome toolbar');
+    await extensionsButton.click();
+
+    const loomExtension = await testdriver.find('Loom in the extensions dropdown');
+    expect(loomExtension.found()).toBe(true);
+  });
 });
 ```
 
+To run this yourself, follow the [Quickstart](/quickstart).
+
+## What's included
+
+- **The SDK**, the `testdriverai` npm package. Use it in Vitest tests to provision apps, find elements, act, and assert.
+- **Cloud sandboxes** that run your tests on fresh Linux machines, or Windows on Enterprise plans. Enterprise customers can also [self-host](/self-hosted) them.
+- **Debugging tools**: screen recordings of every run, [screenshots](/debugging-with-screenshots), and [element caching](/caching) for faster, more stable repeat runs.
+- **[The TestDriver agent](/agent)**, which reviews your pull requests and writes and maintains tests from GitHub.
+
+## When to use TestDriver
+
+TestDriver is built for flows that are hard to cover any other way:
+
+- Multi-application workflows
+- Desktop software
+- Browser extensions
+- Third-party UIs
+- Visual checks
+
+Each step runs on a real machine and uses AI vision. So a TestDriver test takes longer per step than a test that talks to the DOM directly.
+
+If stable, selector-based tests already cover a flow, keep them. Use TestDriver for the parts they can't reach.
 
-<Tip>[vitest](https://vitest.dev/) is the preferred test runner for TestDriver.</Tip>
+## Related
 
-,
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/quickstart">
+    Install TestDriver and run your first test.
+  </Card>
+  <Card title="Locate elements" icon="crosshairs" href="/locating-elements">
+    Write descriptions that find the right element reliably.
+  </Card>
+  <Card title="The TestDriver agent" icon="hand-horns" href="/agent">
+    Let the agent review pull requests and build tests from GitHub.
+  </Card>
+  <Card title="Hosted sandboxes" icon="cloud" href="/hosted">
+    Run tests on TestDriver's cloud infrastructure.
+  </Card>
+</CardGroup>

package/package.json

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