testdriverai 7.2.46 → 7.2.48

package/testdriver-plugin/skills/self-hosting/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: self-hosting
+description: Self-host TestDriver sandboxes. Use when running Windows tests on AWS, configuring custom AMIs, or setting up your own infrastructure.
+---
+
+# Self-Hosting
+
+Read: `node_modules/testdriverai/docs/v7/self-hosted.mdx`
+Read: `node_modules/testdriverai/docs/v7/aws-setup.mdx`
+
+## When to Self-Host
+
+- **Windows testing** - Required for Windows sandboxes
+- **Custom environments** - Special software or configurations
+- **Data compliance** - Keep tests in your own infrastructure
+- **Performance** - Reduce latency with regional instances
+
+## AWS Setup for Windows
+
+### Prerequisites
+1. AWS account with EC2 access
+2. TestDriver Windows AMI (contact support)
+3. VPC with public subnet
+
+### Required Environment Variables
+
+```bash
+TD_API_KEY=your_api_key
+TD_OS=windows
+AWS_REGION=us-east-2
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+AMI_ID=ami-0dd5fa241273a7d50
+AWS_LAUNCH_TEMPLATE_ID=lt-0ef9bf26a945fb442
+```
+
+### Launch Template Configuration
+
+Create an EC2 launch template with:
+- Instance type: `c5.xlarge` or larger
+- AMI: TestDriver Windows AMI
+- Security group: Allow RDP (3389) and TestDriver ports
+- IAM role: EC2 permissions for your use case
+
+### Running Windows Tests
+
+```bash
+TD_OS=windows npx vitest run tests/windows-app.test.mjs
+```
+
+## Test Configuration
+
+```javascript
+const testdriver = TestDriver(context, {
+  os: 'windows',  // Use Windows sandbox
+});
+
+await testdriver.provision.chrome({ url: 'https://example.com' });
+// or
+await testdriver.provision.installer({
+  url: 'https://example.com/app.msi',
+  launch: true,
+});
+```
+
+## Windows-Specific Examples
+
+- `node_modules/testdriverai/examples/windows-installer.test.mjs`
+- `node_modules/testdriverai/examples/exec-pwsh.test.mjs`
+
+## PowerShell Execution
+
+```javascript
+// Run PowerShell commands on Windows
+const result = await testdriver.exec("pwsh", "Get-Date", 5000);
+const files = await testdriver.exec("pwsh", "Get-ChildItem C:\\", 5000);
+```
+
+## Troubleshooting
+
+**Instance not starting?**
+- Check AWS credentials and permissions
+- Verify launch template exists
+- Check AMI is available in your region
+
+**Connection timeout?**
+- Security group must allow inbound traffic
+- Instance needs public IP or NAT gateway
+- Check TestDriver agent is running on AMI

