@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/_data/examples-manifest.json

@@ -21,10 +21,6 @@
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b99dc33133fc0da9440",
       "lastUpdated": "2026-03-03T00:32:25.282Z"
     },
-    "hover-text-with-description.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5f0022b6043aeec2beb",
-      "lastUpdated": "2026-10-20T00:30:09.018Z"
-    },
     "windows-installer.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5f29af2067e32da0685",
       "lastUpdated": "2026-10-20T00:33:18.176Z"
@@ -41,10 +37,6 @@
       "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5eeff9c1cd5b2e06bf9",
       "lastUpdated": "2026-10-20T00:30:38.454Z"
     },
-    "hover-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5f59af2067e32da0686",
-      "lastUpdated": "2026-10-20T00:29:41.180Z"
-    },
     "installer.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5f79af2067e32da0688",
       "lastUpdated": "2026-10-20T00:29:43.255Z"
@@ -59,10 +51,6 @@
       "embedUrl": "https://console-test.testdriver.ai/replay/6ad6b808ff9c1cd5b2e06c32?share=5iVQVpaLc2kTqD7pV7nynA&embed=true",
       "lastUpdated": "2026-10-20T00:38:38.191Z"
     },
-    "scroll-keyboard.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b600022b6043aeec2bf0",
-      "lastUpdated": "2026-10-20T00:30:55.250Z"
-    },
     "scroll.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b6069af2067e32da068a",
       "lastUpdated": "2026-10-20T00:30:29.949Z"
@@ -91,10 +79,6 @@
       "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c873a714b73310c7839450",
       "lastUpdated": "2026-03-29T00:36:10.628Z"
     },
-    "hover-text.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b60a022b6043aeec2bf1",
-      "lastUpdated": "2026-10-20T00:30:33.458Z"
-    },
     "no-provision.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b7706a177a05bccd1cf",
       "lastUpdated": "2026-03-03T00:32:25.279Z"
@@ -180,6 +164,22 @@
     "exec-stream-logs.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/69c9c4feffa05350a7d3abc1/69c9c520ffa05350a7d3abd9",
       "lastUpdated": "2026-03-30T00:35:14.437Z"
+    },
+    "click-icon.test.mjs": {
+      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5f59af2067e32da0686",
+      "lastUpdated": "2026-10-20T00:29:41.180Z"
+    },
+    "click-button.test.mjs": {
+      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b60a022b6043aeec2bf1",
+      "lastUpdated": "2026-10-20T00:30:33.458Z"
+    },
+    "add-to-cart.test.mjs": {
+      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b5f0022b6043aeec2beb",
+      "lastUpdated": "2026-10-20T00:30:09.018Z"
+    },
+    "navigate-and-scroll.test.mjs": {
+      "url": "https://console-test.testdriver.ai/runs/6ad6b5ebff9c1cd5b2e06bf7/6ad6b600022b6043aeec2bf0",
+      "lastUpdated": "2026-10-20T00:30:55.250Z"
     }
   }
 }

package/docs/_scripts/generate-examples.js

@@ -108,11 +108,18 @@ function transformContentForDocs(content) {
     ''
   );
 
-  // Replace getDefaults(context) spread with inline defaults
-  transformed = transformed.replace(
-    /\{\s*\.\.\.getDefaults\(context\)\s*/g,
-    '{ ip: context.ip || process.env.TD_IP'
-  );
+  // Drop CI-only TestDriver options so readers see the minimal setup:
+  // `...getDefaults(context)` (sandbox IP, preview and cache settings for CI)
+  // and `headless: true` (deprecated, and only there to keep CI runs headless).
+  transformed = transformed.replace(/\.\.\.getDefaults\(context\),?\s*/g, '');
+  transformed = transformed.replace(/headless:\s*true,?\s*/g, '');
+  // `TestDriver(context, { })` left empty by the removals above
+  transformed = transformed.replace(/TestDriver\(context,\s*\{\s*\}\s*\)/g, 'TestDriver(context)');
+  // Tidy `{ ` / ` }` padding left behind on single-line option objects
+  transformed = transformed.replace(/TestDriver\(context,\s*\{\s*([^{}\n]*?)\s*\}\)/g, 'TestDriver(context, { $1 })');
+
+  // Drop the file's leading JSDoc header; the page's intro already says what the test does
+  transformed = transformed.replace(/^\/\*\*\n[\s\S]*?\n\s*\*\/\n+/, '');
 
   return transformed;
 }
