testdriverai 7.2.3 → 7.2.10

package/docs/v7/_drafts/screenshot.mdx

@@ -0,0 +1,155 @@
+---
+title: "screenshot()"
+sidebarTitle: "screenshot"
+description: "Capture a screenshot of the current screen"
+icon: "camera"
+---
+
+## Overview
+
+Capture a screenshot of the current sandbox screen. Returns a base64 encoded PNG, or saves directly to a file and returns the filepath.
+
+## Syntax
+
+```javascript
+// Options object (recommended)
+await testdriver.screenshot(options)
+
+// Legacy positional arguments
+await testdriver.screenshot(scale, silent, mouse)
+```
+
+## Parameters
+
+<ParamField path="options" type="object">
+  Options object for screenshot capture
+</ParamField>
+
+<ParamField path="options.scale" type="number" default="1">
+  Scale factor for the screenshot (1 = original size, 0.5 = half size, etc.)
+</ParamField>
+
+<ParamField path="options.silent" type="boolean" default="false">
+  Whether to suppress logging output
+</ParamField>
+
+<ParamField path="options.mouse" type="boolean" default="false">
+  Whether to include the mouse cursor in the screenshot
+</ParamField>
+
+<ParamField path="options.path" type="string">
+  File path to save the screenshot. If provided, the screenshot is saved to this file and the filepath is returned instead of base64 data. Directories are created automatically if they don't exist.
+</ParamField>
+
+## Returns
+
+`Promise<string>` - Base64 encoded PNG screenshot, or the filepath if `options.path` was provided.
+
+## Examples
+
+### Basic Screenshot (Base64)
+
+```javascript
+// Capture a screenshot and get base64 data
+const screenshot = await testdriver.screenshot();
+
+// Write to file manually
+import fs from 'fs';
+fs.writeFileSync('screenshot.png', Buffer.from(screenshot, 'base64'));
+```
+
+### Save Directly to File
+
+```javascript
+// Save screenshot directly to a file (returns filepath)
+const filepath = await testdriver.screenshot({ path: './screenshots/test.png' });
+console.log(`Screenshot saved to: ${filepath}`);
+```
+
+### With Mouse Cursor
+
+```javascript
+// Include mouse cursor in screenshot
+const screenshot = await testdriver.screenshot({ mouse: true });
+
+// Or save to file with mouse cursor
+const filepath = await testdriver.screenshot({ 
+  path: './debug/with-cursor.png',
+  mouse: true 
+});
+```
+
+### Scaled Screenshot
+
+```javascript
+// Capture at half size (useful for reducing file size)
+const screenshot = await testdriver.screenshot({ scale: 0.5 });
+
+// Capture at double size
+const filepath = await testdriver.screenshot({ 
+  path: './hires.png',
+  scale: 2 
+});
+```
+
+### Silent Mode
+
+```javascript
+// Capture without logging output
+const screenshot = await testdriver.screenshot({ silent: true });
+```
+
+### Legacy Usage
+
+```javascript
+// Legacy positional arguments still work
+const screenshot = await testdriver.screenshot(1, false, true);
+// Equivalent to: screenshot({ scale: 1, silent: false, mouse: true })
+```
+
+## Use Cases
+
+### Debugging Test Failures
+
+```javascript
+it('should complete checkout', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  await testdriver.provision.chrome({ url: 'https://shop.example.com' });
+
+  try {
+    await testdriver.find('Checkout button').click();
+    await testdriver.assert('Order confirmation is visible');
+  } catch (error) {
+    // Save screenshot on failure for debugging
+    await testdriver.screenshot({ path: './failures/checkout-failed.png' });
+    throw error;
+  }
+});
+```
+
+### Visual Documentation
+
+```javascript
+// Capture screenshots at each step for documentation
+await testdriver.screenshot({ path: './docs/step1-login.png' });
+await testdriver.find('Login button').click();
+await testdriver.screenshot({ path: './docs/step2-dashboard.png' });
+```
+
+### Comparing States
+
+```javascript
+// Capture before and after states
+const before = await testdriver.screenshot();
+await testdriver.find('Toggle dark mode').click();
+const after = await testdriver.screenshot();
+
+// Both are base64 - can be compared or stored
+```
+
+## Notes
+
+- Screenshots are captured from the sandbox's virtual display
+- The base64 string does not include a data URI prefix (raw base64)
+- When using `path`, directories are created automatically if they don't exist
+- File format is always PNG regardless of the file extension used

