Home / Documentation

Documentation

Getting Started

Get up and running with TraceLoom in 5 minutes. Run your Playwright tests in parallel on your own AWS infrastructure — no vendor lock-in, complete data sovereignty.

Prerequisites

  • AWS account with appropriate permissions (or admin access)
  • Node.js 18+ installed
  • An existing Playwright test suite

Step 1: Create Your Account

Sign up at app.traceloom.io/signup. The free tier includes 50 runs per month — no credit card required.

Once signed in, you land on the onboarding wizard. It walks you through connecting your AWS account and importing your first test suite.

Step 2: Connect Your AWS Account

TraceLoom uses a cross-account IAM role — your credentials never leave your control. The CloudFormation template creates exactly the permissions TraceLoom needs, nothing more.

  1. Click Deploy CloudFormation Stack in the onboarding wizard (or see BYOC Setup for manual deployment steps)
  2. AWS Console opens with the pre-filled CloudFormation template
  3. Review the resources created: IAM role, S3 bucket, SQS queue, Auto Scaling Group
  4. Click Create stack — deployment takes around 3 minutes
  5. TraceLoom validates the connection automatically after stack creation
# The CloudFormation template deploys these resources in your account:
# - IAM cross-account role (TraceLoomExecutionRole)
# - S3 bucket for Playwright traces
# - SQS queue for job distribution
# - EC2 Auto Scaling Group (Spot instances)

# After deployment, TraceLoom validates your connection:
# ✓ STS AssumeRole
# ✓ S3 write access
# ✓ SQS send/receive
# ✓ EC2 describe instances

Step 3: Import Your Tests

TraceLoom auto-detects your Playwright configuration, dependencies, and test files.

Option A: Connect a GitHub Repository

  1. Click Import from GitHub in the dashboard
  2. Authorize TraceLoom to read your repositories
  3. Select the repository and branch containing your Playwright tests
  4. TraceLoom parses your playwright.config.ts and identifies all test files

Option B: Upload from S3

  1. Click Import from S3 in the dashboard
  2. Enter the S3 URI of your zipped test suite
  3. TraceLoom downloads, extracts, and analyzes the contents
# S3 upload format: zip your test directory
zip -r my-tests.zip . -x "node_modules/*" -x ".git/*"

# Upload to your S3 bucket
aws s3 cp my-tests.zip s3://your-bucket/imports/my-tests.zip

# Or upload directly through the TraceLoom dashboard UI

Step 4: Run Your First Test

  1. Click New Run from the dashboard (or the Runs page)
  2. Select the imported test suite
  3. Choose which test files to include (all by default)
  4. Click Start Run

TraceLoom shards your tests across Spot instances automatically. With 100 tests and 10 workers, you get roughly 10x parallelism — a 30-minute suite finishes in around 3 minutes. 

# TraceLoom distributes tests across your EC2 Spot instances:
# - Auto Scaling Group scales up on demand
# - Tests sharded evenly across available workers
# - Each worker runs: npm ci && npx playwright test [shard]
# - Spot instances terminate when idle (no idle billing)

Step 5: View Results

When the run completes, the dashboard shows:

  • Pass/fail breakdown per test file and per individual test
  • Execution time per test with parallel timeline visualization
  • Full Playwright traces available for download — every test, every run
  • Console logs, network requests, and screenshots captured in traces

Open any trace directly in the browser with one click — no local setup required:

# Traces are stored in your S3 bucket under:
# s3://your-traces-bucket/runs/[run-id]/[test-name]/trace.zip

# View traces locally with the Playwright CLI:
aws s3 cp s3://your-bucket/runs/run-123/checkout.spec/trace.zip .
npx playwright show-trace trace.zip

# Or use the built-in trace viewer in the TraceLoom dashboard

Every trace stays in your AWS account — TraceLoom never copies your test data out of your infrastructure.

Next Steps

  • BYOC Setup — detailed CloudFormation configuration, IAM permissions, security model, and cost breakdown
  • Pricing — compare plans and find the right tier for your team
  • Create your account — free tier, no credit card required