testdriverai 6.1.4 → 6.1.5-canary.b2eb46e.0

package/.github/workflows/self-hosted.yml

@@ -0,0 +1,98 @@
+name: AWS
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  gather:
+    name: Gather Test Files
+    runs-on: ubuntu-latest
+    outputs:
+      test_files: ${{ steps.test_list.outputs.files }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Find all test files
+        id: test_list
+        run: |
+          FILES=$(ls ./testdriver/acceptance/*.yaml)
+          FILENAMES=$(basename -a $FILES)
+          FILES_JSON=$(echo "$FILENAMES" | jq -R -s -c 'split("\n")[:-1]')
+          echo "files=$FILES_JSON" >> $GITHUB_OUTPUT
+
+  test:
+    needs: gather
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        test: ${{ fromJson(needs.gather.outputs.test_files) }}
+      fail-fast: false
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      # only needed for `act`
+      # - name: Install AWS CLI
+      #   run: |
+      #     apt-get update
+      #     apt-get install curl unzip -y
+      #     curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+      #     unzip awscliv2.zip
+      #     ./aws/install
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+      - name: Install dependencies
+        run: NODE_ENV=production npm ci
+      - name: Setup AWS Instance
+        id: aws-setup
+        run: |
+          OUTPUT=$(./setup/aws/spawn-runner.sh | tee /dev/stderr) # Capture and display output
+          echo "$OUTPUT"
+          PUBLIC_IP=$(echo "$OUTPUT" | grep "PUBLIC_IP=" | cut -d'=' -f2)
+          INSTANCE_ID=$(echo "$OUTPUT" | grep "INSTANCE_ID=" | cut -d'=' -f2)
+          AWS_REGION=$(echo "$OUTPUT" | grep "AWS_REGION=" | cut -d'=' -f2)
+          echo "public-ip=$PUBLIC_IP" >> $GITHUB_OUTPUT
+          echo "instance-id=$INSTANCE_ID" >> $GITHUB_OUTPUT
+          echo "aws-region=$AWS_REGION" >> $GITHUB_OUTPUT
+        env:
+          FORCE_COLOR: 3
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: us-east-2
+          AWS_LAUNCH_TEMPLATE_ID: lt-00d02f31cfc602f27
+          AMI_ID: ami-085f872ca0cd80fed
+      - name: Run TestDriver
+        run: node bin/testdriverai.js run testdriver/acceptance/${{ matrix.test }} --ip="${{ steps.aws-setup.outputs.public-ip }}" --junit=out.xml
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TD_WEBSITE: https://testdriver-sandbox.vercel.app
+          TD_THIS_FILE: ${{ matrix.test }}
+      - name: Upload TestDriver AI CLI logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: testdriverai-cli-logs-${{ matrix.test }}
+          path: /tmp/testdriverai-cli-*.log
+          if-no-files-found: warn
+          retention-days: 30
+      - name: Upload test results as artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.test }}
+          path: out.xml
+          retention-days: 30
+      - name: Shutdown AWS Instance
+        if: always()
+        run: aws ec2 terminate-instances --region "$AWS_REGION" --instance-ids "$INSTANCE_ID"
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ steps.aws-setup.outputs.aws-region }}
+          INSTANCE_ID: ${{ steps.aws-setup.outputs.instance-id }}

package/agent/index.js

@@ -74,6 +74,7 @@ class TestDriverAgent extends EventEmitter2 {
     this.sandboxId = flags["sandbox-id"] || null;
     this.sandboxAmi = flags["sandbox-ami"] || null;
     this.sandboxInstance = flags["sandbox-instance"] || null;
+    this.ip = flags.ip || null;
     this.workingDir = flags.workingDir || process.cwd();
 
     // Resolve thisFile to absolute path with proper extension
@@ -1709,7 +1710,20 @@ ${regression}
     const recentId = createNew ? null : this.getRecentSandboxId();
 
     // Set sandbox ID for reconnection (only if not creating new and recent ID exists)
-    if (!createNew && recentId) {
+    if (this.ip) {
+      let instance = await this.sandbox.send({
+        type: "direct",
+        resolution: this.config.TD_RESOLUTION,
+        ci: this.config.CI,
+        ip: this.ip,
+      });
+
+      await this.renderSandbox(instance.instance, headless);
+      await this.newSession();
+      await this.runLifecycle("provision");
+
+      return;
+    } else if (!createNew && recentId) {
       this.emitter.emit(
         events.log.narration,
         theme.dim(`using recent sandbox: ${recentId}`),
@@ -1720,10 +1734,8 @@ ${regression}
         events.log.narration,
         theme.dim(`no recent sandbox found, creating a new one.`),
       );
-    }
-
-    // Only attempt to connect to existing sandbox if not in CI mode and not creating new
-    if (this.sandboxId && !this.config.CI && !createNew) {
+    } else if (this.sandboxId && !this.config.CI) {
+      // Only attempt to connect to existing sandbox if not in CI mode and not creating new
       // Attempt to connect to known instance
       this.emitter.emit(
         events.log.narration,

package/agent/interface.js

@@ -55,6 +55,10 @@ function createCommandDefinitions(agent) {
         "sandbox-instance": Flags.string({
           description: "Specify EC2 instance type for sandbox (e.g., i3.metal)",
         }),
+        ip: Flags.string({
+          description:
+            "Connect directly to a sandbox at the specified IP address",
+        }),
         summary: Flags.string({
           description: "Specify output file for summarize results",
         }),
@@ -129,6 +133,10 @@ function createCommandDefinitions(agent) {
         "sandbox-instance": Flags.string({
           description: "Specify EC2 instance type for sandbox (e.g., i3.metal)",
         }),
+        ip: Flags.string({
+          description:
+            "Connect directly to a sandbox at the specified IP address",
+        }),
         summary: Flags.string({
           description: "Specify output file for summarize results",
         }),

package/docs/docs.json

@@ -50,6 +50,7 @@
               }
             ]
           },
+          "/getting-started/self-hosting",
           "/getting-started/playwright",
           "/getting-started/vscode"
         ]

package/docs/getting-started/self-hosting.mdx

@@ -0,0 +1,303 @@
+---
+title: "Self-Hosting TestDriver"
+sidebarTitle: "Self-Hosting"
+description: "Complete guide to self-hosting TestDriver instances on AWS"
+icon: "server"
+---
+
+```mermaid
+graph LR
+    A[CLI] <--> B[api.testdriver.ai]
+    B <--> C[Your AWS EC2 Instance]
+```
+
+Self-hosting TestDriver allows you to run tests on your own infrastructure, giving you full control over the environment, security, and configurations. This guide walks you through setting up and managing self-hosted TestDriver instances using AWS.
+
+## Why self host?
+
+- **Enhanced security**: Get complete control over ingress and egress rules.
+- **Complete customization**: Modify the TestDriver Golden Image to include custom dependencies, software, and configurations at launch time.
+- **Powerful Infrastructure**: Run tests on bare metal infrastructure that support emulators and simulators.
+
+## Quick Start (TL;DR)
+
+1. **Copy the workflow file**: Use [`.github/workflows/self-hosted.yml`](https://github.com/testdriverai/cli/tree/main/.github/workflows/self-hosted.yml) as your template
+2. **Run CloudFormation**: Deploy our [`setup/aws/cloudformation.yaml`](https://github.com/testdriverai/cli/tree/main/setup/aws/cloudformation.yaml) to provision infrastructure
+3. **Setup instances**: Use [`setup/aws/spawn-runner.sh`](https://github.com/testdriverai/cli/tree/main/setup/aws/spawn-runner.sh) with your launch template ID
+4. **Configure GitHub Actions**: Add AWS credentials to your repository secrets
+
+## Overview
+
+Self-hosting TestDriver gives you complete control over your test execution environment. You'll provision EC2 instances on AWS using our pre-configured AMI and infrastructure templates.
+
+## Prerequisites
+
+- AWS account with appropriate permissions
+- AWS CLI installed locally
+- Access to TestDriver's shared AMI. [Contact us for access](https://form.typeform.com/to/UECf9rDx?typeform-source=testdriver.ai).
+- GitHub repository for your tests
+
+## Step 1: Set Up AWS Infrastructure
+
+### Deploy CloudFormation Stack
+
+Our [`setup/aws/cloudformation.yaml`](https://github.com/testdriverai/cli/tree/main/setup/aws/cloudformation.yaml) template creates:
+
+- Dedicated VPC with public subnet
+- Security group with proper port access
+- IAM roles and instance profiles
+- EC2 launch template for programmatic instance creation
+
+This is a one-time setup used to generate a template ID for launching instances.
+
+```bash
+# Deploy the CloudFormation stack
+aws cloudformation deploy \
+  --template-file setup/aws/cloudformation.yaml \
+  --stack-name testdriver-infrastructure-11 \
+  --parameter-overrides \
+    ProjectTag=testdriver \
+    AllowedIngressCidr=0.0.0.0/0 \
+    InstanceType=c5.xlarge \
+    CreateKeyPair=true \
+  --capabilities CAPABILITY_IAM
+```
+
+<Danger>
+  **Security**: Replace `AllowedIngressCidr=0.0.0.0/0` with your specific IP ranges to lock down access to your VPC.
+</Danger>
+
+### Get Launch Template ID
+
+After CloudFormation completes, find the launch template ID in the stack outputs:
+
+```bash
+aws cloudformation describe-stacks \
+  --stack-name testdriver-infrastructure-11 \
+  --query 'Stacks[0].Outputs[?OutputKey==`LaunchTemplateId`].OutputValue' \
+  --output text
+```
+
+Save this ID - you'll need it for the next step.
+
+## Step 2: Spawn a New TestDriver Runner
+
+### Using aws-setup.sh
+
+Our [`setup/aws/spawn-runner.sh`](https://github.com/testdriverai/cli/tree/main/setup/aws/spawn-runner.sh) spawns and initializes instances:
+
+- Launches instances using your launch template
+- Completes TestDriver handshake
+- Returns instance details for CLI usage
+
+```bash
+# Launch an instance
+export AWS_REGION=us-east-2
+export AMI_ID=ami-085f872ca0cd80fed  # Your TestDriver AMI (contact us to get one)
+export AWS_LAUNCH_TEMPLATE_ID=lt-00d02f31cfc602f27  # From CloudFormation output from step 1
+
+./aws-setup.sh
+```
+
+The script outputs:
+
+```
+PUBLIC_IP=1.2.3.4
+INSTANCE_ID=i-1234567890abcdef0
+AWS_REGION=us-east-2
+```
+
+### CLI Usage
+
+Once you have an instance IP, run tests directly:
+
+```bash
+# Basic test execution
+npx testdriverai run test.yaml --ip=1.2.3.4
+```
+
+You can use the `PUBLIC_IP` to target the instance you just spawned via `./setup/aws/spawn-runner.sh`:
+
+```sh
+npx testdriverai@latest run testdriver/your-test.yaml \
+  --ip="$PUBLIC_IP" \
+```
+
+Note that the instance will remain running until you terminate it. You can do this manually via the AWS console, or programmatically in your CI workflow:
+
+```bash
+aws ec2 terminate-instances \
+  --region us-east-2 \
+  --instance-ids $INSTANCE_ID
+```
+
+## Step 3: GitHub Actions Integration
+
+### Example Workflow
+
+Our [`.github/workflows/self-hosted.yml`](https://github.com/testdriverai/cli/tree/main/.github/workflows/self-hosted.yml) demonstrates the complete workflow:
+
+```yaml
+name: TestDriver Self-Hosted
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - 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: us-east-2
+          AWS_LAUNCH_TEMPLATE_ID: ${{ secrets.AWS_LAUNCH_TEMPLATE_ID }}
+          AMI_ID: ${{ secrets.AMI_ID }}
+
+      - name: Run TestDriver
+        run: |
+          npx testdriverai run your-test.yaml \
+            --ip="${{ steps.aws-setup.outputs.public-ip }}"
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+
+      - name: Shutdown AWS Instance
+        if: always()
+        run: |
+          aws ec2 terminate-instances \
+            --region us-east-2 \
+            --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 }}
+```
+
+### Required Secrets
+
+Configure these secrets in your GitHub repository:
+
+| Secret                   | Description                         | Example                                                      |
+| ------------------------ | ----------------------------------- | ------------------------------------------------------------ |
+| `AWS_ACCESS_KEY_ID`      | AWS access key                      | `AKIAIOSFODNN7EXAMPLE`                                       |
+| `AWS_SECRET_ACCESS_KEY`  | AWS secret key                      | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`                   |
+| `AWS_LAUNCH_TEMPLATE_ID` | Launch template from CloudFormation | `lt-07c53ce8349b958d1`                                       |
+| `AMI_ID`                 | TestDriver AMI ID                   | `ami-085f872ca0cd80fed`                                      |
+| `TD_API_KEY`             | TestDriver API key                  | Your API key from [the dashboard](https://app.testdriver.ai) |
+
+## AMI Customization
+
+### Using the Base AMI
+
+Our AMI comes pre-configured with:
+
+- Windows Server with desktop environment
+- Required TestDriver dependencies
+- Optimized settings for test execution
+
+### Modifying the AMI
+
+You can customize the AMI for your specific needs:
+
+1. **Launch an instance** from our base AMI
+2. **Make your changes** (install software, configure settings)
+3. **Create a new AMI** from your modified instance
+4. **Update your workflow** to use the new AMI ID
+
+### Amazon Image Builder
+
+For automated AMI builds, use [Amazon EC2 Image Builder](https://aws.amazon.com/image-builder/):
+
+```yaml
+# Example Image Builder pipeline
+Components:
+  - Name: testdriver-base
+    Version: 1.0.0
+    Platform: Windows
+    Type: BUILD
+    Data: |
+      name: TestDriver Custom Setup
+      description: Custom TestDriver AMI with additional software
+      schemaVersion: 1.0
+      phases:
+        - name: build
+          steps:
+            - name: InstallSoftware
+              action: ExecutePowerShell
+              inputs:
+                commands:
+                  - "# Your custom installation commands here"
+```
+
+## Security Considerations
+
+### Network Security
+
+1. **Restrict CIDR blocks**: Only allow access from your known IP ranges
+2. **Use VPC endpoints**: For private communication with AWS services
+3. **Enable VPC Flow Logs**: For network monitoring and debugging
+
+### AWS Authentication
+
+Use [OIDC for GitHub Actions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) instead of long-term credentials:
+
+```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
+```
+
+### Instance Security
+
+- **Terminate instances** immediately after use
+- **Monitor costs** with AWS billing alerts
+- **Use least-privilege IAM roles** for instance profiles
+- **Enable CloudTrail** for audit logging
+
+## Troubleshooting
+
+### Common Issues
+
+**Instance not responding:**
+
+- Check security group rules allow necessary ports
+- Verify instance has passed all status checks
+- Ensure AMI is compatible with selected instance type
+
+**Connection timeouts:**
+
+- Verify network connectivity from runner to instance
+- Check VPC routing and internet gateway configuration
+- Confirm instance is in correct subnet
+
+**AWS CLI errors:**
+
+- Validate AWS credentials and permissions
+- Check AWS service quotas and limits
+- Verify region consistency across all resources
+
+### Getting Help
+
+For enterprise customers:
+
+- Contact your account manager for AMI access issues
+- Use support channels for infrastructure questions
+- Check the TestDriver documentation for CLI usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "6.1.4",
+  "version": "6.1.5-canary.b2eb46e.0",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "index.js",
   "bin": {

package/setup/aws/cloudformation.yaml

@@ -0,0 +1,463 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >-
+  Baseline artifacts (NO EC2 instance): Creates a dedicated VPC with public subnet, Security Group, 
+  IAM Role/Profile, optional KeyPair, and an EC2 Launch Template so you can spawn many instances 
+  programmatically. Writes handy IDs into SSM Parameter Store for easy lookup in scripts or automation.
+
+Metadata:
+  AWS::CloudFormation::Interface:
+    ParameterGroups:
+      - Label:
+          default: "Notification Configuration"
+        Parameters:
+          - NotificationEmail
+      - Label:
+          default: "Project Configuration"
+        Parameters:
+          - ProjectTag
+      - Label:
+          default: "Network Configuration"
+        Parameters:
+          - AllowedIngressCidr
+      - Label:
+          default: "Instance Configuration"
+        Parameters:
+          - InstanceType
+      - Label:
+          default: "Key Pair Configuration"
+        Parameters:
+          - CreateKeyPair
+          - ExistingKeyName
+    ParameterLabels:
+      ProjectTag:
+        default: "Project Tag"
+      InstanceType:
+        default: "Instance Type"
+      AllowedIngressCidr:
+        default: "Allowed Ingress CIDR"
+      CreateKeyPair:
+        default: "Create New Key Pair"
+      ExistingKeyName:
+        default: "Existing Key Name (only required if 'Create New Key Pair' is 'no')"
+      NotificationEmail:
+        default: "Notification Email (optional)"
+
+Rules:
+  ValidateKeyPairConfiguration:
+    RuleCondition: !Equals [!Ref CreateKeyPair, "no"]
+    Assertions:
+      - Assert: !Not [!Equals [!Ref ExistingKeyName, ""]]
+        AssertDescription: "ExistingKeyName must be provided when CreateKeyPair is 'no'"
+
+Parameters:
+  NotificationEmail:
+    Type: String
+    Default: ""
+    Description: Email address to receive deployment completion notifications (optional)
+
+  ProjectTag:
+    Type: String
+    Default: testdriver
+
+  InstanceType:
+    Type: String
+    Default: c5.xlarge
+    AllowedValues:
+      - c5.xlarge
+      - c5.2xlarge
+      - c5.4xlarge
+      - c5.9xlarge
+      - c5.12xlarge
+      - c5.18xlarge
+      - c5.24xlarge
+      - c5.metal
+      - i3.metal
+    Description: Instance type - only c5.xlarge or larger, plus c5.metal and i3.metal allowed
+
+  AllowedIngressCidr:
+    Type: String
+    Default: 0.0.0.0/0
+    Description: CIDR allowed to access inbound ports (0.0.0.0/0 means "anyone", we recommend tightening this in production).
+
+  CreateKeyPair:
+    Type: String
+    AllowedValues: [yes, no]
+    Default: yes
+    Description: Create a new key pair for instance access? (If 'no', you must provide an existing key name)
+  ExistingKeyName:
+    Type: String
+    Default: ""
+    Description: Name of existing EC2 Key Pair (only required when CreateKeyPair is 'no')
+
+Conditions:
+  UseExistingKeyProvided: !Not [!Equals [!Ref ExistingKeyName, ""]]
+  CreateKey: !Equals [!Ref CreateKeyPair, "yes"]
+  SendNotification: !Not [!Equals [!Ref NotificationEmail, ""]]
+
+Resources:
+  # VPC for TestDriver
+  TestDriverVpc:
+    Type: AWS::EC2::VPC
+    Properties:
+      CidrBlock: 10.0.0.0/16
+      EnableDnsHostnames: true
+      EnableDnsSupport: true
+      Tags:
+        - { Key: Name, Value: !Sub "${AWS::StackName}-vpc" }
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  # Public subnet for EC2 instances
+  PublicSubnet:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref TestDriverVpc
+      CidrBlock: 10.0.1.0/24
+      AvailabilityZone: !Select [0, !GetAZs ""]
+      MapPublicIpOnLaunch: true
+      Tags:
+        - { Key: Name, Value: !Sub "${AWS::StackName}-public-subnet" }
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  # Internet Gateway
+  InternetGateway:
+    Type: AWS::EC2::InternetGateway
+    Properties:
+      Tags:
+        - { Key: Name, Value: !Sub "${AWS::StackName}-igw" }
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  # Attach Internet Gateway to VPC
+  AttachGateway:
+    Type: AWS::EC2::VPCGatewayAttachment
+    Properties:
+      VpcId: !Ref TestDriverVpc
+      InternetGatewayId: !Ref InternetGateway
+
+  # Route table for public subnet
+  PublicRouteTable:
+    Type: AWS::EC2::RouteTable
+    Properties:
+      VpcId: !Ref TestDriverVpc
+      Tags:
+        - { Key: Name, Value: !Sub "${AWS::StackName}-public-rt" }
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  # Route to Internet Gateway
+  PublicRoute:
+    Type: AWS::EC2::Route
+    DependsOn: AttachGateway
+    Properties:
+      RouteTableId: !Ref PublicRouteTable
+      DestinationCidrBlock: 0.0.0.0/0
+      GatewayId: !Ref InternetGateway
+
+  # Associate route table with public subnet
+  SubnetRouteTableAssociation:
+    Type: AWS::EC2::SubnetRouteTableAssociation
+    Properties:
+      SubnetId: !Ref PublicSubnet
+      RouteTableId: !Ref PublicRouteTable
+
+  SecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: SG for QA desktop testing (RDP/HTTPS/NGINX/pyautogui + VNC)
+      VpcId: !Ref TestDriverVpc
+      SecurityGroupIngress:
+        - {
+            IpProtocol: tcp,
+            FromPort: 8765,
+            ToPort: 8765,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "pyautogui-cli WebSockets",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 8443,
+            ToPort: 8443,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "Custom 8443",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 8080,
+            ToPort: 8080,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "NGINX 8080",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 80,
+            ToPort: 80,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "HTTP 80",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 443,
+            ToPort: 443,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "HTTPS 443",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 3389,
+            ToPort: 3389,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "RDP 3389",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 5900,
+            ToPort: 5900,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "TightVNC 5900",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 5901,
+            ToPort: 5901,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "noVNC Websockify 5901",
+          }
+        - {
+            IpProtocol: tcp,
+            FromPort: 6080,
+            ToPort: 6080,
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "noVNC HTTP 6080",
+          }
+      SecurityGroupEgress:
+        - IpProtocol: -1
+          CidrIp: 0.0.0.0/0
+          Description: Allow all outbound
+      Tags:
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  InstanceRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal: { Service: ec2.amazonaws.com }
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
+      Tags:
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  InstanceProfile:
+    Type: AWS::IAM::InstanceProfile
+    Properties:
+      Roles: [!Ref InstanceRole]
+
+  KeyPair:
+    Type: AWS::EC2::KeyPair
+    Condition: CreateKey
+    Properties:
+      KeyName: !Sub "${AWS::StackName}-key"
+      KeyType: rsa
+
+  LaunchTemplate:
+    Type: AWS::EC2::LaunchTemplate
+    Properties:
+      LaunchTemplateName: !Sub "${AWS::StackName}-lt"
+      LaunchTemplateData:
+        InstanceType: !Ref InstanceType
+        IamInstanceProfile:
+          Name: !Ref InstanceProfile
+        # Lock SG + Subnet to the same VPC
+        NetworkInterfaces:
+          - DeviceIndex: 0
+            SubnetId: !Ref PublicSubnet
+            Groups: [!Ref SecurityGroup]
+            AssociatePublicIpAddress: true
+        KeyName: !If
+          - CreateKey
+          - !Ref KeyPair
+          - !If
+            - UseExistingKeyProvided
+            - !Ref ExistingKeyName
+            - !Ref AWS::NoValue
+        TagSpecifications:
+          - ResourceType: instance
+            Tags: [{ Key: Project, Value: !Ref ProjectTag }]
+          - ResourceType: volume
+            Tags: [{ Key: Project, Value: !Ref ProjectTag }]
+
+  # SNS Topic for deployment notifications
+  DeploymentNotificationTopic:
+    Type: AWS::SNS::Topic
+    Condition: SendNotification
+    Properties:
+      TopicName: !Sub "${AWS::StackName}-deployment-notifications"
+      DisplayName: !Sub "${AWS::StackName} Deployment Notifications"
+      Tags:
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  # SNS Subscription for email notifications
+  EmailSubscription:
+    Type: AWS::SNS::Subscription
+    Condition: SendNotification
+    Properties:
+      Protocol: email
+      TopicArn: !Ref DeploymentNotificationTopic
+      Endpoint: !Ref NotificationEmail
+
+  # Custom resource to send completion notification
+  DeploymentCompleteNotification:
+    Type: AWS::CloudFormation::CustomResource
+    Condition: SendNotification
+    Properties:
+      ServiceToken: !GetAtt NotificationLambda.Arn
+      StackName: !Ref AWS::StackName
+      TopicArn: !Ref DeploymentNotificationTopic
+    DependsOn:
+      - SsmParamSg
+      - SsmParamIp
+      - SsmParamLt
+      - SsmParamLtLatest
+      - SsmParamVpc
+      - SsmParamSubnet
+
+  # Lambda function to send the notification
+  NotificationLambda:
+    Type: AWS::Lambda::Function
+    Condition: SendNotification
+    Properties:
+      FunctionName: !Sub "${AWS::StackName}-deployment-notifier"
+      Runtime: python3.11
+      Handler: index.lambda_handler
+      Role: !GetAtt NotificationLambdaRole.Arn
+      Code:
+        ZipFile: |
+          import boto3
+          import json
+          import cfnresponse
+
+          def lambda_handler(event, context):
+              try:
+                  if event['RequestType'] == 'Create':
+                      sns = boto3.client('sns')
+                      stack_name = event['ResourceProperties']['StackName']
+                      topic_arn = event['ResourceProperties']['TopicArn']
+                      
+                      message = f"""
+          TestDriver Infrastructure Deployment Complete!
+
+          Stack Name: {stack_name}
+          Status: CREATE_COMPLETE
+
+          Your TestDriver infrastructure is now ready to use.
+          Check the CloudFormation outputs for resource IDs and configuration details.
+                      """
+                      
+                      sns.publish(
+                          TopicArn=topic_arn,
+                          Subject=f'TestDriver Stack {stack_name} - Deployment Complete',
+                          Message=message
+                      )
+                  
+                  cfnresponse.send(event, context, cfnresponse.SUCCESS, {})
+              except Exception as e:
+                  print(f"Error: {e}")
+                  cfnresponse.send(event, context, cfnresponse.FAILED, {})
+      Tags:
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  # IAM Role for the notification Lambda
+  NotificationLambdaRole:
+    Type: AWS::IAM::Role
+    Condition: SendNotification
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: lambda.amazonaws.com
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+      Policies:
+        - PolicyName: SNSPublishPolicy
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action:
+                  - sns:Publish
+                Resource: !Ref DeploymentNotificationTopic
+      Tags:
+        - { Key: Project, Value: !Ref ProjectTag }
+
+  SsmParamSg:
+    Type: AWS::SSM::Parameter
+    Properties:
+      Name: !Sub "/testdriver/infra/${AWS::StackName}/security-group-id"
+      Type: String
+      Value: !Ref SecurityGroup
+
+  SsmParamIp:
+    Type: AWS::SSM::Parameter
+    Properties:
+      Name: !Sub "/testdriver/infra/${AWS::StackName}/instance-profile-name"
+      Type: String
+      Value: !Ref InstanceProfile
+
+  SsmParamLt:
+    Type: AWS::SSM::Parameter
+    Properties:
+      Name: !Sub "/testdriver/infra/${AWS::StackName}/launch-template-id"
+      Type: String
+      Value: !Ref LaunchTemplate
+
+  SsmParamLtLatest:
+    Type: AWS::SSM::Parameter
+    Properties:
+      Name: !Sub "/testdriver/infra/${AWS::StackName}/launch-template-latest-version"
+      Type: String
+      Value: !GetAtt LaunchTemplate.LatestVersionNumber
+
+  SsmParamVpc:
+    Type: AWS::SSM::Parameter
+    Properties:
+      Name: !Sub "/testdriver/infra/${AWS::StackName}/testdriver-vpc-id"
+      Type: String
+      Value: !Ref TestDriverVpc
+
+  SsmParamSubnet:
+    Type: AWS::SSM::Parameter
+    Properties:
+      Name: !Sub "/testdriver/infra/${AWS::StackName}/testdriver-public-subnet-id"
+      Type: String
+      Value: !Ref PublicSubnet
+
+Outputs:
+  VpcId:
+    Value: !Ref TestDriverVpc
+    Description: VPC ID created for TestDriver
+  SubnetId:
+    Value: !Ref PublicSubnet
+    Description: Public subnet ID for TestDriver instances
+  SecurityGroupId:
+    Value: !Ref SecurityGroup
+    Description: Security Group for QA desktop testing
+  InstanceProfileName:
+    Value: !Ref InstanceProfile
+    Description: Instance Profile to attach to instances
+  LaunchTemplateId:
+    Value: !Ref LaunchTemplate
+    Description: EC2 Launch Template ID
+  LaunchTemplateLatestVersion:
+    Value: !GetAtt LaunchTemplate.LatestVersionNumber
+    Description: Latest Launch Template version
+  KeyPairSsmParam:
+    Condition: CreateKey
+    Value: !Sub "/ec2/keypair/${KeyPair.KeyPairId}"
+    Description: SSM parameter that stores the generated private key
+  SsmNamespaceUsed:
+    Value: !Sub "/testdriver/infra/${AWS::StackName}"
+    Description: Prefix where IDs are stored for discovery

package/setup/aws/spawn-runner.sh

@@ -0,0 +1,189 @@
+#!/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}"
+
+TAG_NAME="${AWS_TAG_PREFIX}-"$(date +%s)
+WS_CONFIG_PATH='C:\Windows\Temp\pyautogui-ws.json'
+
+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}}]" \
+  --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
+
+echo "Getting Public IP..."
+
+# # --- 4) 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"
+
+# echo "Getting Websocket Port..."
+
+
+# --- 5) Read WebSocket config JSON ---
+echo "Reading WebSocket configuration from: $WS_CONFIG_PATH"
+READ_JSON=$(aws ssm send-command \
+  --region "$AWS_REGION" \
+  --instance-ids "$INSTANCE_ID" \
+  --document-name "AWS-RunPowerShellScript" \
+  --parameters "commands=[\"if (Test-Path '${WS_CONFIG_PATH}') { Get-Content -Raw '${WS_CONFIG_PATH}' } else { Write-Output 'Config file not found at ${WS_CONFIG_PATH}' }\"]" \
+  --output json)
+
+READ_CMD_ID=$(jq -r '.Command.CommandId' <<<"$READ_JSON")
+echo "WebSocket config read command ID: $READ_CMD_ID"
+
+echo "Waiting for WebSocket config command to complete..."
+aws ssm wait command-executed --region "$AWS_REGION" --command-id "$READ_CMD_ID" --instance-id "$INSTANCE_ID"
+
+INVOC=$(aws ssm get-command-invocation \
+  --region "$AWS_REGION" \
+  --command-id "$READ_CMD_ID" \
+  --instance-id "$INSTANCE_ID" \
+  --output json)
+
+STDOUT=$(jq -r '.StandardOutputContent // ""' <<<"$INVOC")
+STDERR=$(jq -r '.StandardErrorContent // ""' <<<"$INVOC")
+CMD_STATUS=$(jq -r '.Status // ""' <<<"$INVOC")
+
+echo "WebSocket config command status: $CMD_STATUS"
+if [ -n "$STDERR" ] && [ "$STDERR" != "null" ]; then
+  echo "WebSocket config stderr: $STDERR"
+fi
+echo "WebSocket config raw output: $STDOUT"
+
+# --- 6) Output results ---
+echo "Setup complete!"
+echo "PUBLIC_IP=$PUBLIC_IP"
+echo "INSTANCE_ID=$INSTANCE_ID"
+echo "AWS_REGION=$AWS_REGION"