@testdriverai/mcp 7.9.150-test → 7.9.152-test

package/ai/skills/testdriver-performing-actions/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: testdriver:performing-actions
-description: Click, type, hover, scroll and more with TestDriver
+description: Perform actions and handle dynamic, async UI so tests adapt to change
 ---
 <!-- Generated from performing-actions.mdx. DO NOT EDIT. -->
 
+Real apps move, load, and change. Adapt your tests to handle it.
+
+Once you've [generated](/v7/generating-tests) and [learned](/v7/caching) your tests and gotten them [running](/v7/copilot/running-tests), the next challenge is the real world: buttons appear after a spinner, pages navigate, animations play, and content streams in over the network. To keep tests reliable, you need to perform the right actions and handle timing so your tests adapt to how the UI actually behaves instead of breaking.
+
 ## Performing Actions
 
 TestDriver provides a variety of actions you can perform, like [clicking](/v7/click), [typing](/v7/type), [hovering](/v7/hover), and [scrolling](/v7/scroll). For a full list, see the [API Reference](/v7/click).
@@ -36,7 +40,7 @@ const price = await testdriver.extract('the total price');
 const orderNumber = await testdriver.extract('the order confirmation number');
 ```
 
-## Chaining Actions
+### Chaining Actions
 
 TestDriver supports method chaining for cleaner code:
 
@@ -51,3 +55,94 @@ Or save element reference for later use:
 const button = await testdriver.find('submit button');
 await button.click();
 ```
+
+## Waiting for Dynamic Content
+
+By default, `find()` automatically polls for up to 10 seconds, retrying every 5 seconds until the element is found. This means most elements that appear after short async operations will be found without any extra configuration.
+
+For longer operations, increase the `timeout`:
+
+```javascript
+// Default behavior - polls for up to 10 seconds automatically
+const element = await testdriver.find('Loading complete indicator');
+await element.click();
+
+// Wait up to 30 seconds for slower operations
+const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
+await element.click();
+
+// Useful after actions that trigger loading states
+await testdriver.find('submit button').click();
+await testdriver.find('success message', { timeout: 15000 });
+
+// Disable polling for instant checks
+const toast = await testdriver.find('notification toast', { timeout: 0 });
+```
+
+### Flake Prevention
+
+TestDriver automatically waits for the screen and network to stabilize after each action using **redraw detection**. This prevents flaky tests caused by animations, loading states, or dynamic content updates.
+
+<Note>
+  Redraw detection adds a small delay after each action but significantly reduces test flakiness.
+</Note>
+
+For example, when clicking a submit button that navigates to a new page:
+
+```javascript
+// Click submit - TestDriver automatically waits for the new page to load
+await testdriver.find('submit button').click();
+
+// By the time this runs, the page has fully loaded and stabilized
+await testdriver.assert('dashboard is displayed');
+await testdriver.find('welcome message');
+```
+
+Without redraw detection, you'd need manual waits or retries to handle the page transition. TestDriver handles this automatically by detecting when the screen stops changing and network requests complete.
+
+You can disable redraw detection or customize its behavior:
+
+```javascript
+// Disable redraw detection for faster tests (less reliable)
+const testdriver = TestDriver(context, { 
+  redraw: false 
+});
+```
+
+Here is an example of customizing redraw detection:
+
+```javascript
+// Fine-tune redraw detection
+const testdriver = TestDriver(context, { 
+  redraw: {
+    enabled: true,
+    diffThreshold: 0.1,      // Pixel difference threshold (0-1)
+    screenRedraw: true,      // Monitor screen changes
+    networkMonitor: true,    // Wait for network idle
+  }
+});
+```
+
+### Simple Delays with `wait()`
+
+For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+
+```javascript
+// Wait for an animation to complete
+await testdriver.find('menu toggle').click();
+await testdriver.wait(2000);
+
+// Wait for a page transition to settle
+await testdriver.find('next page button').click();
+await testdriver.wait(1000);
+```
+
+<Note>
+  For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.
+</Note>
+
+Once your tests can reliably act on a changing UI and [assert](/v7/making-assertions) the results, the next step is figuring out what happened when something does go wrong.
+
+<Card title="Next: Debug" icon="bug" href="/v7/debugging-with-screenshots">
+  Use screenshots and run output to see exactly what your test saw and pinpoint failures.
+</Card>

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

