@testdriverai/mcp 7.9.150-test → 7.9.152-test

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

@@ -1,11 +1,12 @@
 ---
 name: testdriver:caching
-description: 1.7x faster test execution with intelligent caching and optimization
+description: How TestDriver learns your app and caches what it discovers for instant, deterministic replays
 ---
 <!-- Generated from caching.mdx. DO NOT EDIT. -->
 
-TestDriver is engineered for performance with intelligent caching that delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis.
+Once the agent has [explored your app](/v7/generating-tests), TestDriver remembers what it found. Every element the AI vision agent discovers is cached with a vision fingerprint—a perceptual hash of the screen state where it was located. On the next run, TestDriver matches against that cache instead of calling the AI again. Passing tests replay instantly, deterministically, and cheaply.
 
+This learning is what makes TestDriver fast. Intelligent caching delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis—the agent only thinks when it sees something new.
 
 ```javascript
 // First run: builds cache
@@ -17,7 +18,7 @@ await testdriver.find('submit button');
 
 ## Automatic Caching
 
-Caching is enabled automatically with zero configuration. The cache key is computed from:
+Learning is enabled automatically with zero configuration. The cache key—the fingerprint TestDriver uses to recognize what it already knows—is computed from:
 
 - **File hash**: SHA-256 hash of the test file contents
 - **Selector prompt**: The exact text description passed to `find()`
@@ -53,7 +54,7 @@ You can clear the cache within the TestDriver console. There, you'll also find p
 
 ## Debugging Cache Hits and Misses
 
-You can track cache performance in your tests:
+You can track what TestDriver has learned by inspecting cache performance in your tests:
 
 ```javascript
 test('monitor cache performance', async (context) => {
@@ -75,7 +76,7 @@ test('monitor cache performance', async (context) => {
 
 ## Configuring the Cache
 
-You can configure cache behavior globally when initializing TestDriver:
+You can configure how TestDriver learns globally when initializing TestDriver:
 
 ```javascript
 import { TestDriver } from 'testdriverai';
@@ -103,7 +104,7 @@ await testdriver.find('submit button', {
 
 ## Caching with Variables
 
-Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates.
+Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates—so TestDriver reuses what it learned even when your data changes.
 
 ```javascript
 // ❌ Without cache key - creates new cache for each variable value
@@ -122,3 +123,9 @@ await testdriver.find(`order ${orderId} status`, {
   cacheKey: 'order-status'  // Same cache for all orders
 });
 ```
+
+## Next
+
+<Card href="/v7/copilot/running-tests" title="Run" icon="play">
+  Now that TestDriver has learned your app, run your tests in CI and locally—replaying the cache for fast, deterministic results.
+</Card>

package/ai/skills/testdriver-ci-cd/SKILL.md

@@ -6,37 +6,33 @@ description: Run TestDriver tests in CI/CD with parallel execution and cross-pla
 
 TestDriver integrates seamlessly with popular CI providers, enabling automated end-to-end testing on every push and pull request.
 
-## Adding Your API Key
+## Authentication
 
-TestDriver requires an API key to authenticate with the TestDriver cloud. Store this securely as a secret in your CI provider.
+On **GitHub Actions, prefer OIDC** via the published `testdriverai/action` —
+there's no `TD_API_KEY` secret to store, copy, or rotate. The action proves the
+workflow is running inside your org and TestDriver exchanges that proof for your
+team's key at run time. See the GitHub Actions tab below.
 
-<Steps>
-  <Step title="Get Your API Key">
-    Go to [console.testdriver.ai/team](https://console.testdriver.ai/team) and copy your team's API key
-  </Step>
-  <Step title="Add Secret to Your CI Provider">
-    Add `TD_API_KEY` as a secret environment variable in your CI provider's settings.
-  </Step>
-</Steps>
+For other CI providers (or self-hosted runners without OIDC), fall back to a
+stored API key from [console.testdriver.ai/team](https://console.testdriver.ai/team),
+added as a `TD_API_KEY` secret in your CI provider's settings.
 
 <Note>
-  Never commit your API key directly in code. Always use your CI provider's secrets management.
+  Never commit your API key directly in code. Always use OIDC or your CI provider's secrets management.
 </Note>
 
 ## CI Provider Examples
 
 <Tabs>
   <Tab title="GitHub Actions">
-    ### Authenticate with OIDC (recommended)
+    ### Authenticate with OIDC via `testdriverai/action` (recommended)
 
-    If you've installed the [TestDriver GitHub App](https://console.testdriver.ai), your workflow can authenticate using GitHub's OIDC token — no long-lived `TD_API_KEY` secret to store or rotate. The workflow proves it's running inside your org, and TestDriver exchanges that proof for your team's API key at run time.
+    Use the published [`testdriverai/action`](https://github.com/testdriverai/action) — it mints the OIDC token, exchanges it for your team's API key, and exports `TD_API_KEY` for the steps that follow. **No `TD_API_KEY` secret to store or rotate.**
 
     <Note>
-      This requires the TestDriver GitHub App to be authorized for your organization once (from the [console](https://console.testdriver.ai)). If your org authorized the App before OIDC support shipped, re-run the authorization once so the binding is created.
+      One-time setup: authorize the [TestDriver GitHub App](https://console.testdriver.ai) for your org so the org → team binding exists. If your org authorized the App before OIDC support shipped, re-authorize once. If the App isn't authorized, the action fails with a console link (or falls back to the `api-key` secret if you provide one).
     </Note>
 
-    Grant the job the `id-token: write` permission and exchange the OIDC token for your API key:
-
     ```yaml .github/workflows/testdriver.yml
     name: TestDriver Tests
 
@@ -50,7 +46,7 @@ TestDriver requires an API key to authenticate with the TestDriver cloud. Store
       test:
         runs-on: ubuntu-latest
         permissions:
-          id-token: write   # required to mint an OIDC token
+          id-token: write   # REQUIRED to mint an OIDC token
           contents: read
 
         steps:
@@ -63,28 +59,18 @@ TestDriver requires an API key to authenticate with the TestDriver cloud. Store
 
           - run: npm ci
 
-          - name: Authenticate to TestDriver via OIDC
-            run: |
-              OIDC_TOKEN=$(curl -sS \
-                -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
-                "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=testdriver" | jq -r '.value')
-              API_KEY=$(curl -sS -X POST https://api.testdriver.ai/github/actions/auth \
-                -H "Content-Type: application/json" \
-                -d "{\"token\":\"$OIDC_TOKEN\"}" | jq -r '.apiKey')
-              echo "::add-mask::$API_KEY"
-              echo "TD_API_KEY=$API_KEY" >> "$GITHUB_ENV"
+          - name: Authenticate to TestDriver
+            uses: testdriverai/action@stable   # pin @stable / @canary / @test to your SDK channel
+            with:
+              api-key: ${{ secrets.TD_API_KEY }}   # optional fallback if OIDC isn't set up
 
           - name: Run TestDriver tests
-            env:
-              TD_API_KEY: ${{ env.TD_API_KEY }}
-            run: vitest --run
+            run: npx vitest run
     ```
 
-    `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL` are injected automatically once `permissions: id-token: write` is set. `::add-mask::` keeps the resolved key out of the logs.
-
-    ### Adding Secrets
+    ### Stored-key fallback
 
-    Prefer OIDC above when possible. If you can't use the GitHub App (e.g. self-hosted runners without OIDC, or a non-GitHub registry), fall back to a stored API key:
+    Only if you can't use OIDC (e.g. self-hosted runners without an OIDC provider). Add the key as a secret and pass it via `env`:
 
     1. Navigate to your GitHub repository
     2. Go to **Settings** → **Secrets and variables** → **Actions**

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

@@ -53,7 +53,11 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="reconnect" type="boolean" default="false">
-      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+      Reattach to the last used sandbox instead of creating a new one. When `true`, the SDK reads the sandbox id from `.testdriver/last-sandbox` (written automatically on every successful connect) and rejoins that VM. Provision methods (`chrome`, `vscode`, `installer`, etc.) are skipped because the application is already running. The previous sandbox must still be alive — see [`keepAlive`](#keepalive) and the [Run guide](/v7/copilot/running-tests#keeping-machines-alive-between-runs).
+    </ParamField>
+
+    <ParamField path="sandboxId" type="string">
+      Reattach to a specific sandbox id instead of the one recorded in `.testdriver/last-sandbox`. Use this for CI matrices or to pin a chain of tests to a known VM. Implies `reconnect: true` behavior (provision calls are skipped).
     </ParamField>
     
     <ParamField path="preview" type="string" default="browser">

package/ai/skills/testdriver-debugging-with-screenshots/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: testdriver:debugging-with-screenshots
-description: View and analyze saved screenshots using MCP commands for test debugging and development
+description: Diagnose failing tests with screenshots, replays, and logs
 ---
 <!-- Generated from debugging-with-screenshots.mdx. DO NOT EDIT. -->
 
 ## Overview
 
-TestDriver MCP provides powerful commands to view and analyze screenshots saved during test execution. This enables rapid debugging, test development, and comparison workflows without manually opening image files.
+When a test fails, debug it by seeing exactly what happened — don't guess. TestDriver captures screenshots, video replays, and logs as your test runs, so you can replay the moment of failure instead of squinting at a stack trace. TestDriver MCP provides powerful commands to view and analyze the screenshots saved during test execution, enabling rapid debugging, test development, and comparison workflows without manually opening image files.
 
 <Note>
   **Automatic Screenshots (Default: Enabled)**: TestDriver automatically captures screenshots before and after every command. Screenshots are named with the line number and action, making it easy to trace exactly which line of code produced each screenshot. For example: `001-click-before-L42-submit-button.png`
@@ -122,7 +122,7 @@ view_local_screenshot({ path: "/full/path/to/screenshot.png" })
 
 ### Test Debugging After Failures
 
-When a test fails, use powerful filtering to quickly find relevant screenshots:
+When a test fails, you don't have to wonder what went wrong — use powerful filtering to quickly find the screenshots that show exactly what happened:
 
 **1. Find screenshots at the failing line:**
 
@@ -358,7 +358,7 @@ This helps verify your test logic before running the full test file.
 
 ### After Test Runs
 
-When tests fail or behave unexpectedly:
+When tests fail or behave unexpectedly, replay what happened step by step:
 
 1. **Run the test** with `vitest run tests/my-test.test.mjs`
 2. **List screenshots** using `list_local_screenshots`
@@ -408,8 +408,18 @@ When tests fail or behave unexpectedly:
   </Accordion>
 </AccordionGroup>
 
+## Where this fits in the Guide
+
+Debugging is what you reach for when a [Run](/v7/copilot/running-tests) goes sideways or a [Validate](/v7/making-assertions) assertion fails — the screenshots show you precisely what the AI saw before it acted. Once you've diagnosed the failure, the next step is to stop it from recurring.
+
 ## Related
 
 - [screenshot()](/v7/screenshot) - Capture screenshots during test execution
 - [Dashcam](/v7/dashcam) - Record full test sessions with video and logs
 - [assert()](/v7/assert) - Make AI-powered assertions that benefit from screenshot context
+
+## Next
+
+<Card title="Prevent" icon="shield-check" href="/v7/copilot/auto-healing">
+  You've seen what went wrong — now keep it from happening again. Let auto-healing repair flaky tests automatically before they fail your suite.
+</Card>

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

@@ -401,6 +401,8 @@ await element.click();
 
 ## Cache Options
 
+When a test completes successfully, the result of each `find()` is cached. On later runs, TestDriver reuses the cached match instead of making a fresh AI call, which significantly speeds up locating the same element. The cache lives in your [dashboard](https://console.testdriver.ai/cache) and is shared across runs — see the [Cache](/v7/cache) page for how matching, thresholds, and invalidation work.
+
 Control caching behavior to optimize performance, especially when using dynamic variables in prompts.
 
 ### Custom Cache Key

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

@@ -1,12 +1,16 @@
 ---
 name: testdriver:generating-tests
-description: Use AI coding agents and exploration mode to generate TestDriver tests
+description: Generate tests by exploring your app with the AI vision agent
 ---
 <!-- Generated from generating-tests.mdx. DO NOT EDIT. -->
 
+Start by exploring your app. This is where tests begin: you describe a flow in plain English, and the TestDriver vision agent clicks, types, and reads the screen to figure it out — then writes the test for you. No selectors, no DOM, no brittle locators. Just describe what you want to test and let the agent discover the rest.
+
+There are two ways to explore: chatting interactively with your AI assistant through the TestDriver MCP server, or handing a coding agent our instructions file and prompting it to generate a test.
+
 ## Instructions for Coding Agents
 
-We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agent instructions file.
+We recommend starting with [our quickstart](./quickstart), then supplying your coding agent with our agent instructions file.
 
 <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.
@@ -24,13 +28,160 @@ Push Submit button
 Verify new page contains expected text 'logged in'
 ```
 
-## AI Exploration Mode
+<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>
+
+## Start a Conversation
 
-Within a test, the `ai()` method lets TestDriver autonomously figure out how to accomplish a task. It's useful for dynamic or unpredictable UIs where explicit actions may be difficult to define.
+With TestDriver's MCP server and your AI assistant (GitHub Copilot, Cursor, or Claude Desktop), you can create tests by chatting with an AI agent. The agent spawns a virtual machine, executes actions, and writes test code for you.
 
-```javascript
-// Handle dynamic or unpredictable UI
-await testdriver.ai('dismiss any popups or modals that appear');
+Open your AI assistant's chat. If your project has no other agents configured, the TestDriver agent is used by default. Otherwise, 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
 ```
 
-<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>
+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
+
+<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>
+
+## Live Preview Panel
+
+When the agent starts a session, a **live preview panel** opens in your editor. This lets you:
+
+- **Watch tests execute** in real-time
+- **Interact with the VM** — click, type, and navigate manually
+- **Debug issues** — see exactly what the AI sees
+
+<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](/v7/copilot/running-tests) for all device and preview options.
+</Note>
+
+## 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:
+
+    ```
+    Assert that the order confirmation page is shown with the order number
+    ```
+  </Step>
+
+  <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>
+
+## Example Conversation
+
+Here's a complete example of exploring and creating a login test:
+
+```
+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]
+
+       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]
+
+       Now entering the password and clicking Sign In...
+       [Screenshot: Dashboard loaded]
+
+       ✅ Login successful! I've written the test to tests/login.test.mjs
+```
+
+## Generated Test Code
+
+The agent generates standard Vitest test files:
+
+```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) => {
+    const testdriver = TestDriver(context);
+
+    await testdriver.provision.chrome({
+      url: "https://console.testdriver.ai"
+    });
+
+    const emailInput = await testdriver.find("email input field");
+    await emailInput.click();
+    await testdriver.type("test@example.com");
+
+    const passwordInput = await testdriver.find("password input field");
+    await passwordInput.click();
+    await testdriver.type("password123");
+
+    const signInButton = await testdriver.find("Sign In button");
+    await signInButton.click();
+
+    const result = await testdriver.assert("dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## 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>
+  <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>
+  <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>
+  <Accordion title="Break complex flows into steps">
+    For long workflows, create the test incrementally and verify each step works before moving on.
+  </Accordion>
+</AccordionGroup>
+
+## Next
+
+<Card title="Learn" icon="brain" arrow="true" horizontal href="/v7/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>

package/ai/skills/testdriver-machine-setup/SKILL.md

@@ -87,6 +87,16 @@ const testdriver = TestDriver(context, {
 
 Windows (and Linux) cold starts can be expensive if you're iterating quickly. Use `keepAlive` + `reconnect` to reuse the same VM across multiple test runs.
 
+### How it works
+
+Every time the SDK successfully connects to a sandbox, it records the sandbox id in `.testdriver/last-sandbox` inside your project directory. The next test that opts in with `reconnect: true` reads that file and reattaches automatically — no manual id tracking required.
+
+Provision calls (`testdriver.provision.chrome(...)`, `vscode(...)`, etc.) are **skipped** when reconnecting, because the application is already running inside the sandbox from the previous run.
+
+<Note>
+  `.testdriver/last-sandbox` is already covered by the default TestDriver `.gitignore`. Don't commit it.
+</Note>
+
 ### Step 1 — Start the machine with a long `keepAlive`
 
 ```javascript
@@ -102,30 +112,87 @@ await testdriver.provision.chrome({ url: "https://example.com" });
 
 When this test finishes, the sandbox stays running for 30 minutes instead of being terminated immediately.
 
-### Step 2 — Connect in subsequent runs
+### Step 2 — Reattach automatically with `reconnect: true`
 
 ```javascript
 // second.test.mjs
 const testdriver = TestDriver(context, {
   os: "windows",
+  reconnect: true,            // ← reads .testdriver/last-sandbox
   keepAlive: 30 * 60 * 1000,
 });
 
-await testdriver.connect({ sandboxId: "sandbox-abc123" });
-
-// provision.chrome() is automatically skipped — Chrome is already open
+// No provision call — Chrome is already open from the previous run.
 await testdriver.find("Sign In button").click();
 ```
 
-When connecting to an existing sandbox ID:
+### Step 2 (alternative) — Reattach to an explicit id
+
+If you need to pin to a specific sandbox (CI matrix, multiple chains in parallel, etc.) pass the id directly:
+
+```javascript
+await testdriver.connect({ sandboxId: "sandbox-abc123" });
+```
+
+When reattaching to a sandbox:
 - You reuse a specific running machine directly
-- You can continue from the app state created in an earlier test run
-- You should run within the previous test's `keepAlive` window
+- You continue from the app state created in the earlier run
+- You must run within the previous test's `keepAlive` window
 
 <Tip>
-  You can also supply a sandbox ID directly: `await testdriver.connect({ sandboxId: "sandbox-abc123" })`. Use `testdriver.getLastSandboxId()` to retrieve the ID of the last sandbox for scripting purposes.
+  Use `testdriver.getLastSandboxId()` to read the recorded sandbox id (and optional metadata) for scripting purposes.
 </Tip>
 
+### Chaining describe blocks within one test file
+
+A common pattern is to break a long flow into focused `describe` blocks that share one sandbox — the first block provisions and signs in, later blocks reconnect and continue:
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+const KEEP_ALIVE_MS = 5 * 60 * 1000;
+
+describe("step 1 — log in", () => {
+  it("signs in and lands on the dashboard", async (context) => {
+    const testdriver = TestDriver(context, { keepAlive: KEEP_ALIVE_MS });
+    await testdriver.provision.chrome({ url: "https://example.com/login" });
+    await testdriver.find("username input").click();
+    await testdriver.type("standard_user");
+    await testdriver.pressKeys(["tab"]);
+    await testdriver.type("secret_sauce", { secret: true });
+    await testdriver.pressKeys(["enter"]);
+    expect(await testdriver.assert("the dashboard is visible")).toBeTruthy();
+  });
+});
+
+describe("step 2 — add to cart", () => {
+  it("reuses the logged-in sandbox", async (context) => {
+    const testdriver = TestDriver(context, {
+      reconnect: true,           // ← skip provisioning, reattach
+      keepAlive: KEEP_ALIVE_MS,
+    });
+    await testdriver.find("Add to cart").click();
+    await testdriver.find("cart icon").click();
+    expect(await testdriver.assert("the cart has an item")).toBeTruthy();
+  });
+});
+
+describe("step 3 — check out", () => {
+  it("continues from the cart state", async (context) => {
+    const testdriver = TestDriver(context, { reconnect: true, keepAlive: 30_000 });
+    await testdriver.find("Checkout").click();
+    expect(await testdriver.assert("the checkout form is visible")).toBeTruthy();
+  });
+});
+```
+
+A runnable copy of this pattern lives at [`examples/reconnect-sequential.test.mjs`](https://github.com/testdriverai/mono/blob/main/sdk/examples/reconnect-sequential.test.mjs).
+
+<Warning>
+  Vitest runs **test files** in parallel by default. Within a single file, `describe`/`it` blocks run in source order, so reconnect chaining works as written. To chain across multiple files, run them sequentially (e.g. `vitest run --sequence.concurrent=false` or place them in a single project pool with workers set to 1).
+</Warning>
+
 ### How `keepAlive` works
 
 `keepAlive` is a duration in milliseconds. After the SDK disconnects, the server keeps the VM running for that long before terminating it. The default is `60000` (1 minute). Note: `keepAlive: 0` currently falls back to the default disconnect grace period rather than terminating immediately, so use a positive duration when you want to control the grace window explicitly.

package/ai/skills/testdriver-making-assertions/SKILL.md

@@ -1,12 +1,82 @@
 ---
 name: testdriver:making-assertions
-description: Verify application state with AI-powered assertions
+description: Locate elements and verify app state with AI-powered assertions
 ---
 <!-- Generated from making-assertions.mdx. DO NOT EDIT. -->
 
+Once a test runs, validate that the app did what it should. Validation has two parts: locating the elements you want to check, and making assertions about the state of your app. TestDriver uses AI as a judge, returning a boolean plus reasoning about whether your app is in the expected state.
+
+## Locating Elements
+
+### Locating Single Elements
+
+Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:
+
+```javascript
+await testdriver.find('email input field');
+await testdriver.find('first product card in the grid');
+await testdriver.find('dropdown menu labeled "Country"');
+```
+
+<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>
+
+### Debugging Found Elements
+
+After finding an element, you can inspect its properties for debugging:
+
+```javascript
+const button = await testdriver.find('submit button');
+console.log(button);
+```
+
+This outputs all element properties:
+
+```javascript
+{
+  description: 'submit button',
+  found: true,
+  x: 150,
+  y: 300,
+  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
+  threshold: 0.8,
+  confidence: 0.95,
+  similarity: 0.92,
+  selector: 'button[type="submit"]',
+  cache: {
+    hit: true,
+    strategy: 'pixel-diff',
+    createdAt: '2025-01-15T10:30:00Z',
+    diffPercent: 0.02,
+    imageUrl: 'https://...'
+  }
+}
+```
+
+### Working with Multiple Elements
+
+Find and interact with multiple elements:
+
+```javascript
+// Find all matching elements
+const products = await testdriver.findAll('product card');
+console.log(`Found ${products.length} products`);
+
+// Interact with each
+for (const product of products) {
+  const title = await product.find('title text');
+  console.log('Product:', title.text);
+
+  await product.find('add to cart button').click();
+}
+
+// Or find specific element
+const firstProduct = products[0];
+await firstProduct.click();
+```
+
 ## Making Assertions
 
-Use AI-powered assertions to verify application state:
+Use AI-powered assertions to verify application state. TestDriver acts as a judge: it evaluates your natural-language statement against the current state of the app and returns a boolean plus reasoning explaining the verdict.
 
 ```javascript
 // Verify visibility
@@ -30,3 +100,9 @@ await testdriver.assert('form has red border');
 ```
 
 <Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>
+
+## Next
+
+<Card title="Adapt" icon="arrows-rotate" href="/v7/performing-actions">
+  Drive your app forward by performing actions on the elements you've located and validated.
+</Card>