package/docs/v7/_drafts/test-recording.mdx

@@ -376,12 +376,6 @@ const run2 = await client.createTestRun({
 - Associated dashcam replay
 - Timing and duration
 
-### TdSandbox
-- VM/sandbox lifecycle tracking
-- Platform and OS information
-- Dashcam integration status
-- Cost and usage metrics
-
 ### Replay
 - Dashcam recordings
 - Linked to test runs and cases

package/docs/v7/_drafts/writing-tests.mdx

@@ -0,0 +1,25 @@
+---
+title: "Writing Tests"
+description: "Learn how to write effective TestDriver tests with natural language"
+icon: "pencil"
+---
+
+Learn how to write effective TestDriver tests. This section covers everything from generating tests with AI to making assertions.
+
+<CardGroup cols={2}>
+  <Card title="Generating Tests" icon="wand-magic-sparkles" href="./generating-tests">
+    Use AI coding agents and exploration mode to generate tests
+  </Card>
+  <Card title="Locating Elements" icon="crosshairs" href="./locating-elements">
+    Find UI elements using natural language descriptions
+  </Card>
+  <Card title="Waiting for Elements" icon="clock" href="./waiting-for-elements">
+    Handle async operations and prevent flaky tests
+  </Card>
+  <Card title="Performing Actions" icon="computer-mouse" href="./performing-actions">
+    Click, type, hover, scroll and more
+  </Card>
+  <Card title="Making Assertions" icon="check-double" href="./making-assertions">
+    Verify application state with AI-powered assertions
+  </Card>
+</CardGroup>

package/docs/v7/{api/act.mdx → ai.mdx}

@@ -1,18 +1,19 @@
 ---
-title: "act()"
-sidebarTitle: "act"
+title: "ai()"
+sidebarTitle: "ai"
 description: "Execute natural language tasks using AI"
 icon: "wand-magic-sparkles"
+tag: beta
 ---
 
 ## Overview
 
-The `act()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
+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.act(task, options)
+await testdriver.ai(task, options)
 ```
 
 ## Parameters
@@ -41,20 +42,20 @@ await testdriver.act(task, options)
 
 ```javascript
 // Simple task execution
-await testdriver.act('Click the submit button');
+await testdriver.ai('Click the submit button');
 
 // Complex multi-step task
-await testdriver.act('Fill out the contact form and submit it');
+await testdriver.ai('Fill out the contact form and submit it');
 
 // Navigation task
-await testdriver.act('Go to the settings page and enable notifications');
+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.act('Complete the checkout process', { 
+const result = await testdriver.ai('Complete the checkout process', { 
   validateAndLoop: true 
 });
 
@@ -65,10 +66,10 @@ console.log('Task result:', result);
 
 ```javascript
 // The AI will break down complex tasks
-await testdriver.act('Search for "laptop", add the first result to cart, and proceed to checkout');
+await testdriver.ai('Search for "laptop", add the first result to cart, and proceed to checkout');
 
 // UI exploration
-await testdriver.act('Find and click all menu items to explore the application');
+await testdriver.ai('Find and click all menu items to explore the application');
 ```
 
 ## Use Cases
@@ -78,8 +79,8 @@ await testdriver.act('Find and click all menu items to explore the application')
     Use AI to explore unfamiliar applications:
     
     ```javascript
-    await testdriver.act('Explore the main navigation menu');
-    await testdriver.act('Try to find the user profile settings');
+    await testdriver.ai('Explore the main navigation menu');
+    await testdriver.ai('Try to find the user profile settings');
     ```
   </Accordion>
   
@@ -87,8 +88,8 @@ await testdriver.act('Find and click all menu items to explore the application')
     Let AI handle multi-step processes:
     
     ```javascript
-    await testdriver.act('Complete the multi-step registration form');
-    await testdriver.act('Configure all the advanced settings to default values');
+    await testdriver.ai('Complete the multi-step registration form');
+    await testdriver.ai('Configure all the advanced settings to default values');
     ```
   </Accordion>
   
@@ -96,8 +97,8 @@ await testdriver.act('Find and click all menu items to explore the application')
     When exact element locations aren't critical:
     
     ```javascript
-    await testdriver.act('Close any popup dialogs');
-    await testdriver.act('Accept the cookie consent if it appears');
+    await testdriver.ai('Close any popup dialogs');
+    await testdriver.ai('Accept the cookie consent if it appears');
     ```
   </Accordion>
 </AccordionGroup>
@@ -109,13 +110,13 @@ await testdriver.act('Find and click all menu items to explore the application')
   
   ```javascript
   // ✅ Good
-  await testdriver.act('Add the first product to the shopping cart');
+  await testdriver.ai('Add the first product to the shopping cart');
   
   // ❌ Too vague
-  await testdriver.act('do something');
+  await testdriver.ai('do something');
   
   // ❌ Too specific (defeats the purpose)
-  await testdriver.act('click at coordinates 500, 300');
+  await testdriver.ai('click at coordinates 500, 300');
   ```
 </Check>
 
@@ -124,7 +125,7 @@ await testdriver.act('Find and click all menu items to explore the application')
   
   ```javascript
   // Use AI for setup
-  await testdriver.act('Navigate to the login page');
+  await testdriver.ai('Navigate to the login page');
   
   // Use explicit methods for critical steps
   const usernameField = await testdriver.find('username input');
@@ -141,7 +142,7 @@ await testdriver.act('Find and click all menu items to explore the application')
 
 ## When to Use AI vs Explicit Methods
 
-### Use `act()` when:
+### Use `ai()` when:
 - Exploring unfamiliar applications
 - Handling optional UI elements (popups, cookies, etc.)
 - Prototyping tests quickly
@@ -177,8 +178,8 @@ describe('E-commerce Flow with AI', () => {
     await testdriver.focusApplication('Google Chrome');
     
     // Use AI for navigation and exploration
-    await testdriver.act('Browse to the electronics section');
-    await testdriver.act('Find and add a laptop to the cart');
+    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');
@@ -188,7 +189,7 @@ describe('E-commerce Flow with AI', () => {
     console.log('Cart total:', total);
     
     // Use AI for checkout flow
-    await testdriver.act('Proceed to checkout and fill in shipping details', {
+    await testdriver.ai('Proceed to checkout and fill in shipping details', {
       validateAndLoop: true
     });
     
@@ -200,6 +201,6 @@ describe('E-commerce Flow with AI', () => {
 
 ## Related Methods
 
-- [`find()`](/v7/api/find) - Locate specific elements
-- [`assert()`](/v7/api/assert) - Make assertions
-- [`extract()`](/v7/api/extract) - Extract information
+- [`find()`](/v7/find) - Locate specific elements
+- [`assert()`](/v7/assert) - Make assertions
+- [`extract()`](/v7/extract) - Extract information

package/docs/v7/{api/assert.mdx → assert.mdx}

@@ -280,6 +280,6 @@ describe('Assertions', () => {
 
 ## Related Methods
 
-- [`extract()`](/v7/api/extract) - Extract information for detailed assertions
-- [`find()`](/v7/api/find) - Locate elements to verify
-- [`ai()`](/v7/api/ai) - Complex AI-driven tasks
+- [`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/aws-setup.mdx

@@ -0,0 +1,338 @@
+---
+title: "AWS Setup Guide"
+sidebarTitle: "AWS Setup"
+description: "Deploy TestDriver on your AWS infrastructure using CloudFormation"
+icon: "aws"
+---
+
+This guide walks you through setting up self-hosted TestDriver instances on AWS. By the end, you'll have a complete infrastructure that can spawn test environments on-demand and integrate with your CI/CD pipelines.
+
+```mermaid
+graph LR
+    A[Vitest] <--> B[api.testdriver.ai]
+    B <--> C[Your AWS EC2 Instance]
+```
+
+## Overview
+
+The setup process involves three main steps:
+
+1. **CloudFormation Infrastructure** — Deploy our template to create VPC, security groups, IAM roles, and launch templates
+2. **On-Demand Instance Spawning** — Use `spawn-runner.sh` to launch TestDriver instances when you need to run tests
+3. **CI/CD Integration** — Automate the lifecycle in GitHub Actions: spawn instance → run tests → terminate instance
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- AWS account with CloudFormation permissions
+- [AWS CLI](https://aws.amazon.com/cli/) installed and configured (`aws configure`)
+- Access to the TestDriver AMI — [Contact us](https://form.typeform.com/to/UECf9rDx?typeform-source=testdriver.ai) with your AWS region
+- A GitHub repository for your tests
+
+<Tip>
+  The TestDriver Golden Image AMI ID is `ami-086b5b4b86d78987c`. Contact us to get access in your preferred AWS region.
+</Tip>
+
+## Step 1: Deploy CloudFormation Stack
+
+Our CloudFormation template creates all the AWS infrastructure you need:
+
+- Dedicated VPC with public subnet
+- Security group with required port access
+- IAM roles and instance profiles
+- EC2 launch template for instance creation
+
+Download the template from the [TestDriver CLI repository](https://github.com/testdriverai/testdriverai/tree/main/setup/aws/cloudformation.yaml), then deploy:
+
+```bash
+aws cloudformation deploy \
+  --template-file setup/aws/cloudformation.yaml \
+  --stack-name testdriver-infrastructure \
+  --parameter-overrides \
+    ProjectTag=testdriver \
+    AllowedIngressCidr=0.0.0.0/0 \
+    InstanceType=c5.xlarge \
+    CreateKeyPair=true \
+  --capabilities CAPABILITY_IAM
+```
+
+<Warning>
+  **Security**: Replace `AllowedIngressCidr=0.0.0.0/0` with your specific IP ranges to restrict VPC access.
+</Warning>
+
+### Get Your Launch Template ID
+
+After deployment completes, retrieve the launch template ID:
+
+```bash
+aws cloudformation describe-stacks \
+  --stack-name testdriver-infrastructure \
+  --query 'Stacks[0].Outputs[?OutputKey==`LaunchTemplateId`].OutputValue' \
+  --output text
+```
+
+<Tip>
+  **Save this ID** — you'll need it for spawning instances and CI configuration.
+</Tip>
+
+## Step 2: Spawn Test Instances
+
+Use the `spawn-runner.sh` script to launch instances on-demand. This script:
+
+- Launches a new EC2 instance using your launch template
+- Waits for the instance to be ready
+- Completes the TestDriver handshake
+- Returns instance details for test execution
+
+```bash
+# Set environment variables
+export AWS_REGION=us-east-2
+export AMI_ID=ami-086b5b4b86d78987c
+export AWS_LAUNCH_TEMPLATE_ID=lt-your-template-id
+export RESOLUTION=1440x900  # Optional, default is 1440x900
+
+# Spawn an instance
+./setup/aws/spawn-runner.sh
+```
+
+Output:
+```
+PUBLIC_IP=1.2.3.4
+INSTANCE_ID=i-1234567890abcdef0
+AWS_REGION=us-east-2
+```
+
+### Run Tests Against Your Instance
+
+With Vitest, specify the instance IP using the `TD_VM` environment variable:
+
+```bash
+TD_API_KEY=your-api-key TD_VM=1.2.3.4 npx vitest run
+```
+
+### Terminate Instances
+
+Always terminate instances after tests complete to avoid unnecessary costs:
+
+```bash
+aws ec2 terminate-instances \
+  --instance-ids i-1234567890abcdef0 \
+  --region us-east-2
+```
+
+<Note>
+  Instances are tagged with `Name=TestDriverRunner` and your `ProjectTag` for easy identification in the AWS console.
+</Note>
+
+## Step 3: GitHub Actions Integration
+
+Automate the full lifecycle in your CI/CD pipeline. This workflow spawns an instance, runs tests, and terminates the instance:
+
+```yaml .github/workflows/test.yml
+name: TestDriver Self-Hosted
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Prevent concurrent runs from competing for resources
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Setup AWS Instance
+        id: aws-setup
+        run: |
+          OUTPUT=$(./setup/aws/spawn-runner.sh | tee /dev/stderr)
+          PUBLIC_IP=$(echo "$OUTPUT" | grep "PUBLIC_IP=" | cut -d'=' -f2)
+          INSTANCE_ID=$(echo "$OUTPUT" | grep "INSTANCE_ID=" | cut -d'=' -f2)
+          echo "public-ip=$PUBLIC_IP" >> $GITHUB_OUTPUT
+          echo "instance-id=$INSTANCE_ID" >> $GITHUB_OUTPUT
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ secrets.AWS_REGION }}
+          AWS_LAUNCH_TEMPLATE_ID: ${{ secrets.AWS_LAUNCH_TEMPLATE_ID }}
+          AMI_ID: ${{ secrets.AMI_ID }}
+
+      - name: Run Tests
+        run: npx vitest run
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TD_VM: ${{ steps.aws-setup.outputs.public-ip }}
+
+      - name: Shutdown AWS Instance
+        if: always()
+        run: |
+          aws ec2 terminate-instances \
+            --region ${{ secrets.AWS_REGION }} \
+            --instance-ids ${{ steps.aws-setup.outputs.instance-id }}
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ secrets.AWS_REGION }}
+```
+
+### Required GitHub Secrets
+
+| Secret | Description | Example |
+|--------|-------------|---------|
+| `AWS_ACCESS_KEY_ID` | AWS access key | `AKIAIOSFODNN7EXAMPLE` |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key | `wJalrXUtnFEMI/K7MDENG...` |
+| `AWS_REGION` | AWS region | `us-east-2` |
+| `AWS_LAUNCH_TEMPLATE_ID` | From CloudFormation output | `lt-07c53ce8349b958d1` |
+| `AMI_ID` | TestDriver AMI ID | `ami-086b5b4b86d78987c` |
+| `TD_API_KEY` | Your TestDriver API key | From [console.testdriver.ai](https://console.testdriver.ai) |
+
+## AMI Customization
+
+The TestDriver Golden Image comes pre-configured with:
+
+- Windows Server with desktop environment
+- VNC + web server for remote access
+- Python, Node.js, Git
+- TestDriver agent and dependencies
+
+### Creating a Custom AMI
+
+You can customize the AMI to include additional software or configurations:
+
+<Steps>
+  <Step title="Connect via RDP">
+    Use the default credentials:
+    - **Username**: `testdriver`
+    - **Password**: `changemeABC123`
+  </Step>
+  
+  <Step title="Change the Password">
+    **Critical**: Run the password rotation script immediately:
+    ```powershell
+    C:\testdriver\RotateLocalPasswords.ps1
+    ```
+    Save the new password securely.
+  </Step>
+  
+  <Step title="Install Your Software">
+    Install any additional dependencies, configure settings, or modify the environment as needed.
+  </Step>
+  
+  <Step title="Create New AMI">
+    Use the AWS console or CLI to create an AMI from your modified instance. Update your workflow to use the new AMI ID.
+  </Step>
+</Steps>
+
+<Warning>
+  **Security**: Never use the default password in production. Always rotate passwords before creating custom AMIs.
+</Warning>
+
+### Changing Screen Resolution
+
+Set resolution via environment variable when spawning:
+
+```bash
+export RESOLUTION=1920x1080
+./setup/aws/spawn-runner.sh
+```
+
+Or in a lifecycle provision script:
+
+```yaml lifecycle/provision.yaml
+version: 7.0.0
+steps:
+  - prompt: set screen resolution
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          C:\testdriver\SetResolution.ps1 -Width 1920 -Height 1080
+```
+
+## Security Best Practices
+
+### Network Security
+
+- **Restrict CIDR blocks** — Only allow access from known IP ranges
+- **Use VPC endpoints** — For private AWS service communication
+- **Enable VPC Flow Logs** — For network monitoring
+
+### AWS Authentication
+
+Use OIDC instead of long-term credentials for GitHub Actions:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+
+steps:
+  - name: Configure AWS credentials
+    uses: aws-actions/configure-aws-credentials@v4
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
+      aws-region: us-east-2
+```
+
+See [GitHub's OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for setup instructions.
+
+### Instance Security
+
+- **Terminate immediately** after tests complete
+- **Monitor costs** with AWS billing alerts
+- **Use least-privilege IAM roles**
+- **Enable CloudTrail** for audit logging
+
+## Troubleshooting
+
+### Instance Not Responding
+
+- **Check security groups** — Verify required ports are open (RDP 3389, VNC 5900, TestDriver ports)
+- **Verify status checks** — Ensure instance has passed AWS status checks
+- **Check AMI compatibility** — Some instance types don't support certain AMIs
+
+### Connection Timeouts
+
+- Verify network connectivity from CI runner to instance
+- Check VPC routing and internet gateway configuration
+- Confirm instance is in the correct subnet
+
+### AWS CLI Errors
+
+- Validate credentials and permissions
+- Check service quotas and limits
+- Verify region consistency across all resources
+
+## Getting Help
+
+<CardGroup cols={2}>
+  <Card
+    title="Contact Support"
+    icon="envelope"
+    href="https://calendly.com/d/cq23-qyn-3v6/testdriver-ai-demo"
+  >
+    Get help with self-hosted setup and configuration
+  </Card>
+  <Card
+    title="Self-Hosted Overview"
+    icon="server"
+    href="/v7/self-hosted"
+  >
+    Learn more about self-hosted benefits and pricing
+  </Card>
+</CardGroup>