@@ -123,8 +130,8 @@ function parseTestFile(filePath) {
   const content = transformContentForDocs(raw);
   const filename = path.basename(filePath);
 
-  // Extract JSDoc comment at top of file
-  const jsdocMatch = content.match(/^\/\*\*\n([\s\S]*?)\n\s*\*\//);
+  // Extract JSDoc comment at top of file (from the raw source; the docs copy strips it)
+  const jsdocMatch = raw.match(/^\/\*\*\n([\s\S]*?)\n\s*\*\//);
   const jsdoc = jsdocMatch
     ? jsdocMatch[1]
         .split("\n")
@@ -197,7 +204,7 @@ async function generateAIDescription(testMeta, options) {
     return generateFallbackDescription(testMeta);
   }
 
-  const prompt = `You are a technical writer for TestDriver.ai documentation. Generate a concise 2-3 paragraph description for this test example.
+  const prompt = `You are a technical writer for TestDriver.ai documentation. Write the one- or two-sentence introduction for this test example's docs page.
 
 Test file: ${testMeta.filename}
 Test suite name: ${testMeta.describeName || "N/A"}
@@ -209,12 +216,7 @@ Test code:
 ${testMeta.content}
 \`\`\`
 
-Write a description that:
-1. Explains what this test demonstrates (first paragraph)
-2. Describes the key TestDriver SDK methods used (second paragraph)
-3. Mentions any important patterns or best practices shown (optional third paragraph)
-
-Keep it professional and focused on helping developers understand the example. Do not include code blocks in your response.`;
+Say what the test does and which TestDriver methods it demonstrates, in second person and present tense (for example: "This test opens the login page and uses \`assert()\` to check that it loaded."). No marketing words, no headings, no code blocks.`;
 
   try {
     const response = await fetch("https://api.openai.com/v1/chat/completions", {
@@ -226,7 +228,7 @@ Keep it professional and focused on helping developers understand the example. D
       body: JSON.stringify({
         model: "gpt-4o-mini",
         messages: [{ role: "user", content: prompt }],
-        max_tokens: 500,
+        max_tokens: 150,
         temperature: 0.7,
       }),
     });
@@ -260,10 +262,6 @@ function generateFallbackDescription(testMeta) {
     );
   }
 
-  parts.push(
-    "\nReview the source code below to understand the implementation details and patterns used."
-  );
-
   return parts.join("\n");
 }
 
@@ -397,62 +395,52 @@ description: "${shortDescription.replace(/"/g, '\\"')}"
 icon: "${testMeta.icon}"
 ---
 
-## Overview
-
 ${description}
 
 `;
 
-  // Add Live Test Run section if URL exists
+  // Recording of the latest CI run, if the manifest has one
   if (replayEmbedUrl) {
-    mdx += `## Live Test Run
-
-Watch this test execute in a real sandbox environment:
+    mdx += `## Watch it run
 
 {/* ${testMeta.filename} output */}
-<iframe 
-  src="${replayEmbedUrl}" 
-  width="100%" 
-  height="600" 
+<iframe
+  src="${replayEmbedUrl}"
+  width="100%"
+  height="600"
   style={{ border: "1px solid #333", borderRadius: "8px" }}
   allow="fullscreen"
 />
 
 `;
   } else {
-    mdx += `## Live Test Run
+    mdx += `## Watch it run
 
 <Note>
-  A live test recording will be available after the next CI run.
+  A recording appears here after the next CI run.
 </Note>
 
 `;
   }
 
-  // Add Source Code section
-  mdx += `## Source Code
+  mdx += `## The test
 
 \`\`\`javascript title="${testMeta.filename}"
 ${testMeta.content.trim()}
 \`\`\`
 
-## Running This Example
+## Run it
+
+The test is in the [TestDriver SDK repository](https://github.com/testdriverai/testdriverai/tree/main/examples). Clone it, install dependencies, and run the file:
 
 \`\`\`bash
-# Clone the TestDriver repository
 git clone https://github.com/testdriverai/testdriverai
-
-# Install dependencies
 cd testdriverai
 npm install
-
-# Run this specific example
-vitest run examples/${testMeta.filename}
+npx vitest run examples/${testMeta.filename}
 \`\`\`
 
-<Note>
-  Make sure you have \`TD_API_KEY\` set in your environment. Get one at [testdriver.ai](https://testdriver.ai).
-</Note>
+The test reads your API key from \`TD_API_KEY\`. Create a key at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys). Then set it in your environment or a \`.env\` file.
 `;
 
   return mdx;
@@ -491,8 +479,13 @@ function updateDocsNavigation(docsJson, examplePages, options) {
   }
 
   if (examplesGroup) {
-    // Update existing group
-    examplesGroup.pages = examplesPages;
+    // Keep the hand-picked order of pages already in the sidebar, drop pages
+    // whose test file is gone, and append new examples at the end.
+    const kept = examplesGroup.pages.filter(
+      (p) => typeof p === "string" && examplesPages.includes(p)
+    );
+    const added = examplesPages.filter((p) => !kept.includes(p));
+    examplesGroup.pages = [...kept, ...added];
     if (options.verbose) {
       console.log("🔄 Updated existing Examples group in navigation");
     }

package/docs/agent.mdx

@@ -1,102 +1,183 @@
 ---
-title: "The TestDriver Agent"
+title: "The TestDriver agent"
 sidebarTitle: "Introduction"
-description: "How the TestDriver agent behaves on GitHub issues, pull requests, and @mentions"
+description: "How the TestDriver agent reviews pull requests, builds tests, and answers @mentions on GitHub."
 icon: "hand-horns"
 ---
 
-The TestDriver agent is an AI teammate in your GitHub repository. It is
-**code review that runs your app**. It does not only read a diff and guess
-what can break. It starts a real sandbox, controls the real app, and reports what
-really happens.
-
-## Scope: it only builds and maintains tests
-
-The agent has one purpose. It does one thing: it **writes, debugs, fixes, and keeps
-automated tests** with TestDriver. It reviews pull requests. It writes and runs
-a test against the change. It does not do work that is not in scope. It does not edit
-your application code, fix product bugs, answer other programming questions, or
-act as a general coding assistant.
-
-## How it behaves depends on the surface
-
-The agent reacts to three different GitHub surfaces. Its behavior is
-different on each one.
-
-| Surface | Trigger | What it does |
-|---------|---------|--------------|
-| **Pull request opened** | Automatic (no mention) | Silent, evidence-based **code review** |
-| **Issue opened** | Automatic (no mention) | **Onboarding / test-building** |
-| **@mention** (issue or PR) | You mention the bot | Interactive, chatty conversation |
-
-## Pull requests — automatic code review
-
-When a pull request is **opened**, the agent reviews it automatically. Nobody has
-to ask.
-
-- **The review is the deliverable, not chatter.** No person asks for an automatic review.
-  Thus the agent stays quiet while it works. It posts a **single review
-  comment** at the end. It does not put many inline threads across the diff. It does not
-  tell each step.
-- **It runs the change when it can.** Its default first move is to start a session,
-  work out what the PR changes from a user's point of view, and write and run a
-  TestDriver test that exercises exactly that. A bug it *watched happen* is far
-  more valuable than one it inferred.
-- **Findings are labeled by how they were found.** Each finding is marked
-  `observed` (proven by actually running the change) or `suspected` (reasoned out
-  from reading the diff). If the installation isn't signed in to TestDriver, the
-  agent can't run anything, so it reviews by reading and marks every finding
-  `suspected`.
-- **It focuses on real bugs.** Logic errors, regressions, broken edge cases,
-  mishandled errors — not style, naming, or "consider extracting this."
-- **Zero findings is a good review.** If the change looks correct, it says so in a
-  sentence. If there's nothing worth reviewing (only lockfiles, generated files, or
-  formatting), it posts nothing at all.
-- **It comments, it never blocks.** The review is always a `COMMENT` — it never
-  approves and never requests changes, so it can't gate a merge.
-
-It also fires a native GitHub **Check Run** for the PR's TestDriver suite, and
-re-runs that check on every push (not a full re-review — push more commits and
-@mention the agent if you want it to review again).
-
-<Note>
-  The agent never reviews its own pull requests. PRs opened by the bot are skipped,
-  so it won't wake itself up to review the tests it just committed.
-</Note>
-
-## Issues — onboarding and test building
-
-When an issue is **opened**, the agent treats it as a cue to help you build a test.
-
-- **If the issue describes a task**, it acts on the request — writing or debugging
-  the test you asked for.
-- **If the issue is empty**, it introduces itself, explains that it writes and
-  debugs computer-use tests, and walks you through signing in to TestDriver and
-  creating your first test.
-- **It finishes by opening a pull request** with the test it wrote.
-
-## @mentions — interactive conversation
-
-Mentioning the bot (on either an issue or a PR) starts a **solicited**, interactive
-turn. Because you asked directly, the agent is chatty: it posts progress updates,
-shows you screenshots of what's happening in the sandbox, and answers follow-ups in
-the thread.
-
-On a PR, an @mention overrides the silent auto-review behavior — you'll see the full
-play-by-play instead of just the final review comment.
-
-You can also manage the agent from a comment:
-
-- **`@bot logout`** (or "sign out") revokes the installation's shared TestDriver
-  sign-in and tears down the live sandbox, so the next mention will prompt whoever
-  responds to sign in again.
+The TestDriver agent is an AI teammate that lives in your GitHub repository.
+
+- It reviews every pull request's code for bugs.
+- For user-visible changes, it drives your app in a real sandbox and reports what happened.
+- It writes, runs, and maintains your end-to-end tests.
+
+To install it, see [Add TestDriver to GitHub](/quickstart-github).
+
+## What the agent does
+
+The agent does two jobs:
+
+- **Code review.** It reviews pull requests like a senior engineer. It reads the diff for logic errors, security problems, and regressions. When it can, it runs the change in a sandbox to prove what it finds.
+- **Test building.** It writes new TestDriver tests, debugs and fixes failing ones, and keeps them up to date.
+
+It declines work outside that scope:
+
+- It doesn't edit your application code.
+- It doesn't fix product bugs.
+- It doesn't act as a general coding assistant.
+
+When it finds a bug in a pull request, it reports the bug instead of pushing a fix.
+
+## How it responds on each surface
+
+The agent behaves differently depending on what woke it up:
+
+| Event | Trigger | What the agent does |
+| --- | --- | --- |
+| Pull request opened, or new commits pushed | Automatic | Reviews the change and posts one review comment |
+| Issue opened | Automatic | Acts on the request in the issue, or onboards a new user |
+| @mention on an issue or pull request | You mention the agent | Works with you interactively in the thread |
+
+Automatic turns are unsolicited, so the agent posts only when it has something useful to say.
+
+When you @mention it, someone is waiting. It always replies and narrates its progress.
+
+## Pull request reviews
+
+The agent reviews a pull request without being asked when it's opened or gets new commits.
+
+<Steps>
+  <Step title="Triage the change">
+
+    The agent reads the changed files and decides whether there's anything to review or run.
+
+    A pull request that only touches lockfiles, generated output, or formatting gets an 👀 reaction and no comment.
+
+  </Step>
+  <Step title="Read the code">
+
+    It reviews the diff like a senior engineer. It opens surrounding files only when the diff isn't enough on its own.
+
+    It looks for:
+
+    - Logic errors
+    - Unhandled error paths
+    - Security problems
+    - Race conditions
+    - Broken contracts for callers
+    - Risky logic with no tests
+
+    It skips style issues that a linter would catch.
+
+  </Step>
+  <Step title="Run the change">
+
+    This step runs if the change has a user-visible surface and your installation is signed in to TestDriver. The agent:
+
+    - Starts a sandbox.
+    - Drives the exact flow the diff touches.
+    - Runs any existing tests that cover it.
+    - Writes and runs a new test for the change.
+
+    While it works, a single comment on the pull request shows the latest screenshot. The comment finishes with the run recording.
+
+  </Step>
+  <Step title="Post the review">
+
+    It posts one review comment with:
+
+    - A summary and verdict
+    - A short walkthrough of each meaningful file
+    - Its findings
+
+    On a re-review after a push, it reassesses its earlier findings against the new code. It drops the fixed ones and checks the new commits for regressions.
+
+  </Step>
+</Steps>
+
+### What's in a finding
+
+Each finding has:
+
+- A file and line
+- A severity: `critical`, `major`, `minor`, or `nit`
+- A category
+- A suggested replacement, when the fix is small and certain
+
+Findings are also labelled by how the agent found them:
+
+- **`observed`**: the agent saw the bug happen during a run in the sandbox.
+- **`suspected`**: the agent inferred the bug from reading the code.
+
+If a run confirms a suspected finding, the agent upgrades it to `observed` instead of listing it twice.
+
+If the change looks correct, the review says so in a sentence and has no findings.
+
+### The review never blocks a merge
+
+Reviews are posted as GitHub `COMMENT` reviews. The agent never approves a pull request or requests changes, so it can't gate a merge.
+
+### Tests from a review
+
+During a review, the agent may write a test worth keeping: one that passes, or one that cleanly reproduces a bug.
+
+It opens a separate pull request for that test and links it from the review. The pull request uses a `testdriver/session/…` branch and targets your default branch.
+
+It never pushes to the branch it's reviewing.
+
+### Pull requests the agent skips
+
+- **Draft pull requests** get no review until they're marked ready for review.
+- **Pull requests opened by bots** are never reviewed. This includes the agent's own test pull requests, so it doesn't review its own work.
+- **Teams without a subscription** don't get automatic reviews, because automatic review is a paid feature. If your team has used its allowance, the pull request gets one short notice explaining why there's no review.
+
+## Issues
+
+When an issue is opened, the agent reads its title and description:
+
+- **If the issue describes a test task**, the agent does it. It asks you to sign in only if a step needs it.
+- **If the issue is empty** and you look like a new user, the agent introduces itself. It walks you through signing in to TestDriver and creating your first test.
+- **If the agent can't help with the issue**, such as a product bug report or a feature request, it stays silent instead of posting an off-topic reply.
+
+Whenever the agent creates or changes a test file, it finishes by opening a pull request with the test.
+
+## @mentions
+
+Mention the agent on an issue or pull request to start an interactive conversation. Because you asked directly, the agent:
+
+- Posts progress updates and sandbox screenshots as it works.
+- Answers follow-up questions in the thread.
+- Opens a pull request with any test it writes.
+
+On a pull request, an @mention gets you this play-by-play instead of the quiet automatic review.
+
+### Sign out
+
+To revoke your installation's TestDriver sign-in, mention the agent with `logout`:
+
+```text
+@testdriverai logout
+```
+
+`sign out` and `disconnect` work too.
+
+The agent revokes the installation's shared sign-in and shuts down its live sandbox. The next person to mention it is asked to sign in again.
 
 ## Signing in
 
-Reading a diff needs nothing, but **running** the app needs a TestDriver session,
-which requires the installation to be signed in. Sign-in state doesn't decide
-*whether* the agent reviews — it decides *how good* the review gets. A signed-out
-install still gets its bugs caught from reading the code; signing in upgrades
-findings from `suspected` to `observed`.
+Reading a diff doesn't need a TestDriver account, but running your app does.
+
+When your installation isn't signed in, the agent still reviews pull requests by reading the code. It marks every finding `suspected`.
+
+Signing in lets it run each change, so findings it proves become `observed`.
+
+## Related
 
-test
+<CardGroup cols={2}>
+  <Card title="Add TestDriver to GitHub" icon="github" href="/quickstart-github">
+    Install the GitHub app and get your first review.
+  </Card>
+  <Card title="Run tests in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your TestDriver suite in GitHub Actions and other CI systems.
+  </Card>
+</CardGroup>