@testdriverai/agent 7.8.0-canary.10

package/setup/aws/spawn-runner.sh

@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Config (reads from env) ---
+: "${AWS_REGION:?Set AWS_REGION}"
+: "${AMI_ID:?Set AMI_ID (TestDriver Ami)}"
+: "${AWS_LAUNCH_TEMPLATE_ID:?Set AWS_LAUNCH_TEMPLATE_ID}"
+: "${AWS_LAUNCH_TEMPLATE_VERSION:=\$Latest}"
+: "${AWS_TAG_PREFIX:=td}"
+: "${RUNNER_CLASS_ID:=default}"
+: "${RESOLUTION:=1440x900}"
+
+TAG_NAME="${AWS_TAG_PREFIX}-"$(date +%s)
+
+echo "Launching AWS Instance..."
+
+# --- 1) Launch instance ---
+RUN_JSON=$(aws ec2 run-instances \
+  --region "$AWS_REGION" \
+  --image-id "$AMI_ID" \
+  --launch-template "LaunchTemplateId=$AWS_LAUNCH_TEMPLATE_ID,Version=$AWS_LAUNCH_TEMPLATE_VERSION" \
+  --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=${TAG_NAME}},{Key=Class,Value=${RUNNER_CLASS_ID}},{Key=TD_RESOLUTION,Value=${RESOLUTION}}]" \
+  --output json)
+
+INSTANCE_ID=$(jq -r '.Instances[0].InstanceId' <<<"$RUN_JSON")
+
+echo "Launched: $INSTANCE_ID"
+echo "Instance details:"
+echo "  Region: $AWS_REGION"
+echo "  AMI ID: $AMI_ID"
+echo "  Launch Template ID: $AWS_LAUNCH_TEMPLATE_ID"
+echo "  Launch Template Version: $AWS_LAUNCH_TEMPLATE_VERSION"
+
+echo "Waiting for instance to be running..."
+
+# --- 2) Wait for running + status checks ---
+aws ec2 wait instance-running --region "$AWS_REGION" --instance-ids "$INSTANCE_ID"
+echo "✓ Instance is now running"
+
+echo "Waiting for instance to pass status checks..."
+
+aws ec2 wait instance-status-ok --region "$AWS_REGION" --instance-ids "$INSTANCE_ID"
+echo "✓ Instance passed all status checks"
+
+# Additional validation - check instance state details
+echo "Validating instance readiness..."
+INSTANCE_STATE=$(aws ec2 describe-instances --region "$AWS_REGION" --instance-ids "$INSTANCE_ID" \
+  --query 'Reservations[0].Instances[0].{State:State.Name,StatusChecks:StateTransitionReason}' \
+  --output json)
+echo "Instance state details: $INSTANCE_STATE"
+
+# --- 3) Ensure SSM connectivity ---
+echo "Waiting for SSM connectivity..."
+echo "This can take several minutes for the SSM agent to be fully ready..."
+
+# First, check if the instance is registered with SSM
+echo "Checking SSM instance registration..."
+TRIES=0; MAX_TRIES=60
+while :; do
+  echo "Attempt $((TRIES+1))/$MAX_TRIES: Checking if instance is registered with SSM..."
+  
+  # Check if instance appears in SSM managed instances
+  if aws ssm describe-instance-information \
+      --region "$AWS_REGION" \
+      --filters "Key=InstanceIds,Values=$INSTANCE_ID" \
+      --query 'InstanceInformationList[0].InstanceId' \
+      --output text 2>/dev/null | grep -q "$INSTANCE_ID"; then
+    echo "✓ Instance is registered with SSM"
+    break
+  fi
+  
+  TRIES=$((TRIES+1))
+  if [ $TRIES -ge $MAX_TRIES ]; then
+    echo "❌ SSM registration timeout - instance may not have proper IAM role or SSM agent"
+    echo "Checking instance details for debugging..."
+    aws ec2 describe-instances --region "$AWS_REGION" --instance-ids "$INSTANCE_ID" \
+      --query 'Reservations[0].Instances[0].{State:State.Name,IAMProfile:IamInstanceProfile.Arn,SecurityGroups:SecurityGroups[].GroupId}' \
+      --output table
+    exit 2
+  fi
+  echo "Instance not yet registered with SSM, waiting..."
+  sleep 10
+done
+
+# Now test SSM command execution
+echo "Testing SSM command execution..."
+TRIES=0; MAX_TRIES=30
+while :; do
+  echo "Attempt $((TRIES+1))/$MAX_TRIES: Sending test SSM command..."
+  
+  if CMD_JSON=$(aws ssm send-command \
+      --region "$AWS_REGION" \
+      --targets "Key=instanceIds,Values=$INSTANCE_ID" \
+      --document-name "AWS-RunPowerShellScript" \
+      --parameters 'commands=["echo SSM connectivity test successful"]' \
+      --output json 2>/dev/null); then
+      
+    COMMAND_ID=$(jq -r '.Command.CommandId' <<<"$CMD_JSON")
+    echo "✓ SSM command sent successfully (Command ID: $COMMAND_ID)"
+    
+    # Wait for command to complete and check status
+    echo "Waiting for command execution..."
+    if aws ssm wait command-executed --region "$AWS_REGION" --command-id "$COMMAND_ID" --instance-id "$INSTANCE_ID" 2>/dev/null; then
+      echo "✓ SSM connectivity confirmed"
+      break
+    else
+      echo "⚠ Command execution may have failed, checking status..."
+      CMD_STATUS=$(aws ssm get-command-invocation \
+        --region "$AWS_REGION" \
+        --command-id "$COMMAND_ID" \
+        --instance-id "$INSTANCE_ID" \
+        --query 'Status' \
+        --output text 2>/dev/null || echo "Unknown")
+      echo "Command status: $CMD_STATUS"
+      
+      if [ "$CMD_STATUS" = "Success" ]; then
+        echo "✓ Command actually succeeded"
+        break
+      fi
+    fi
+  else
+    echo "⚠ Failed to send SSM command"
+  fi
+  
+  TRIES=$((TRIES+1))
+  if [ $TRIES -ge $MAX_TRIES ]; then
+    echo "❌ SSM command execution timeout"
+    echo "Final debugging information:"
+    
+    # Get SSM agent status
+    echo "SSM Agent status on instance:"
+    aws ssm describe-instance-information \
+      --region "$AWS_REGION" \
+      --filters "Key=InstanceIds,Values=$INSTANCE_ID" \
+      --query 'InstanceInformationList[0].{PingStatus:PingStatus,LastPingDateTime:LastPingDateTime,AgentVersion:AgentVersion}' \
+      --output table 2>/dev/null || echo "Could not retrieve SSM status"
+    
+    exit 2
+  fi
+  echo "Retrying in 20 seconds..."
+  sleep 20
+done
+
+# --- 4) Install/update runner ---
+echo "Installing runner..."
+
+# Determine environment and version
+TD_ENV="${TD_ENV:-stable}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SDK_PKG_JSON="${SCRIPT_DIR}/../../../sdk/package.json"
+RUNNER_DIR="${SCRIPT_DIR}/../../../runner"
+
+if [ -f "$SDK_PKG_JSON" ]; then
+  RUNNER_VERSION=$(jq -r '.version' "$SDK_PKG_JSON")
+  echo "Runner version from SDK: $RUNNER_VERSION"
+else
+  RUNNER_VERSION="$TD_ENV"
+  echo "SDK package.json not found, using env tag: $RUNNER_VERSION"
+fi
+
+if [ "$TD_ENV" = "dev" ]; then
+  echo "Dev mode: packing and uploading local runner to S3..."
+  
+  # Pack local runner
+  TMPDIR=$(mktemp -d)
+  pushd "$RUNNER_DIR" > /dev/null
+  npm pack --pack-destination "$TMPDIR" > /dev/null 2>&1
+  TARBALL=$(ls "$TMPDIR"/*.tgz | head -1)
+  popd > /dev/null
+  
+  # Upload to S3
+  S3_BUCKET="${AWS_BUCKET_IMAGE_TRANSFER:-v7-transfer}"
+  S3_KEY="runner-dev/$(date +%s)-$(openssl rand -hex 4)/runner.tgz"
+  aws s3 cp "$TARBALL" "s3://${S3_BUCKET}/${S3_KEY}" --region "$AWS_REGION"
+  
+  # Generate presigned URL (15 min)
+  DOWNLOAD_URL=$(aws s3 presign "s3://${S3_BUCKET}/${S3_KEY}" --expires-in 900 --region "$AWS_REGION")
+  rm -rf "$TMPDIR"
+  
+  # Build SSM parameters JSON in a temp file to avoid shell escaping issues with URL
+  PARAMS_FILE=$(mktemp)
+  cat > "$PARAMS_FILE" << 'PARAMS_EOF'
+{
+  "commands": [
+    "Write-Host '=== Starting runner dev install ==='",
+    "Write-Host 'Stopping existing runner processes...'",
+    "Stop-ScheduledTask -TaskName RunTestDriverAgent -ErrorAction SilentlyContinue",
+    "Stop-Process -Name node -Force -ErrorAction SilentlyContinue",
+    "Start-Sleep -Seconds 2",
+    "Write-Host 'Current runner version:'",
+    "Get-Content 'C:\\testdriver\\sandbox-agent\\package.json' | ConvertFrom-Json | Select-Object -ExpandProperty version",
+    "Set-Location 'C:\\testdriver\\sandbox-agent'",
+    "Write-Host 'Dev mode: downloading runner from S3...'",
+    "$tarball = 'C:\\Windows\\Temp\\runner-dev.tgz'",
+PARAMS_EOF
+  
+  # Add the URL line with proper JSON escaping
+  echo "    \"Invoke-WebRequest -Uri '$(echo "$DOWNLOAD_URL" | sed 's/"/\\"/g')' -OutFile \$tarball\"," >> "$PARAMS_FILE"
+  
+  cat >> "$PARAMS_FILE" << 'PARAMS_EOF'
+    "Write-Host 'Downloaded tarball size:'",
+    "(Get-Item $tarball).Length",
+    "Write-Host 'Extracting runner...'",
+    "tar -xzf $tarball -C 'C:\\Windows\\Temp'",
+    "Write-Host 'Extracted package contents:'",
+    "Get-ChildItem 'C:\\Windows\\Temp\\package' -Recurse | Select-Object FullName",
+    "Write-Host 'New runner version in package:'",
+    "Get-Content 'C:\\Windows\\Temp\\package\\package.json' | ConvertFrom-Json | Select-Object -ExpandProperty version",
+    "Write-Host 'Clearing old lib folder...'",
+    "Remove-Item 'C:\\testdriver\\sandbox-agent\\lib' -Recurse -Force -ErrorAction SilentlyContinue",
+    "Write-Host 'Copying files to sandbox-agent...'",
+    "xcopy 'C:\\Windows\\Temp\\package\\*' 'C:\\testdriver\\sandbox-agent\\' /E /Y /I",
+    "Write-Host 'Files after copy:'",
+    "Get-ChildItem 'C:\\testdriver\\sandbox-agent' | Select-Object Name",
+    "Remove-Item 'C:\\Windows\\Temp\\package' -Recurse -Force -ErrorAction SilentlyContinue",
+    "Remove-Item $tarball -Force -ErrorAction SilentlyContinue",
+    "Write-Host 'Runner version after copy:'",
+    "Get-Content 'C:\\testdriver\\sandbox-agent\\package.json' | ConvertFrom-Json | Select-Object -ExpandProperty version",
+    "Write-Host 'Installing npm dependencies...'",
+    "npm install --omit=dev 2>&1 | Write-Host",
+    "Write-Host 'Final verification - ably-service.js exists:'",
+    "Test-Path 'C:\\testdriver\\sandbox-agent\\lib\\ably-service.js'",
+    "Write-Host 'Restarting RunTestDriverAgent scheduled task...'",
+    "Start-ScheduledTask -TaskName RunTestDriverAgent -ErrorAction SilentlyContinue",
+    "Write-Host '=== Runner install complete (dev) ==='"
+  ]
+}
+PARAMS_EOF
+
+  echo "Sending SSM command to download and install runner from S3..."
+  INSTALL_CMD=$(aws ssm send-command \
+    --region "$AWS_REGION" \
+    --instance-ids "$INSTANCE_ID" \
+    --document-name "AWS-RunPowerShellScript" \
+    --parameters "file://$PARAMS_FILE" \
+    --timeout-seconds 180 \
+    --output json)
+  rm -f "$PARAMS_FILE"
+else
+  echo "Installing @testdriverai/runner@${RUNNER_VERSION} via npm..."
+  INSTALL_CMD=$(aws ssm send-command \
+    --region "$AWS_REGION" \
+    --instance-ids "$INSTANCE_ID" \
+    --document-name "AWS-RunPowerShellScript" \
+    --parameters "commands=[
+      \"Set-Location 'C:\\\\testdriver\\\\sandbox-agent'\",
+      \"Write-Host 'Installing @testdriverai/runner@${RUNNER_VERSION}...'\",
+      \"npm install @testdriverai/runner@${RUNNER_VERSION} --omit=dev 2>&1 | Write-Host\",
+      \"Write-Host 'Stopping runner (config not yet provisioned)...'\",
+      \"Stop-Process -Name node -Force -ErrorAction SilentlyContinue\",
+      \"Stop-ScheduledTask -TaskName RunTestDriverAgent -ErrorAction SilentlyContinue\",
+      \"Start-Sleep -Seconds 2\",
+      \"Start-ScheduledTask -TaskName RunTestDriverAgent -ErrorAction SilentlyContinue\",
+      \"Write-Host 'Runner install complete'\"
+    ]" \
+    --timeout-seconds 120 \
+    --output json)
+fi
+
+INSTALL_CMD_ID=$(jq -r '.Command.CommandId' <<<"$INSTALL_CMD")
+echo "Runner install command sent (Command ID: $INSTALL_CMD_ID)"
+
+# Wait for install to complete
+echo "Waiting for runner install to complete..."
+if aws ssm wait command-executed --region "$AWS_REGION" --command-id "$INSTALL_CMD_ID" --instance-id "$INSTANCE_ID" 2>/dev/null; then
+  echo "✓ Runner install succeeded"
+else
+  INSTALL_STATUS=$(aws ssm get-command-invocation \
+    --region "$AWS_REGION" \
+    --command-id "$INSTALL_CMD_ID" \
+    --instance-id "$INSTANCE_ID" \
+    --output json 2>/dev/null || echo '{}')
+  echo "⚠ Runner install status: $(jq -r '.Status // "Unknown"' <<<"$INSTALL_STATUS")"
+  echo "Output: $(jq -r '.StandardOutputContent // "No output"' <<<"$INSTALL_STATUS" | head -20)"
+  echo "Errors: $(jq -r '.StandardErrorContent // "No errors"' <<<"$INSTALL_STATUS" | head -10)"
+fi
+
+echo "Getting Public IP..."
+
+# --- 5) Get instance Public IP ---
+DESC_JSON=$(aws ec2 describe-instances --region "$AWS_REGION" --instance-ids "$INSTANCE_ID" --output json)
+PUBLIC_IP=$(jq -r '.Reservations[0].Instances[0].PublicIpAddress // empty' <<<"$DESC_JSON")
+[ -n "$PUBLIC_IP" ] || PUBLIC_IP="No public IP assigned"
+
+# --- 6) Output results ---
+echo "Setup complete!"
+echo "PUBLIC_IP=$PUBLIC_IP"
+echo "INSTANCE_ID=$INSTANCE_ID"
+echo "AWS_REGION=$AWS_REGION"

package/test/captcha-solver.test.mjs

@@ -0,0 +1,152 @@
+/**
+ * Unit tests for the captcha solver script
+ * These tests verify the solver script is valid JavaScript and can be loaded correctly
+ */
+import { describe, expect, it } from "vitest";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import vm from "vm";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const solverPath = path.join(__dirname, "..", "lib", "captcha", "solver.js");
+
+// Extract safeParseJson function from the solver script for testing
+function getSafeParseJson() {
+  const script = fs.readFileSync(solverPath, "utf8");
+  // Extract the safeParseJson function source
+  const funcMatch = script.match(
+    /function safeParseJson\(text\) \{[\s\S]*?^}/m,
+  );
+  if (!funcMatch) {
+    throw new Error("Could not find safeParseJson function in solver script");
+  }
+  // Create and return the function
+  const func = new Function("return " + funcMatch[0])();
+  return func;
+}
+
+describe("Captcha Solver Script", () => {
+  it("should exist", () => {
+    expect(fs.existsSync(solverPath)).toBe(true);
+  });
+
+  it("should be valid JavaScript syntax", () => {
+    const script = fs.readFileSync(solverPath, "utf8");
+
+    // This will throw if the syntax is invalid
+    expect(() => {
+      new vm.Script(script, { filename: "solver.js" });
+    }).not.toThrow();
+  });
+
+  it("should contain required functions and variables", () => {
+    const script = fs.readFileSync(solverPath, "utf8");
+
+    // Check for key components
+    expect(script).toContain('require("https")');
+    expect(script).toContain('require("chrome-remote-interface")');
+    expect(script).toContain("detectCaptchaScript");
+    expect(script).toContain("getInjectScript");
+    expect(script).toContain("autoSubmitScript");
+    expect(script).toContain("checkSuccessScript");
+    expect(script).toContain("2captcha.com");
+  });
+
+  it("should handle all supported captcha types", () => {
+    const script = fs.readFileSync(solverPath, "utf8");
+
+    // Check for captcha type handling
+    expect(script).toContain("recaptcha_v2");
+    expect(script).toContain("recaptcha_v3");
+    expect(script).toContain("hcaptcha");
+    expect(script).toContain("turnstile");
+  });
+
+  it("should have proper auto-detection for captcha elements", () => {
+    const script = fs.readFileSync(solverPath, "utf8");
+
+    // Check for DOM selectors used in auto-detection
+    expect(script).toContain(".g-recaptcha[data-sitekey]");
+    expect(script).toContain(".h-captcha[data-sitekey]");
+    expect(script).toContain(".cf-turnstile[data-sitekey]");
+    expect(script).toContain("[data-sitekey]");
+  });
+
+  it("should properly inject tokens into response fields", () => {
+    const script = fs.readFileSync(solverPath, "utf8");
+
+    // Check for token injection selectors
+    expect(script).toContain("[name=g-recaptcha-response]");
+    expect(script).toContain("[name=h-captcha-response]");
+    expect(script).toContain("[name=cf-turnstile-response]");
+    expect(script).toContain("___grecaptcha_cfg");
+  });
+
+  it("should contain safeParseJson function for robust JSON parsing", () => {
+    const script = fs.readFileSync(solverPath, "utf8");
+    expect(script).toContain("function safeParseJson");
+    expect(script).toContain("safeParseJson(await httpsGet");
+  });
+});
+
+describe("safeParseJson", () => {
+  let safeParseJson;
+  let extractionFailed = false;
+
+  // Try to extract the function for testing
+  try {
+    safeParseJson = getSafeParseJson();
+  } catch {
+    extractionFailed = true;
+  }
+
+  // Use it.skipIf to clearly indicate skipped tests
+  const testFn = extractionFailed ? it.skip : it;
+
+  testFn("should parse valid JSON normally", () => {
+    const result = safeParseJson('{"status":1,"request":"abc123"}');
+    expect(result).toEqual({ status: 1, request: "abc123" });
+  });
+
+  testFn("should handle JSON with leading/trailing whitespace", () => {
+    const result = safeParseJson('  {"status":1}  \n');
+    expect(result).toEqual({ status: 1 });
+  });
+
+  testFn("should extract first JSON object from concatenated responses", () => {
+    // This is the exact error case: multiple JSON objects concatenated
+    const result = safeParseJson('{"status":1}{"status":2}');
+    expect(result).toEqual({ status: 1 });
+  });
+
+  testFn("should handle JSON with trailing garbage characters", () => {
+    const result = safeParseJson('{"status":1}xxx');
+    expect(result).toEqual({ status: 1 });
+  });
+
+  testFn("should handle nested objects correctly", () => {
+    const result = safeParseJson('{"data":{"nested":true}}extra');
+    expect(result).toEqual({ data: { nested: true } });
+  });
+
+  testFn("should handle strings containing braces", () => {
+    const result = safeParseJson('{"text":"hello {world}"}extra');
+    expect(result).toEqual({ text: "hello {world}" });
+  });
+
+  testFn("should handle escaped quotes in strings", () => {
+    const result = safeParseJson('{"text":"say \\"hello\\""}extra');
+    expect(result).toEqual({ text: 'say "hello"' });
+  });
+
+  testFn("should throw for responses without JSON", () => {
+    expect(() => safeParseJson("not json at all")).toThrow(
+      "No JSON object found",
+    );
+  });
+
+  testFn("should throw for incomplete JSON", () => {
+    expect(() => safeParseJson('{"incomplete')).toThrow("Invalid JSON");
+  });
+});

package/test/chrome-remote-debugging.test.mjs

@@ -0,0 +1,66 @@
+/**
+ * Test that validates Chrome remote debugging is working
+ * Installs chrome-remote-interface and connects to the active tab
+ */
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Chrome Remote Debugging", () => {
+
+  it("should connect to Chrome via CDP and get page title", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    // Launch Chrome with a known URL
+    await testdriver.provision.chrome({
+      url: 'https://example.com',
+    });
+
+    // Take a screenshot to verify Chrome launched
+    await testdriver.screenshot();
+
+    // Install chrome-remote-interface (needs sudo for global install)
+    const installResult = await testdriver.exec(
+      'sh',
+      'sudo npm install -g chrome-remote-interface',
+      60000
+    );
+    console.log('Install result:', installResult);
+
+    // Write the CDP script to a file to avoid quoting issues
+    const cdpScript = `
+const CDP = require('chrome-remote-interface');
+(async () => {
+  try {
+    const client = await CDP();
+    const { Runtime } = client;
+    const result = await Runtime.evaluate({
+      expression: 'document.title'
+    });
+    console.log('PAGE_TITLE:' + result.result.value);
+    await client.close();
+    process.exit(0);
+  } catch (err) {
+    console.error('CDP_ERROR:' + err.message);
+    process.exit(1);
+  }
+})();
+`;
+
+    // Write script to file
+    await testdriver.exec('sh', `cat > /tmp/cdp-test.js << 'SCRIPT'
+${cdpScript}
+SCRIPT`, 5000);
+
+    // Run the CDP script with NODE_PATH set to find globally installed modules
+    const cdpResult = await testdriver.exec(
+      'sh',
+      'NODE_PATH=/usr/lib/node_modules node /tmp/cdp-test.js 2>&1 || echo "CDP_EXIT_CODE:$?"',
+      30000
+    );
+    console.log('CDP result:', cdpResult);
+
+    // Verify we got the page title
+    expect(cdpResult).toContain('PAGE_TITLE:');
+    expect(cdpResult).toContain('Example Domain');
+  });
+});