package/testdriver-plugin/skills/setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: setup
+description: Set up TestDriver in a project. Use when installing testdriverai, configuring vitest, setting up TD_API_KEY, or initializing a new test project.
+---
+
+# Setting Up TestDriver
+
+Read the quickstart guide: `node_modules/testdriverai/docs/v7/quickstart.mdx`
+
+## Requirements
+
+1. **API Key** from [console.testdriver.ai/team](https://console.testdriver.ai/team)
+2. **Node.js** and **Vitest**
+
+## Setup Steps
+
+### 1. Install TestDriver
+
+```bash
+npm install testdriverai vitest dotenv --save-dev
+```
+
+### 2. Create `.env` file
+
+```bash
+TD_API_KEY=your_api_key_here
+```
+
+### 3. Create `vitest.config.mjs`
+
+```javascript
+import { config } from 'dotenv';
+import TestDriver from 'testdriverai/vitest';
+import { defineConfig } from 'vitest/config';
+
+config();
+
+const setupFiles = ['testdriverai/vitest/setup', 'testdriverai/vitest/setup-aws'];
+
+export default defineConfig({
+  test: {
+    testTimeout: 900000,
+    hookTimeout: 900000,
+    disableConsoleIntercept: true,
+    maxConcurrency: 3,
+    reporters: ['default', TestDriver(), ['junit', { outputFile: 'test-report.junit.xml' }]],
+    setupFiles,
+  },
+});
+```
+
+### 4. Add to `.gitignore`
+
+```
+.env
+```
+
+## Verify Setup
+
+Create a test file `tests/example.test.mjs`:
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Setup Test", () => {
+  it("should load a page", async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://example.com' });
+    const result = await testdriver.assert("Example Domain heading is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+Run: `npx vitest run tests/example.test.mjs`

package/testdriver-plugin/skills/variables/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: variables
+description: Use variables in TestDriver tests. Use when parameterizing tests, using environment variables, or passing data between test steps.
+---
+
+# Using Variables
+
+Read: `node_modules/testdriverai/docs/v7/variables.mdx`
+
+## Environment Variables
+
+Access via `process.env`:
+
+```javascript
+const username = process.env.TEST_USERNAME;
+const password = process.env.TEST_PASSWORD;
+
+await testdriver.find("Username input").click();
+await testdriver.type(username);
+```
+
+## .env File
+
+Create `.env` in project root:
+
+```bash
+TD_API_KEY=your_api_key
+TEST_USERNAME=testuser@example.com
+TEST_PASSWORD=testpass123
+BASE_URL=https://staging.example.com
+```
+
+Load with dotenv (already configured in vitest.config.mjs):
+
+```javascript
+import { config } from 'dotenv';
+config();
+```
+
+## Parameterized Tests
+
+```javascript
+const testCases = [
+  { email: 'user1@test.com', expected: 'Welcome User 1' },
+  { email: 'user2@test.com', expected: 'Welcome User 2' },
+];
+
+describe("Login Tests", () => {
+  testCases.forEach(({ email, expected }) => {
+    it(`should login ${email}`, async (context) => {
+      const testdriver = TestDriver(context);
+      await testdriver.provision.chrome({ url: process.env.BASE_URL });
+      
+      await testdriver.find("Email input").click();
+      await testdriver.type(email);
+      
+      const result = await testdriver.assert(`page shows '${expected}'`);
+      expect(result).toBeTruthy();
+    });
+  });
+});
+```
+
+## Sharing Data Between Steps
+
+```javascript
+it("should complete flow", async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://example.com' });
+  
+  // Get data from page
+  const orderId = await testdriver.exec("js", 
+    "return document.querySelector('.order-id').textContent", 
+    5000
+  );
+  
+  // Use in later assertions
+  const result = await testdriver.assert(`Order ${orderId} is confirmed`);
+  expect(result).toBeTruthy();
+});
+```
+
+## Dynamic URLs
+
+```javascript
+const baseUrl = process.env.BASE_URL || 'https://localhost:3000';
+await testdriver.provision.chrome({ url: `${baseUrl}/login` });
+```

package/testdriver-plugin/skills/waiting/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: waiting
+description: Wait for elements in TestDriver tests. Use when polling for elements, waiting for page loads, handling loading states, or setting timeouts.
+---
+
+# Waiting for Elements
+
+Read: `node_modules/testdriverai/docs/v7/waiting-for-elements.mdx`
+
+## Polling with Timeout
+
+Use the `timeout` option to poll until an element is found:
+
+```javascript
+// Retries every 5 seconds until found or timeout
+const element = await testdriver.find("Success message", { timeout: 30000 });
+```
+
+## Wait for Page Load
+
+```javascript
+// Assert something visible after load
+await testdriver.assert("Page has finished loading");
+
+// Or check for specific content
+await testdriver.assert("Welcome message is visible");
+```
+
+## Wait via Assertion
+
+```javascript
+// This will wait and retry until true or timeout
+const loaded = await testdriver.assert("The dashboard has fully loaded");
+expect(loaded).toBeTruthy();
+```
+
+## Wait via exec (JavaScript)
+
+```javascript
+await testdriver.exec("js", `
+  await new Promise(resolve => {
+    const check = () => {
+      if (document.querySelector('.loaded')) resolve();
+      else setTimeout(check, 100);
+    };
+    check();
+  });
+`, 10000);
+```
+
+## Common Patterns
+
+### Wait for element to disappear
+```javascript
+// Keep checking until loading spinner is gone
+let spinner = await testdriver.find("Loading spinner");
+while (spinner.found()) {
+  await new Promise(r => setTimeout(r, 1000));
+  spinner = await testdriver.find("Loading spinner");
+}
+```
+
+### Wait between actions
+```javascript
+await button.click();
+await new Promise(r => setTimeout(r, 2000));  // Wait 2 seconds
+await testdriver.assert("Result is visible");
+```
+
+## Examples
+
+See `node_modules/testdriverai/docs/guide/best-practices-polling.mdx`

package/examples/github-actions.yml

@@ -1,68 +0,0 @@
-name: TestDriver Tests with GitHub Comments
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-  push:
-    branches: [main, develop]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    
-    permissions:
-      # Required for posting comments on PRs
-      pull-requests: write
-      # Required for posting comments on commits
-      contents: write
-    
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-      
-      - name: Install dependencies
-        run: npm ci
-      
-      - name: Run TestDriver tests
-        env:
-          # TestDriver API key (add this to your repository secrets)
-          TD_API_KEY: ${{ secrets.TD_API_KEY }}
-          
-          # GitHub token for posting comments (automatically provided)
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          
-          # PR number for PR comments
-          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
-          
-          # Git information (automatically available)
-          # GITHUB_SHA, GITHUB_REF_NAME, GITHUB_REPOSITORY, GITHUB_ACTOR
-          
-        run: npm run test:sdk
-        
-      - name: Upload test results
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-results
-          path: |
-            test-report.junit.xml
-            test-results/
-          retention-days: 30
-      
-      - name: Comment PR on failure
-        if: failure() && github.event_name == 'pull_request'
-        uses: actions/github-script@v7
-        with:
-          script: |
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: '❌ TestDriver tests failed. Check the workflow logs for details.'
-            })

package/examples/run-tests-with-recording.sh

@@ -1,70 +0,0 @@
-#!/bin/bash
-
-# Example script showing how to run tests with TestDriver + Dashcam integration
-# This script demonstrates the complete flow:
-# 1. Start dashcam
-# 2. Run tests with Vitest reporter
-# 3. Stop and publish dashcam recording
-# 4. View results in TestDriver dashboard
-
-set -e
-
-echo "======================================"
-echo "TestDriver + Dashcam Test Recording"
-echo "======================================"
-echo ""
-
-# Check for required environment variables
-if [ -z "$TD_API_KEY" ]; then
-  echo "Error: TD_API_KEY environment variable is required"
-  echo "Get your API key from: https://console.testdriver.ai/settings/api-keys"
-  exit 1
-fi
-
-if [ -z "$DASHCAM_PROJECT_ID" ]; then
-  echo "Warning: DASHCAM_PROJECT_ID not set, replays won't be published"
-fi
-
-# Start Dashcam recording
-echo "📹 Starting Dashcam..."
-dashcam start
-
-# Track test logs
-echo "📝 Tracking test output..."
-dashcam track --name="TestDriver Tests" --type=application --pattern="*.log"
-
-echo ""
-
-# Run tests with Vitest and TestDriver reporter
-echo "🧪 Running tests..."
-npx vitest run --config vitest.config.example.js
-
-# Capture exit code
-TEST_EXIT_CODE=$?
-
-# Stop dashcam
-echo ""
-echo "🛑 Stopping Dashcam..."
-dashcam stop
-
-# Publish to dashcam project if configured
-if [ -n "$DASHCAM_PROJECT_ID" ]; then
-  echo "📤 Publishing replay to project: $DASHCAM_PROJECT_ID"
-  REPLAY_URL=$(dashcam publish -p "$DASHCAM_PROJECT_ID" --json | jq -r '.replayUrl')
-  echo "✅ Replay URL: $REPLAY_URL"
-  echo ""
-  echo "View your test recording at:"
-  echo "$REPLAY_URL"
-else
-  echo "⚠️  Skipping publish (DASHCAM_PROJECT_ID not set)"
-fi
-
-echo ""
-echo "======================================"
-echo "📊 View Results"
-echo "======================================"
-echo "Dashboard: https://console.testdriver.ai/dashboard/test-runs"
-echo ""
-
-# Exit with the same code as tests
-exit $TEST_EXIT_CODE

package/examples/screenshot-example.js

@@ -1,63 +0,0 @@
-/**
- * TestDriver SDK - Screenshot Example
- *
- * This example demonstrates how to use the screenshot() method
- * to capture screenshots of the sandbox environment.
- */
-
-const TestDriver = require("../sdk.js");
-const fs = require("fs");
-const path = require("path");
-
-async function main() {
-  // Initialize TestDriver SDK
-  const client = new TestDriver(process.env.TD_API_KEY);
-
-  try {
-    // Connect to sandbox
-    console.log("Connecting to sandbox...");
-    await client.connect();
-
-    // Navigate to a website
-    console.log("Opening Chrome and navigating to example.com...");
-    await client.focusApplication("Google Chrome");
-    const urlBar = await client.find("URL bar in Chrome");
-    await urlBar.click();
-    await client.type("https://example.com");
-    await client.pressKeys(["enter"]);
-
-    // Wait a moment for page to load
-    await client.wait(2000);
-
-    // Capture a screenshot
-    console.log("Capturing screenshot...");
-    const screenshot = await client.screenshot();
-
-    // Save screenshot to file
-    const outputPath = path.join(__dirname, "example-screenshot.png");
-    fs.writeFileSync(outputPath, Buffer.from(screenshot, "base64"));
-    console.log(`Screenshot saved to: ${outputPath}`);
-
-    // You can also capture with the mouse cursor visible
-    console.log("Capturing screenshot with mouse cursor...");
-    await client.hover(400, 300);
-    const screenshotWithMouse = await client.screenshot(1, false, true);
-
-    const outputPathWithMouse = path.join(
-      __dirname,
-      "example-screenshot-with-mouse.png",
-    );
-    fs.writeFileSync(
-      outputPathWithMouse,
-      Buffer.from(screenshotWithMouse, "base64"),
-    );
-    console.log(`Screenshot with mouse saved to: ${outputPathWithMouse}`);
-  } catch (error) {
-    console.error("Error:", error);
-  } finally {
-    // Clean up
-    await client.disconnect();
-  }
-}
-
-main();