testdriverai 7.11.264-test → 7.11.266-canary

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

@@ -15,7 +15,7 @@ Choose where you want to start:
     An AI code reviewer that tests every pull request in a real sandbox.
   </Card>
   <Card title="Claude Code" icon="terminal" href="/quickstart-claude" arrow horizontal>
-    Install the plugin to write and run tests from Claude Code.
+    Install the connector to write and run tests from Claude Code.
   </Card>
   <Card title="VS Code & Cursor" icon="code" href="/quickstart-vscode" arrow horizontal>
     Install the extension to write tests and watch them run live.

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

@@ -1,22 +1,59 @@
 ---
 name: testdriver:quickstart-claude
-description: Install one plugin to get the TestDriver MCP server, agent, and skills in Claude Code.
+description: Install the TestDriver connector from the Claude directory, and Claude Code can drive a live sandbox.
 ---
 <!-- Generated from quickstart-claude.mdx. DO NOT EDIT. -->
 
-Install the TestDriver plugin, and Claude Code can write, run, and debug end-to-end tests in a live sandbox.
+Install the TestDriver connector, and Claude Code can write, run, and debug end-to-end tests in a live sandbox.
 
-The plugin bundles three things:
+The connector is the fastest way to get started: one click, a browser sign-in, and no API key to copy. Connectors you install on claude.ai are available automatically in Claude Code, Claude Desktop, and claude.ai chat.
 