package/test/duckduckgo/experiment.test.mjs

@@ -0,0 +1,28 @@
+/**
+ * Experiment file - reconnects to existing sandbox
+ * Run AFTER setup.test.mjs passes
+ */
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../lib/vitest/hooks.mjs";
+
+describe("Experiment DuckDuckGo", () => {
+  it("should search for apples", async (context) => {
+    const testdriver = TestDriver(context, {
+      reconnect: true, // ← Key: reconnects to last sandbox
+    });
+
+    // NO provision here! The sandbox is already running from setup.test.mjs
+
+    // Find search input and type
+    const searchInput = await testdriver.find("search input");
+    await searchInput.click();
+    await testdriver.type("apples");
+    await testdriver.pressKeys(["enter"]);
+
+    // Assert results
+    const result = await testdriver.assert(
+      "I can see search results for apples",
+    );
+    expect(result).toBeTruthy();
+  });
+});

package/test/duckduckgo/setup.test.mjs

@@ -0,0 +1,29 @@
+/**
+ * Setup file - MINIMAL steps to get to starting state
+ * Only add more steps AFTER this passes!
+ */
+import { afterAll, describe, expect, it } from "vitest";
+import { TestDriver } from "../../lib/vitest/hooks.mjs";
+
+describe("Setup DuckDuckGo", () => {
+  afterAll(async () => {
+    // DO NOT disconnect - keep sandbox alive for reconnect
+    console.log("Sandbox staying alive for 30 seconds (keepAlive)");
+  });
+
+  it("should set up the application state", async (context) => {
+    const testdriver = TestDriver(context);
+
+    await testdriver.provision.chrome({
+      url: "https://duckduckgo.com",
+    });
+
+    // Start with just ONE assertion to verify we're on the right page
+    const result = await testdriver.assert(
+      "I can see the DuckDuckGo search page",
+    );
+    expect(result).toBeTruthy();
+
+    console.log("✅ Setup ready - run experiment.test.mjs now");
+  });
+});

