AstraZ AI QA OPS (astraz-qa)

Local-first QA runner for AI/web agencies. Record browser flows, generate Playwright tests, export CI pipelines.

Quick Start

# Install globally or use npx
npx astraz-qa doctor

# Record a browser flow
npx astraz-qa record https://your-app.com --name login

# Open Studio to edit flows and assertions
npx astraz-qa studio

# Export Playwright tests and GitHub Actions workflow
npx astraz-qa export --flow login

# Run tests in CI
npx astraz-qa run --ci --all

Commands

| Command | Description | |---|---| | doctor [--dir <path>] [--debug] | Check project health, Playwright versions, proxy, artifacts | | login | Authenticate via RFC 8628 device flow | | logout | Remove local credentials and revoke server tokens | | license status | Show license and plan info | | record <url> --name <name> | Record a browser flow with Chromium | | studio [--port 4321] | Open visual flow editor in browser | | export [--flow <name>] [--output <dir>] | Generate Playwright tests + GitHub Actions | | run --ci [--flow <name>\|--all] | Run tests, sync results, detect flaky vs failed | | sync-playwright | Align all flows to one Playwright version |

How It Works

1. Record: Launch Chromium, interact with your app. AstraZ captures clicks, fills, navigation, uploads, dialogs, and SPA routes.
2. Edit: Open Studio to review steps, add assertions, configure branding, manage dependencies between flows.
3. Export: Generate idiomatic Playwright test files and a GitHub Actions workflow with Docker image pinning.
4. Run: Execute tests in CI with retry support, flaky detection, and optional telemetry sync.

Project Structure

.astraz/
  project.json          # Project metadata + fingerprint
  config.json           # Masking config (redact keys, patterns)
  branding.json         # Company name, colors, footer
  authorization.json    # Recording authorization log
  flows/<flow-name>/
    flow.json           # Recorded flow steps + assertions
    screenshots/
    traces/
    history/            # Last 20 versions of flow.json
  reports/              # Generated HTML QA reports
  pending-sync/         # CI result sync queue
  astraz-debug.log      # JSON Lines debug log

Configuration

Environment Variables

| Variable | Purpose | |---|---| | BASE_URL | Target URL for Playwright tests in CI | | ASTRAZ_TOKEN | CI token for syncing results to Supabase | | ASTRAZ_API_URL | Supabase Edge Function base URL | | HTTPS_PROXY | Proxy URL (Basic auth supported) |

Masking

AstraZ redacts sensitive data before writing to disk. Configure in .astraz/config.json:

{
  "redactKeys": ["custom_secret"],
  "redactPatterns": ["SSN-\\d{3}-\\d{2}-\\d{4}"],
  "allowFields": ["email"]
}

Protected fields (authorization, cookie, password, etc.) can never be added to allowFields.

CI Integration

The exported GitHub Actions workflow (.github/workflows/astraz.yml):

• Uses official Playwright Docker image when versions are consistent
• Falls back to npx playwright install --with-deps chromium
• Waits for staging URL with wait-on
• Retries flaky tests (2 retries in CI)
• Uploads failure artifacts with 5-day retention
• Uses actions/checkout@v6, actions/setup-node@v6, actions/upload-artifact@v7

Requirements

• Node.js 20+ (20, 22, 24 supported)
• Playwright (bundled as dependency)
• Works on Windows, macOS, and Linux

Security

• Credentials stored in ~/.astraz/credentials.json with HMAC integrity check
• File permissions set to 0600 on macOS/Linux (best-effort on Windows)
• CI tokens are hashed (SHA-256) before storage — plain token shown once
• Sensitive values replaced with [ASTRAZ_REDACTED] before disk write
• No raw keystrokes logged for sensitive fields
• Proxy credentials masked in all logs
• See SECURITY.md for vulnerability reporting

Legal

⚠ DISCLAIMER: AstraZ AI QA OPS is an automated testing aid provided strictly "AS IS". It does NOT guarantee bug-free software, security, uptime, or fitness for any purpose. Always perform manual QA on critical paths before production deployment.

• Terms of Service — License scope, liability limitations, acceptable use
• Privacy Policy — Zero PII, local-first data handling
• Security Policy — Vulnerability reporting, architecture overview

Data Deletion

To remove all AstraZ data from your system:

# Remove project data
rm -rf .astraz/

# Remove credentials and install secret
rm -rf ~/.astraz/

# Remove generated test files (if exported)
rm -rf astraz-tests/

License

Copyright © 2026 AstraZ AI. All rights reserved. Proprietary software. See LICENSE for details.