/testdriver-aws-setup

name: testdriver:aws-setup
description: Deploy TestDriver on your AWS infrastructure using CloudFormation

<!-- Generated from aws-setup.mdx. DO NOT EDIT. -->

This guide walks you through setting up self-hosted TestDriver instances on AWS. By the end, you'll have fully automated test infrastructure that spawns and terminates instances on-demand.

graph LR
    A[Vitest Test] --> B[setup-aws hook]
    B --> C[Spawns EC2]
    C --> D[Runs Test]
    D --> E[Terminates EC2]

How It Works

TestDriver automatically manages AWS EC2 instances for your tests:

1. **Deploy CloudFormation** — One-time infrastructure setup 2. **Configure Vitest** — Add one line to your config 3. **Run Tests** — Instances spawn automatically, run tests, and terminate

That's it! No manual instance management needed.

Quickstart

<Steps> <Step title="Deploy Infrastructure"> <Card title="Launch CloudFormation Stack" icon="aws" href="https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https://v7-cloudformation-template.s3.us-east-2.amazonaws.com/cloudformation.yaml" horizontal arrow > One-click AWS setup </Card> </Step>

<Step title="Add to Vitest Config">

    setupFiles: ['testdriverai/vitest/setup', 'testdriverai/vitest/setup-aws']

</Step>

<Step title="Run Tests">

    TD_OS=windows AWS_REGION=us-east-2 \
      AWS_LAUNCH_TEMPLATE_ID=lt-xxx AMI_ID=ami-xxx \
      vitest run

</Step> </Steps>

Overview

The setup process is simple:

1. **Deploy CloudFormation** — Creates VPC, security groups, IAM roles, and launch templates 2. **Configure Vitest** — Add `setup-aws` to automatically manage instance lifecycle 3. **Run Tests** — Set `TD_OS=windows` with AWS credentials and instances spawn/terminate automatically

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](http://testdriver.ai/demo) with your AWS region
• A GitHub repository for your tests

<Tip> The TestDriver Golden Image AMI ID is `ami-0504bf50fad62f312`. 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

<Tabs> <Tab title="GUI"> Click the button below to launch the CloudFormation stack in your AWS Console:

<Card title="Launch Stack" icon="aws" href="https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https://v7-cloudformation-template.s3.us-east-2.amazonaws.com/cloudformation.yaml" horizontal arrow > Deploy TestDriver infrastructure with one click </Card>

Configure the stack parameters:

• **Stack name**: `testdriver-infrastructure` (or your preferred name)
• **ProjectTag**: `testdriver`
• **AllowedIngressCidr**: Your IP range (e.g., `203.0.113.0/24`)
• **InstanceType**: `c5.xlarge` (recommended)
• **CreateKeyPair**: `true`

<Warning> **Security**: Replace `AllowedIngressCidr` with your specific IP ranges to restrict VPC access. Avoid using `0.0.0.0/0` in production. </Warning>

Get Your Launch Template ID

After the stack creation completes, navigate to the **Outputs** tab to find your `LaunchTemplateId`:


<Tip> **Save this ID** — you'll need it for spawning instances and CI configuration. </Tip> </Tab> <Tab title="CLI"> Download the template from the [TestDriver CLI repository](https://github.com/testdriverai/testdriverai/blob/main/setup/aws/cloudformation.yaml), then deploy:

    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:

    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> </Tab> </Tabs>

Step 2: Configure Vitest

Add the AWS setup hook to your `vitest.config.mjs`:

import { defineConfig } from 'vitest/config';
import { config } from 'dotenv';
import TestDriver from 'testdriverai/vitest';

config(); // Load .env file

export default defineConfig({
  test: {
    testTimeout: 900000,
    hookTimeout: 900000,
    maxConcurrency: 3,
    reporters: [
      'default',
      TestDriver(),
      ['junit', { outputFile: 'test-report.junit.xml' }]
    ],
    setupFiles: ['testdriverai/vitest/setup', 'testdriverai/vitest/setup-aws'],
  },
});

<Note> **That's it!** The `setup-aws` hook automatically spawns and terminates instances when `TD_OS=windows` is set. No manual instance management needed. </Note>

Step 3: Write Your Tests

Tests should use `context.ip || process.env.TD_IP` for the IP configuration:

import { describe, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("My Test", () =>