Cloud Platform Quickstart

This guide takes you from zero to your first TestRelic cloud session in under 10 minutes. Choose how you want to set it up: You will sign up, configure the Playwright reporter with your API key, run a test, and explore the result in the cloud platform.

Appium / mobile testing

For Appium/WDIO cloud setup, see the Appium Cloud Quickstart.

Prerequisites

• Node.js ≥ 18 and npm/yarn/pnpm
• An existing Playwright project with @testrelic/playwright-analytics installed (see Installation)
• A testrelic.ai account (create one for free below)

Step 1 — Create your account

1. Go to testrelic.ai and click Sign Up.
2. Enter your name, email address, and a password.
3. Check your inbox for a verification code and enter it on the verification screen.

What happens next

After verifying your email, the onboarding wizard walks you through setting your profile, choosing your framework (Playwright), and generating your first API key. See the Onboarding guide for the full walkthrough.

When runs appear in the cloud, you can wire the TestRelic MCP in your IDE so an assistant can query runs, coverage, and failures without copying logs.

Step 2 — Generate an API key

1. In the TestRelic platform, navigate to Settings → API Keys.
2. Click Create new key, give it a name (e.g. my-playwright-project), and copy the key value.
3. Store it securely — the key is shown only once.

Step 3 — Configure the reporter

For AI agents

Configure with an AI assistant

AI Prompt — Add API key to playwright.config.ts

Update my playwright.config.ts to enable TestRelic cloud upload.

1. Add apiKey: process.env.TESTRELIC_API_KEY and repoId: process.env.TESTRELIC_REPO_ID
   to the @testrelic/playwright-analytics reporter options.
2. Create a .env file in the project root:
   TESTRELIC_API_KEY=my_key_here
   TESTRELIC_REPO_ID=my_repo_id_here
3. Add .env to .gitignore.

Show me the updated playwright.config.ts reporter section.

---

Set up CI with an AI assistant

GitHub Actions

AI Prompt — GitHub Actions for Playwright cloud

Create a GitHub Actions workflow file at .github/workflows/playwright.yml that:
1. Runs on push and pull_request events
2. Uses node 20
3. Runs: npm ci
4. Runs: npx playwright install --with-deps
5. Runs: npx playwright test
6. Passes TESTRELIC_API_KEY and TESTRELIC_REPO_ID from GitHub secrets as environment variables

Show me the complete workflow file.

GitLab CI

AI Prompt — GitLab CI for Playwright cloud

Create a GitLab CI config (.gitlab-ci.yml) for my Playwright project that:
1. Uses the mcr.microsoft.com/playwright:v1.49.0-noble image
2. Passes TESTRELIC_API_KEY and TESTRELIC_REPO_ID from GitLab CI variables
3. Runs npm ci and npx playwright test

Show me the complete .gitlab-ci.yml.

For Human

Add the apiKey to your @testrelic/playwright-analytics options in playwright.config.ts:

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['list'],
    [
      '@testrelic/playwright-analytics',
      {
        apiKey: process.env.TESTRELIC_API_KEY,
        repoId: process.env.TESTRELIC_REPO_ID,
      },
    ],
  ],
  // ... rest of your config
});

Set the environment variables. In development, add them to a .env file in the root of your project (never commit this file):

.env

# Never commit this file — add .env to .gitignore
TESTRELIC_API_KEY=your_api_key_here
TESTRELIC_REPO_ID=your_repo_id_here

Using environment variables

Playwright v1.49+ loads .env automatically when you use npx playwright test. For earlier versions, install and use dotenv.

CI configuration

GitHub Actions

Add TESTRELIC_API_KEY and TESTRELIC_REPO_ID as repository secrets in Settings → Secrets and variables → Actions, then reference them in your workflow:

.github/workflows/playwright.yml

name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
        env:
          TESTRELIC_API_KEY: ${{ secrets.TESTRELIC_API_KEY }}
          TESTRELIC_REPO_ID: ${{ secrets.TESTRELIC_REPO_ID }}

GitLab CI

.gitlab-ci.yml

playwright:
  image: mcr.microsoft.com/playwright:v1.49.0-noble
  variables:
    TESTRELIC_API_KEY: $TESTRELIC_API_KEY
    TESTRELIC_REPO_ID: $TESTRELIC_REPO_ID
  script:
    - npm ci
    - npx playwright test

Step 4 — Run your tests

npx playwright test

The reporter runs alongside your tests. After the run completes, it uploads the data to the TestRelic cloud platform automatically. You should see a confirmation line in the reporter output:

✓ TestRelic: Run uploaded — https://testrelic.ai/dashboards/test-runs/<runId>

Step 5 — Explore the result in the platform

1. Click the URL printed by the reporter, or navigate to the Test Runs dashboard.
2. You should see your test run in the list. Click it to open the Run Detail view.
3. Click any test case row to open the Session Workspace — the full DevTools-style inspection view.

What to explore next

Feature	What to try
Session Workspace	Inspect steps, console output, network requests, and video
AI Insights	On a failing test, check the Insights tab for AI-generated defect analysis (Growth plan)
Ask AI	Ask "What were the most common failures in the last 7 days?"
Test Navigation	See a graph of all URL navigation flows captured in your sessions
Repositories	View repo-level health metrics, pass rates, and framework setup snippets

Troubleshooting

Reporter output says "API key invalid" Double-check the TESTRELIC_API_KEY value in your environment. Ensure there are no extra spaces. Verify the key is active in API Keys settings.

No run appears in the dashboard Ensure your network can reach platform.testrelic.ai. Check if a corporate proxy or firewall is blocking outbound HTTPS. The reporter logs connection errors at the end of the test run.

Runs appear but sessions are missing network data Network data requires includeNetworkStats: true in your reporter options (default: true). If you explicitly set it to false, re-enable it to capture network activity.

Video is missing from sessions Video capture requires video: 'on' or video: 'retain-on-failure' in your Playwright config's use block.

---

Need more detail? See the full configuration reference for all reporter options.