@@ -9,6 +9,53 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
 <Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have any questions or need help getting started!</Tip>
 
 <Tabs>
+  <Tab title="Add to GitHub" icon="github">
+
+    Drop-in UI testing for any GitHub repository. Mention `@testdriverai` anywhere in your repo and it writes UI tests and catches regressions before they merge.
+
+    <Card
+      title="Add to GitHub"
+      icon="github"
+      href="https://go.testdriver.ai/github"
+      arrow
+      horizontal
+    >
+      Install the TestDriver GitHub app and start testing in minutes — no setup required.
+    </Card>
+
+    <Steps>
+      <Step title="Install the GitHub App">
+        Click **Add to GitHub** above and install TestDriver on the repositories you want to test.
+      </Step>
+
+      <Step title="Mention @testdriverai">
+        Open a pull request or issue and mention `@testdriverai` to have it write and run UI tests:
+
+        ```
+        @testdriverai Write a test that verifies the homepage loads and the signup button works.
+        ```
+
+        TestDriver spawns a sandbox, writes the test, and posts results right in the conversation.
+      </Step>
+
+      <Step title="Catch Regressions Automatically">
+        Once your tests are committed, TestDriver runs them on every pull request and flags regressions before they merge.
+      </Step>
+    </Steps>
+
+    Want to use TestDriver from GitHub Copilot or the GitHub Mobile app instead? See the full GitHub guide:
+
+    <Card
+      title="GitHub Integration Guide"
+      icon="arrow-right"
+      href="/v7/copilot/auto-healing#use-testdriver-in-github"
+      arrow
+      horizontal
+    >
+      Use TestDriver from GitHub web, Copilot chat, PR reviews, and mobile.
+    </Card>
+
+  </Tab>
   <Tab title="CLI" icon="terminal">
 
     Get started quickly with the TestDriver CLI.
@@ -39,34 +86,6 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
       </Step>
     </Steps>
   </Tab>
-  <Tab title="GitHub Copilot" icon="github">
-
-    Use the TestDriver VS Code extension with GitHub Copilot for an AI-powered testing workflow.
-
-    <Card
-      title="Install TestDriver for VS Code"
-      icon="/images/content/extension/vscode.svg"
-      href="vscode:extension/testdriver.testdriver"
-      arrow
-      horizontal
-    >
-    </Card>
-
-    The extension provides one-click sign-in, project initialization, a live preview panel for watching tests execute, and MCP server configuration for GitHub Copilot.
-
-    Once installed, follow the full setup guide to configure MCP and start building tests with AI assistance:
-
-    <Card
-      title="VS Code + Copilot Setup Guide"
-      icon="arrow-right"
-      href="/v7/copilot/setup"
-      arrow
-      horizontal
-    >
-      Sign in, initialize your project, and configure MCP for GitHub Copilot.
-    </Card>
-
-  </Tab>
   <Tab title="Manual" icon="wrench">
 
     Install TestDriver and manually create the files yourself.

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

@@ -47,4 +47,4 @@ await testdriver.wait();
   const element = await testdriver.find('success message');
   ```
 - Avoid excessively long timeouts to keep tests efficient.
-- Use sparingly — TestDriver's [redraw detection](/v7/waiting-for-elements) automatically waits for screen and network stability after each action.
+- Use sparingly — TestDriver's [redraw detection](/v7/performing-actions#waiting-for-dynamic-content) automatically waits for screen and network stability after each action.

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

@@ -23,14 +23,3 @@ Type password Password123 into Password field
 Push Submit button
 Verify new page contains expected text 'logged in'
 ```
-
-## AI Exploration Mode
-
-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.
-
-```javascript
-// Handle dynamic or unpredictable UI
-await testdriver.ai('dismiss any popups or modals that appear');
-```
-
-<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>

package/docs/changelog.mdx

@@ -93,7 +93,7 @@ This release includes all changes from v7.8.0-test.6 with version bumps across a
 
 ✨ New features
 