package/test/manual/debug-locate-response.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * Debug script to inspect the full locate API response
+ * Run this with: TD_API_KEY=your_key node debug-locate-response.js
+ */
+
+const TestDriverSDK = require("./sdk.js");
+
+async function debugLocateResponse() {
+  const client = new TestDriverSDK(process.env.TD_API_KEY);
+
+  try {
+    console.log("Connecting to sandbox (Linux)...");
+    await client.connect({ headless: true });
+
+    console.log("Opening a test page...");
+    await client.focusApplication("Google Chrome");
+    await client.type("https://example.com");
+    await client.pressKeys(["enter"]);
+
+    // Wait for page to load
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    console.log("\nFinding an element to inspect the response...");
+    const element = await client.find("the heading that says Example Domain");
+
+    console.log("\n=".repeat(60));
+    console.log("FULL LOCATE API RESPONSE:");
+    console.log("=".repeat(60));
+
+    const response = element.getResponse();
+    console.log(JSON.stringify(response, null, 2));
+
+    console.log("\n=".repeat(60));
+    console.log("RESPONSE KEYS:");
+    console.log("=".repeat(60));
+
+    if (response) {
+      Object.keys(response).forEach((key) => {
+        const value = response[key];
+        const type = Array.isArray(value) ? "array" : typeof value;
+        const preview =
+          typeof value === "string" && value.length > 100
+            ? `${value.substring(0, 100)}... (${value.length} chars)`
+            : typeof value === "object"
+              ? JSON.stringify(value)
+              : value;
+
+        console.log(`  ${key} (${type}): ${preview}`);
+      });
+    }
+
+    console.log("\n=".repeat(60));
+    console.log("ELEMENT PROPERTIES:");
+    console.log("=".repeat(60));
+    console.log("  found:", element.found());
+    console.log("  x:", element.x);
+    console.log("  y:", element.y);
+    console.log("  centerX:", element.centerX);
+    console.log("  centerY:", element.centerY);
+    console.log("  width:", element.width);
+    console.log("  height:", element.height);
+    console.log("  confidence:", element.confidence);
+    console.log("  text:", element.text);
+    console.log("  label:", element.label);
+    console.log(
+      "  screenshot:",
+      element.screenshot ? `${element.screenshot.length} chars` : null,
+    );
+    console.log("  boundingBox:", element.boundingBox);
+
+    await client.disconnect();
+  } catch (error) {
+    console.error("Error:", error.message);
+    console.error(error.stack);
+    await client.disconnect();
+    process.exit(1);
+  }
+}
+
+debugLocateResponse();