-- The TestDriver MCP server
+## Before you begin
+
+- **[Claude Code](https://code.claude.com)**, signed in with the same account you use on claude.ai.
+- **A TestDriver account.** [Sign up at console.testdriver.ai](https://console.testdriver.ai). The free plan includes 30 testing minutes and needs no credit card.
+
+<Steps>
+  <Step title="Install the connector">
+
+    Open the TestDriver listing in the Claude directory:
+
+    [**claude.ai/directory/testdriver**](https://claude.ai/directory/testdriver)
+
+    Click **Connect**, and sign in to TestDriver when the browser opens.
+
+  </Step>
+  <Step title="Check the connection">
+
+    Start a Claude Code session and run `/mcp`. The `testdriver` server should be listed as connected.
+
+    If it isn't, make sure Claude Code is signed in to the same account where you installed the connector, then restart the session.
+
+  </Step>
+  <Step title="Write your first test">
+
+    Ask Claude Code to drive a browser:
+
+    ```text
+    Use TestDriver to write a test that logs in to https://testdriver-sandbox.vercel.app/login and adds an item to the cart.
+    ```
+
+    Claude starts a sandbox, performs each step, and gets a screenshot after every action. Each tool call also returns the SDK code for that step, which Claude assembles into a runnable [Vitest](https://vitest.dev) test.
+
+    To save and run those tests locally and in CI, [set up a project](/quickstart-manual).
+
+  </Step>
+</Steps>
+
+## Alternative: install the plugin
+
+Prefer everything to run locally, or want the `testdriver` agent and skills bundled in? Install the TestDriver plugin instead. It bundles three things:
+
+- The TestDriver MCP server, run locally over stdio
 - The `testdriver` agent, which builds tests step by step
 - Skills that teach Claude the TestDriver SDK
 
-## Before you begin
-
-- **[Claude Code](https://code.claude.com)** and **Node.js 20.19 or later**, which runs the MCP server.
-- **A TestDriver API key.** Create one at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys).
-- **A project with the TestDriver SDK installed**, so the agent can run the tests it writes. If you don't have one yet, see [Set up a project](/quickstart-manual).
+The plugin requires **Node.js 20.19 or later** and a **TestDriver API key**. Create one at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys).
 
 <Steps>
   <Step title="Set your API key">
@@ -63,7 +100,7 @@ The plugin bundles three things:
 </Steps>
 
 <Tip>
-  Only need TestDriver's tools in chat, without the agent or skills? Add the hosted server instead. It signs in through your browser and needs no API key. See [MCP Setup](/mcp-setup).
+  Using another MCP client, or want to add the hosted server by URL instead? See [MCP Setup](/mcp-setup).
 </Tip>
 
 ## Next steps

package/docs/_scripts/generate-skills.js

@@ -4,15 +4,20 @@ const fs = require("fs");
 const path = require("path");
 
 /**
- * Script to generate MCP skills from the docs/*.mdx files
+ * Script to generate MCP skills from the docs/*.mdx and ai/agents/*.md files
  *
- * This script reads the frontmatter from each mdx file and generates
- * SKILL.md files in the skills/ output directory.
+ * This script reads the frontmatter from each source file and generates
+ * SKILL.md files in the skills/ output directory. Generated skills whose
+ * source file no longer exists are pruned; hand-written skills (without
+ * the generated marker) are left alone.
  */
 
 const DOCS_DIR = path.join(__dirname, "..");
+const AGENTS_DIR = path.join(__dirname, "../../ai/agents");
 const OUTPUT_DIR = path.join(__dirname, "../../ai/skills");
 
+const GENERATED_MARKER = /^<!-- Generated from .* DO NOT EDIT\. -->$/m;
+
 // Parse YAML frontmatter from mdx content
 function parseFrontmatter(content) {
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
@@ -38,12 +43,12 @@ function parseFrontmatter(content) {
 
 // Get skill name from filename (used in SKILL.md frontmatter)
 function getSkillName(filename) {
-  return `testdriver:${filename.replace(".mdx", "")}`;
+  return `testdriver:${path.basename(filename, path.extname(filename))}`;
 }
 
 // Get directory name from filename (Windows-compatible, uses hyphen instead of colon)
 function getDirName(filename) {
-  return `testdriver-${filename.replace(".mdx", "")}`;
+  return `testdriver-${path.basename(filename, path.extname(filename))}`;
 }
 
 // Generate SKILL.md content
@@ -61,27 +66,42 @@ ${body}
 `;
 }
 
-// Process all mdx files
+// Process all source files
 function processFiles() {
   // Ensure output directory exists
   if (!fs.existsSync(OUTPUT_DIR)) {
     fs.mkdirSync(OUTPUT_DIR, { recursive: true });
   }
 
-  const files = fs.readdirSync(DOCS_DIR);
-  const mdxFiles = files.filter(
-    (file) => file.endsWith(".mdx") && !file.startsWith("_")
-  );
+  const sources = [];
 
-  console.log(`Found ${mdxFiles.length} mdx files to process\n`);
+  // docs/*.mdx
+  for (const file of fs.readdirSync(DOCS_DIR)) {
+    if (file.endsWith(".mdx") && !file.startsWith("_")) {
+      sources.push({ dir: DOCS_DIR, file });
+    }
+  }
+
+  // ai/agents/*.md
+  if (fs.existsSync(AGENTS_DIR)) {
+    for (const file of fs.readdirSync(AGENTS_DIR)) {
+      if (file.endsWith(".md") && !file.startsWith("_")) {
+        sources.push({ dir: AGENTS_DIR, file });
+      }
+    }
+  }
+
+  console.log(`Found ${sources.length} source files to process\n`);
 
   let generated = 0;
   let errors = 0;
+  const generatedDirs = new Set();
 
-  for (const file of mdxFiles) {
-    const filePath = path.join(DOCS_DIR, file);
+  for (const { dir, file } of sources) {
+    const filePath = path.join(dir, file);
     const skillName = getSkillName(file);
-    const outputDir = path.join(OUTPUT_DIR, getDirName(file));
+    const dirName = getDirName(file);
+    const outputDir = path.join(OUTPUT_DIR, dirName);
     const outputPath = path.join(outputDir, "SKILL.md");
 
     try {
@@ -95,6 +115,7 @@ function processFiles() {
       }
 
       fs.writeFileSync(outputPath, skillContent, "utf-8");
+      generatedDirs.add(dirName);
       console.log(`✅ ${skillName}`);
       generated++;
     } catch (error) {
@@ -103,19 +124,48 @@ function processFiles() {
     }
   }
 
-  return { generated, errors };
+  const pruned = pruneStaleSkills(generatedDirs);
+
+  return { generated, errors, pruned };
+}
+
+// Remove generated skills whose source file no longer exists.
+// Hand-written skills (without the generated marker) are left alone.
+function pruneStaleSkills(generatedDirs) {
+  let pruned = 0;
+
+  for (const entry of fs.readdirSync(OUTPUT_DIR)) {
+    const skillDir = path.join(OUTPUT_DIR, entry);
+    if (!fs.lstatSync(skillDir).isDirectory()) continue;
+    if (generatedDirs.has(entry)) continue;
+
+    const skillFile = path.join(skillDir, "SKILL.md");
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, "utf-8");
+    if (!GENERATED_MARKER.test(content)) continue;
+
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    console.log(`🗑️  Pruned stale skill: ${entry}`);
+    pruned++;
+  }
+
+  return pruned;
 }
 
 // Main function
 function main() {
-  console.log("🚀 Generating MCP skills from docs/*.mdx files...\n");
-  console.log(`📂 Source: ${DOCS_DIR}`);
+  console.log("🚀 Generating MCP skills from docs/*.mdx and ai/agents/*.md files...\n");
+  console.log(`📂 Sources: ${DOCS_DIR}, ${AGENTS_DIR}`);
   console.log(`📂 Output: ${OUTPUT_DIR}\n`);
 
-  const { generated, errors } = processFiles();
+  const { generated, errors, pruned } = processFiles();
 
   console.log(`\n✨ Complete!`);
   console.log(`   Generated: ${generated} skills`);
+  if (pruned > 0) {
+    console.log(`   Pruned: ${pruned} stale skills`);
+  }
   if (errors > 0) {
     console.log(`   Errors: ${errors}`);
   }
@@ -133,14 +183,16 @@ Options:
   --help, -h    Show this help message
 
 Description:
-  This script generates MCP skill files from the docs/*.mdx documentation.
-  
-  Each .mdx file is converted to a SKILL.md file with:
+  This script generates MCP skill files from the docs/*.mdx documentation
+  and the ai/agents/*.md agent definitions.
+
+  Each source file is converted to a SKILL.md file with:
   - name: testdriver:<filename>
   - description: from frontmatter
-  - Content: the mdx body
-  
-  Output is written to the skills/ directory.
+  - Content: the source body
+
+  Output is written to the ai/skills/ directory. Generated skills whose
+  source file was removed are pruned; hand-written skills are kept.
 `);
   process.exit(0);
 }

package/docs/quickstart-claude.mdx

@@ -1,23 +1,60 @@
 ---
 title: "Add TestDriver to Claude Code"
 sidebarTitle: "Claude Code"
-description: "Install one plugin to get the TestDriver MCP server, agent, and skills in Claude Code."
+description: "Install the TestDriver connector from the Claude directory, and Claude Code can drive a live sandbox."
 icon: "terminal"
 ---
 
-Install the TestDriver plugin, and Claude Code can write, run, and debug end-to-end tests in a live sandbox.
+Install the TestDriver connector, and Claude Code can write, run, and debug end-to-end tests in a live sandbox.
 
-The plugin bundles three things:
+The connector is the fastest way to get started: one click, a browser sign-in, and no API key to copy. Connectors you install on claude.ai are available automatically in Claude Code, Claude Desktop, and claude.ai chat.
 
-- The TestDriver MCP server
+## Before you begin
+
+- **[Claude Code](https://code.claude.com)**, signed in with the same account you use on claude.ai.
+- **A TestDriver account.** [Sign up at console.testdriver.ai](https://console.testdriver.ai). The free plan includes 30 testing minutes and needs no credit card.
+
+<Steps>
+  <Step title="Install the connector">
+
+    Open the TestDriver listing in the Claude directory:
+
+    [**claude.ai/directory/testdriver**](https://claude.ai/directory/testdriver)
+
+    Click **Connect**, and sign in to TestDriver when the browser opens.
+
+  </Step>
+  <Step title="Check the connection">
+
+    Start a Claude Code session and run `/mcp`. The `testdriver` server should be listed as connected.
+
+    If it isn't, make sure Claude Code is signed in to the same account where you installed the connector, then restart the session.
+
+  </Step>
+  <Step title="Write your first test">
+
+    Ask Claude Code to drive a browser:
+
+    ```text
+    Use TestDriver to write a test that logs in to https://testdriver-sandbox.vercel.app/login and adds an item to the cart.
+    ```
+
+    Claude starts a sandbox, performs each step, and gets a screenshot after every action. Each tool call also returns the SDK code for that step, which Claude assembles into a runnable [Vitest](https://vitest.dev) test.
+
+    To save and run those tests locally and in CI, [set up a project](/quickstart-manual).
+
+  </Step>
+</Steps>
+
+## Alternative: install the plugin
+
+Prefer everything to run locally, or want the `testdriver` agent and skills bundled in? Install the TestDriver plugin instead. It bundles three things:
+
+- The TestDriver MCP server, run locally over stdio
 - The `testdriver` agent, which builds tests step by step
 - Skills that teach Claude the TestDriver SDK
 
-## Before you begin
-
-- **[Claude Code](https://code.claude.com)** and **Node.js 20.19 or later**, which runs the MCP server.
-- **A TestDriver API key.** Create one at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys).
-- **A project with the TestDriver SDK installed**, so the agent can run the tests it writes. If you don't have one yet, see [Set up a project](/quickstart-manual).
+The plugin requires **Node.js 20.19 or later** and a **TestDriver API key**. Create one at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys).
 
 <Steps>
   <Step title="Set your API key">
@@ -64,7 +101,7 @@ The plugin bundles three things:
 </Steps>
 
 <Tip>
-  Only need TestDriver's tools in chat, without the agent or skills? Add the hosted server instead. It signs in through your browser and needs no API key. See [MCP Setup](/mcp-setup).
+  Using another MCP client, or want to add the hosted server by URL instead? See [MCP Setup](/mcp-setup).
 </Tip>
 
 ## Next steps

package/docs/quickstart.mdx

@@ -17,7 +17,7 @@ Choose where you want to start:
     An AI code reviewer that tests every pull request in a real sandbox.
   </Card>
   <Card title="Claude Code" icon="terminal" href="/quickstart-claude" arrow horizontal>
-    Install the plugin to write and run tests from Claude Code.
+    Install the connector to write and run tests from Claude Code.
   </Card>
   <Card title="VS Code & Cursor" icon="code" href="/quickstart-vscode" arrow horizontal>
     Install the extension to write tests and watch them run live.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.11.264-test",
+  "version": "7.11.266-canary",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -80,7 +80,7 @@
     "generate-report": "junit-viewer --results=out.xml --save=report.html",
     "serve-report": "npx http-server . -p 8080 -o report.html",
     "report": "npm run generate-report && npm run serve-report",
-    "generate:skills": "node scripts/generate-skills.js",
+    "generate:skills": "node docs/_scripts/generate-skills.js",
     "build:mcp": "cd mcp-server && npm ci && npm run build",
     "prepublishOnly": "npm run build:mcp"
   },

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

@@ -1,204 +0,0 @@
----
-name: testdriver:ai
-description: Execute natural language tasks using AI
----
-<!-- Generated from ai.mdx. DO NOT EDIT. -->
-
-## Overview
-
-The `ai()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
-
-## Syntax
-
-```javascript
-await testdriver.ai(task, options)
-```
-
-## Parameters
-
-<ParamField path="task" type="string" required>
-  Natural language description of what to do
-</ParamField>
-
-<ParamField path="options" type="object">
-  Execution options
-  
-  <Expandable title="properties">
-    <ParamField path="validateAndLoop" type="boolean" default="false">
-      Whether to validate completion and retry if incomplete
-    </ParamField>
-  </Expandable>
-</ParamField>
-
-## Returns
-
-`Promise<string | void>` - Final AI response if `validateAndLoop` is true
-
-## Examples
-
-### Basic Usage
-
-```javascript
-// Simple task execution
-await testdriver.ai('Click the submit button');
-
-// Complex multi-step task
-await testdriver.ai('Fill out the contact form and submit it');
-
-// Navigation task
-await testdriver.ai('Go to the settings page and enable notifications');
-```
-
-### With Validation
-
-```javascript
-// AI will verify the task completed successfully
-const result = await testdriver.ai('Complete the checkout process', { 
-  validateAndLoop: true 
-});
-
-console.log('Task result:', result);
-```
-
-### Multi-Step Workflows
-
-```javascript
-// The AI will break down complex tasks
-await testdriver.ai('Search for "laptop", add the first result to cart, and proceed to checkout');
-
-// UI exploration
-await testdriver.ai('Find and click all menu items to explore the application');
-```
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Exploratory Testing">
-    Use AI to explore unfamiliar applications:
-    
-    ```javascript
-    await testdriver.ai('Explore the main navigation menu');
-    await testdriver.ai('Try to find the user profile settings');
-    ```
-  </Accordion>
-  
-  <Accordion title="Complex Workflows">
-    Let AI handle multi-step processes:
-    
-    ```javascript
-    await testdriver.ai('Complete the multi-step registration form');
-    await testdriver.ai('Configure all the advanced settings to default values');
-    ```
-  </Accordion>
-  
-  <Accordion title="Flexible Interactions">
-    When exact element locations aren't critical:
-    
-    ```javascript
-    await testdriver.ai('Close any popup dialogs');
-    await testdriver.ai('Accept the cookie consent if it appears');
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Best Practices
-
-<Check>
-  **Be specific but flexible**: Give enough context without over-constraining the AI
-  
-  ```javascript
-  // ✅ Good
-  await testdriver.ai('Add the first product to the shopping cart');
-  
-  // ❌ Too vague
-  await testdriver.ai('do something');
-  
-  // ❌ Too specific (defeats the purpose)
-  await testdriver.ai('click at coordinates 500, 300');
-  ```
-</Check>
-
-<Check>
-  **Use for exploration, not precision**: For critical assertions, use explicit methods
-  
-  ```javascript
-  // Use AI for setup
-  await testdriver.ai('Navigate to the login page');
-  
-  // Use explicit methods for critical steps
-  const usernameField = await testdriver.find('username input');
-  await usernameField.click();
-  await testdriver.type('testuser');
-  
-  await testdriver.assert('login page is displayed');
-  ```
-</Check>
-
-<Warning>
-  **AI tasks may be slower**: The AI needs to analyze the screen and plan actions. For performance-critical tests, use explicit methods.
-</Warning>
-
-## When to Use AI vs Explicit Methods
-
-### Use `ai()` when:
-- Exploring unfamiliar applications
-- Handling optional UI elements (popups, cookies, etc.)
-- Prototyping tests quickly
-- Tasks where exact steps may vary
-
-### Use explicit methods when:
-- Performance is critical
-- You need precise control
-- Making assertions
-- Debugging test failures
-- Repetitive, predictable actions
-
-## Complete Example
-
-```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('E-commerce Flow with AI', () => {
-  let testdriver;
-
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
-
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
-
-  it('should complete shopping flow using AI assistance', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Use AI for navigation and exploration
-    await testdriver.ai('Browse to the electronics section');
-    await testdriver.ai('Find and add a laptop to the cart');
-    
-    // Use explicit methods for critical steps
-    const cartIcon = await testdriver.find('shopping cart icon');
-    await cartIcon.click();
-    
-    const total = await testdriver.extract('the cart total amount');
-    console.log('Cart total:', total);
-    
-    // Use AI for checkout flow
-    await testdriver.ai('Proceed to checkout and fill in shipping details', {
-      validateAndLoop: true
-    });
-    
-    // Explicit assertion
-    await testdriver.assert('order confirmation page is displayed');
-  });
-});
-```
-
-## Related Methods
-
-- [`find()`](/v7/find) - Locate specific elements
-- [`assert()`](/v7/assert) - Make assertions
-- [`extract()`](/v7/extract) - Extract information