-- **[GitHub Copilot integration](/v7/copilot/setup)** — Use TestDriver directly from GitHub Copilot in VS Code. The new MCP server lets Copilot launch sandboxes, interact with elements, and run assertions through natural language. Includes guides for [creating tests](/v7/copilot/creating-tests), [running tests](/v7/copilot/running-tests), [GitHub Actions integration](/v7/copilot/github), and [auto-healing](/v7/copilot/auto-healing).
+- **[GitHub Copilot integration](/v7/copilot/running-tests)** — Use TestDriver directly from GitHub Copilot in VS Code. The new MCP server lets Copilot launch sandboxes, interact with elements, and run assertions through natural language. Includes guides for [creating tests](/v7/generating-tests), [running tests](/v7/copilot/running-tests), [GitHub Actions integration](/v7/copilot/auto-healing#use-testdriver-in-github), and [auto-healing](/v7/copilot/auto-healing).
 
 🔧 Improvements
 

package/docs/docs.json

@@ -53,33 +53,16 @@
               "/changelog"
             ]
           },
-          {
-            "group": "GitHub Copilot",
-            "pages": [
-              "/v7/copilot/setup",
-              "/v7/copilot/creating-tests",
-              "/v7/copilot/running-tests",
-              "/v7/copilot/github",
-              "/v7/copilot/auto-healing"
-            ]
-          },
           {
             "group": "Guide",
             "pages": [
               "/v7/generating-tests",
-              "/v7/device-config",
-              "/v7/machine-setup",
-              "/v7/locating-elements",
-              "/v7/waiting-for-elements",
-              "/v7/performing-actions",
-              "/v7/making-assertions"
-            ]
-          },
-          {
-            "group": "Running Tests",
-            "pages": [
-              "/v7/running-tests",
               "/v7/caching",
+              "/v7/copilot/running-tests",
+              "/v7/making-assertions",
+              "/v7/performing-actions",
+              "/v7/debugging-with-screenshots",
+              "/v7/copilot/auto-healing",
               "/v7/ci-cd",
               "/v7/test-results-json"
             ]
@@ -91,7 +74,7 @@
               "/v7/secrets",
               "/v7/reusable-code",
               {
-                "group": "Self-Hosting Setup",
+                "group": "Self-Hosting",
                 "icon": "server",
                 "pages": [
                   "/v7/aws-setup"
@@ -99,25 +82,9 @@
               }
             ]
           },
-          {
-            "group": "AI",
-            "icon": "robot",
-            "pages": [
-              "/v7/ai/agent",
-              "/v7/ai/skills",
-              "/v7/ai/mcp"
-            ]
-          },
           {
             "group": "Actions",
             "pages": [
-              {
-                "group": "ai",
-                "tag": "Beta",
-                "pages": [
-                  "/v7/ai"
-                ]
-              },
               "/v7/assert",
               "/v7/captcha",
               "/v7/click",
@@ -366,6 +333,14 @@
     }
   },
   "redirects": [
+    {
+      "source": "/v7/ai",
+      "destination": "/v7/quickstart"
+    },
+    {
+      "source": "/v7/ai/:slug*",
+      "destination": "/v7/quickstart"
+    },
     {
       "source": "/guides/github-actions",
       "destination": "/v6/action/setup"

package/docs/v7/assert.mdx

@@ -313,4 +313,3 @@ describe('Assertions', () => {
 
 - [`extract()`](/v7/extract) - Extract information for detailed assertions
 - [`find()`](/v7/find) - Locate elements to verify
-- [`ai()`](/v7/ai) - Complex AI-driven tasks

package/docs/v7/caching.mdx

@@ -1,11 +1,13 @@
 ---
-title: "Caching Prompts"
-description: "1.7x faster test execution with intelligent caching and optimization"
-icon: "bolt"
+title: "Learn"
+sidebarTitle: "Learn"
+description: "How TestDriver learns your app and caches what it discovers for instant, deterministic replays"
+icon: "brain"
 ---
 
-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 +19,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 +55,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 +77,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 +105,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
@@ -123,6 +125,8 @@ await testdriver.find(`order ${orderId} status`, {
 });
 ```
 
+## 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/docs/v7/ci-cd.mdx

@@ -7,37 +7,33 @@ icon: "code-branch"
 
 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
 
@@ -51,7 +47,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:
@@ -64,28 +60,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/docs/v7/client.mdx

@@ -54,7 +54,7 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="reconnect" type="boolean" default="false">
-      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 [Machine Setup guide](/v7/machine-setup#keeping-machines-alive-between-runs).
+      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">