Getting Started

Run distributed Playwright tests on your own AWS infrastructure with full trace capture.

Prerequisites

• AWS account with permissions to create IAM roles, S3 buckets, and CloudWatch log groups
• Node.js 18+ installed
• Playwright installed in your project (npm install -D @playwright/test)

Sign Up and Create Your Account

Sign up at app.traceloom.io. Enter your email address and verify it. TraceLoom offers a free tier; however, BYOC setup deploys AWS resources (EC2, S3, SQS, DynamoDB) into your account which incur standard AWS charges.

After verifying your email, you land on the onboarding wizard. It walks you through two steps:

1. Enter your company name
2. Connect your AWS account (BYOC setup)

Connect Your AWS Account (BYOC)

TraceLoom stores traces and runs tests in your AWS account. Your Playwright trace files never leave your infrastructure — TraceLoom only reads run metadata.

Follow the BYOC Setup guide for full details on creating the IAM role, configuring the trust policy, and validating the connection.

Generate an API Key

Navigate to Settings → API Keys in the TraceLoom dashboard. Click Create Key, give it a name, and copy the key value. You will need this to authenticate test runs. See the API Keys documentation for details.

Run Your First Test

Once your AWS account is connected, install the TraceLoom CLI and run your first distributed test.

1. Install the CLI

npm install -g traceloom

2. Authenticate

Log in with your TraceLoom account. This stores a session token locally so subsequent commands are authenticated.

traceloom auth

For CI environments, set your API key as an environment variable instead:

export TRACELOOM_API_KEY=tlk_your_api_key_here

3. Initialize your project

Run traceloom init in your Playwright project directory. This creates a .traceloom.yml config file linking your project to your TraceLoom account.

traceloom init

4. Run your tests

Launch a distributed test run. TraceLoom discovers your Playwright tests, shards them across EC2 Spot workers in your AWS account, and streams results back to your terminal.

traceloom run

After the run completes, view results and traces at app.traceloom.io/runs or directly from the CLI with traceloom runs list.

Next Steps

• CLI Reference — install, authenticate, init, and run commands
• BYOC Setup — detailed IAM role setup, trust policy, data residency, and permission requirements
• Schedules — automate test runs on a cron schedule from the TraceLoom dashboard
• Team settings — invite teammates and manage access from Settings
• Billing — upgrade your plan for more runs per month

Last updated: March 2026