Documentation

Master QA Guardian - the distributed test automation platform built for scale. Learn how to create, execute, and manage tests.

Get Started View Architecture

Getting Started

Everything you need to begin using Guardian for automated testing.

Start Testing in Minutes

Guardian makes it easy to set up automated tests. Create test flows with Playwright, connect to your CI/CD pipeline, and start catching bugs before they reach production.

No complex infrastructure needed

Kubernetes scaling built-in

Real-time debugging with live sessions

API Authentication

Secure JWT token-based authentication. Generate keys in your dashboard and start building integrations.

Learn more

Comprehensive Guides

Step-by-step guides for test creation, execution, debugging, and CI/CD integration.

Explore

System Architecture

Understand Guardian's distributed microservices architecture and how components work together.

View diagram

REST API Reference

Full API documentation with endpoints for tests, flows, execution, and analytics.

API Docs

Code Examples

Ready-to-use code snippets and examples for common Guardian workflows.

View examples

Test Flow Creation

Learn to create and organize test flows using Playwright with Guardian's test recorder.

Test Execution

Execute tests via the UI or API. Guardian handles sharding and parallel execution automatically.

Live Debugging

Debug tests in real-time with VNC access, stepping through actions, and visual feedback.

Test Results & Analytics

Access detailed test reports, videos, traces, and analytics for every test run.

CI/CD Integration

Integrate Guardian with your CI/CD pipeline via REST API or scheduler service.

User & Tenant Management

Manage users, roles, permissions, and multiple tenant environments.

Key Concepts

Test Flow

A collection of related tests organized together for grouped execution. Run 50-100 tests in parallel across Kubernetes pods with automatic sharding.

Sharding

Automatic distribution of tests across multiple parallel pods. Guardian calculates optimal shard count so each pod runs ~10-15 tests, reducing total runtime by 80-90%.

Executor

FastAPI service that spawns Kubernetes jobs. Each pod runs Playwright tests independently, uploads videos/traces to Storage service, reports results back to Coordinator.

Recording & Artifacts

Full test recordings, screenshots, DOM traces, and network logs. Average 500MB per test run. Stored in Google Cloud Storage with 30-day retention configurable per tenant.

Quick Start: Your First API Call

1. Get Your API Token

curl -X POST https://api.quaguardian.com/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_email@company.com",
    "password": "your_password"
  }'

# Response:
# {
#   "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
#   "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc...",
#   "user": { "id": 123, "email": "..." }
# }

2. Trigger a Test Run

curl -X POST https://api.quaguardian.com/api/v1/testing/runs/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": 42,
    "browser": "chromium",
    "environment": "staging"
  }'

# Response:
# {
#   "id": "run-7f3a9e2c",
#   "status": "queued",
#   "started_at": "2024-11-01T15:30:00Z",
#   "estimated_duration_seconds": 120
# }

3. Poll for Results

curl https://api.quaguardian.com/api/v1/testing/runs/run-7f3a9e2c/results/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response:
# {
#   "run_id": "run-7f3a9e2c",
#   "status": "completed",
#   "total_tests": 47,
#   "passed": 45,
#   "failed": 2,
#   "skipped": 0,
#   "duration_seconds": 118,
#   "artifacts": {
#     "videos_url": "gs://...",
#     "traces_url": "gs://...",
#     "report_url": "https://dashboard.quaguardian.com/runs/7f3a9e2c"
#   }
# }

Common Workflows

Step-by-step guides for typical Guardian use cases.

GitHub Actions Integration

Run Guardian tests as part of your GitHub workflow

Add Secret

Store GUARDIAN_API_TOKEN in GitHub Secrets

Create Workflow

.github/workflows/test.yml

Trigger on Push

Runs on every commit to main branch

name: Guardian E2E Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Guardian Tests
        run: |
          curl -X POST https://api.quaguardian.com/api/v1/testing/runs/ \
            -H "Authorization: Bearer {{ secrets.GUARDIAN_API_TOKEN }}" \
            -d '{"flow_id": 42, "browser": "chromium"}'

Node.js SDK Example

Programmatic test execution in your Node app

Install SDK

npm install @guardian/sdk

Initialize Client

Create Guardian client instance

Execute & Monitor

Run tests and handle results

const Guardian = require('@guardian/sdk');
const client = new Guardian.Client({
  apiToken: process.env.GUARDIAN_TOKEN
});

async function runTests() {
  const run = await client.runs.create({
    flowId: 42,
    browser: 'chromium'
  });

  const results = await run.waitForCompletion();
  console.log(`Tests: ${results.passed}/${results.total} passed`);
  return results.passed === results.total;
}

GitLab CI/CD Pipeline

Integrate Guardian with your GitLab CI pipeline

Define Variable

$GUARDIAN_API_TOKEN in CI/CD settings

Add Stage

Add 'test' stage to .gitlab-ci.yml

Parse Results

Fail pipeline if tests fail

stages:
  - build
  - test
  - deploy

e2e_tests:
  stage: test
  script:
    - |
      RESULT=$(curl -s -X POST https://api.quaguardian.com/api/v1/testing/runs/ \
        -H "Authorization: Bearer $GUARDIAN_API_TOKEN" \
        -d '{"flow_id": 42}')
      echo $RESULT | jq .
  allow_failure: false

Python Automation Script

Trigger tests from Python and parse results

Setup

pip install requests

Authenticate

Get JWT token from Guardian

Run & Analyze

Execute and generate reports

import requests
import time

def run_guardian_tests(flow_id):
  headers = {'Authorization': f'Bearer {token}'}

  # Trigger test run
  response = requests.post(
    'https://api.quaguardian.com/api/v1/testing/runs/',
    headers=headers,
    json={'flow_id': flow_id, 'browser': 'chromium'}
  )
  run_id = response.json()['id']

  # Poll for results
  while True:
    result = requests.get(
      f'https://api.quaguardian.com/api/v1/testing/runs/{run_id}/results/',
      headers=headers
    ).json()

    if result['status'] == 'completed':
      print(f"✓ {result['passed']}/{result['total']} tests passed")
      break

    time.sleep(5)

Troubleshooting Common Issues

🔴 Tests Timeout

Problem: Test run exceeds 30 minutes

Check for infinite loops in test code
Increase timeout in Guardian dashboard
Split large flows (max 250 tests/run)

❌ 401 Unauthorized

Problem: Invalid or expired JWT token

Refresh token using /api/auth/token/refresh/
Verify token has not expired (check exp claim)
Check Authorization header format

⚠️ 429 Rate Limited

Problem: Exceeded 100 requests/minute

Implement exponential backoff for retries
Batch requests when possible
Contact support for higher limits

🐛 Flaky Tests

Problem: Tests fail sporadically

Add explicit waits for elements/networks
Use data-testid selectors instead of CSS
Review video artifacts in dashboard

Best Practices & SDKs

Optimize your test execution and follow recommended patterns.

🚀 Optimization Tips

1
Keep Tests Focused
Each test should verify one user workflow. Avoid long test chains.
2
Use Page Objects
Centralize selectors in page object classes for easier maintenance.
3
Add Explicit Waits
Use waitForSelector instead of hard sleeps.
4
Parallel Execution
Split tests into separate files for automatic parallelization across pods.
5
Environment Variables
Use env vars for URLs, credentials, and test data per environment.

📦 Available SDKs

Node.js SDK

npm install @guardian/sdk

Full-featured SDK for Node.js applications

Python SDK

pip install guardian-sdk

Python SDK for test automation scripts

JavaScript SDK

yarn add @guardian/js-sdk

Browser-compatible SDK for frontend apps

Go SDK

go get github.com/guardian/sdk-go

Type-safe Go SDK for backend integration

REST API

cURL / Postman

Direct HTTP access to all Guardian endpoints

📚 Example Repository

Check out our GitHub examples with ready-to-use test flows, CI/CD configurations, and best practices:

github.com/guardian/examples

✓ React application E2E tests
✓ Next.js integration example
✓ GitHub Actions workflow
✓ GitLab CI configuration
✓ Docker setup for local testing
✓ Slack notification integration

Need More Help?

Can't find what you're looking for? We're here to help.

📧

Contact Support

Get help from our dedicated support team for issues or questions.

Learn More

📅

Schedule a Demo

Get a personalized walkthrough of Guardian's features and capabilities.

Learn More