qa360

QA360 Proof CLI - Quality as Cryptographic Proof

Official package published by xyqotech with npm provenance signatures

Installation

Option 1: Global installation (recommended for regular use)

# macOS: use sudo if you get EACCES permission errors
sudo npm install -g qa360

# Or configure npm prefix (one-time setup)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g qa360

Option 2: Direct usage with npx (no installation needed)

# Run directly without installing
npx qa360@latest run test.yml
npx qa360@latest verify proof.json
npx qa360@latest doctor

Note: On first run, Playwright browsers will be automatically downloaded (~100MB). This happens only once.

Quick Start

1. Generate a test pack

# Option 1: Interactive mode (recommended for first-time users)
qa360 init

# Option 2: Use a template directly
qa360 init --template api-basic --yes

# Option 3: Copy an example
qa360 examples copy api-basic
qa360 examples list              # See all available examples

2. Run tests

qa360 run

3. Verify proof

qa360 verify .qa360/runs/

Usage

# Generate test pack (interactive)
qa360 init

# Generate with template
qa360 init --template api-basic
qa360 init --template fullstack
qa360 init --template security
qa360 init --template complete

# Examples commands
qa360 examples list              # List all examples
qa360 examples copy api-basic    # Copy example to qa360.yml
qa360 examples show fullstack    # Preview example content

# System health check
qa360 doctor

# Run test pack
qa360 run                    # Auto-detects qa360.yml
qa360 run custom-pack.yml    # Use specific file

# Verify proof bundle
qa360 verify .qa360/runs/
qa360 verify proof.json

# View run history
qa360 history list
qa360 history show <run-id>

# Export proof bundle
qa360 history export <run-id> --bundle proof-bundle.zip

# Clean up old runs (garbage collection)
qa360 history gc                    # Default: keep last 10 runs
qa360 history gc --keep-last 20     # Keep last 20 runs
qa360 history gc --dry-run          # Preview what would be deleted

# Pin/unpin runs (pinned runs are never deleted by gc)
qa360 history pin <run-id>
qa360 history unpin <run-id>

# With JSON output (CI-friendly)
qa360 doctor --json
qa360 verify proof.json --json
qa360 history list --json

Available Templates

| Template | Description | Gates | |----------|-------------|-------| | api-basic | Simple API smoke tests | api_smoke | | ui-basic | Basic UI/E2E tests | ui | | fullstack | API + UI + Performance | api_smoke, ui, perf | | security | Security testing suite | sast, dast, secrets, deps | | accessibility | Accessibility testing | ui, a11y | | complete | All quality gates | All (8 gates) |

Example Files

Pre-made examples are included in the package:

# List examples
ls examples/

# Copy an example
cp examples/api-basic.yml qa360.yml

# Run example directly
qa360 run examples/api-basic.yml

Commands

| Command | Description | |---------|-------------| | init | Generate test pack interactively | | examples | Manage example templates (list, copy, show) | | run | Execute test pack | | verify | Verify cryptographic proof bundles | | doctor | Check system health, auto-fix issues | | history | View run history and results | | report | Generate reports | | secrets | Manage encrypted secrets | | pack | Pack validation and linting |

History Commands

The history command provides comprehensive management of test run history stored in the Evidence Vault:

| Subcommand | Description | Example | |------------|-------------|---------| | list | List recent test runs | qa360 history list --limit 20 | | show <run-id> | Show detailed run information | qa360 history show abc123 | | diff <id1> <id2> | Compare two test runs | qa360 history diff abc123 def456 | | trend | Show trust score trends | qa360 history trend --window 30 | | export <run-id> | Export run as ZIP bundle | qa360 history export abc123 --bundle proof.zip | | gc | Garbage collect old runs | qa360 history gc --keep-last 10 | | pin <run-id> | Pin run (protect from gc) | qa360 history pin abc123 | | unpin <run-id> | Unpin run | qa360 history unpin abc123 |

Export Bundle Contents

When exporting a run with qa360 history export <run-id> --bundle proof.zip, the ZIP contains:

• proof.json - Cryptographically signed proof document
• report.pdf - Human-readable PDF report (if generated)
• run.json - Complete run details (gates, findings, artifacts)
• artifacts/ - All test artifacts (screenshots, logs, etc.)
• VERIFICATION.json - Verification instructions and metadata

Garbage Collection

The gc command removes old test runs and orphaned artifacts to free disk space:

# Preview what would be deleted (dry-run)
qa360 history gc --dry-run

# Keep last 20 runs, delete older ones
qa360 history gc --keep-last 20

# Default behavior (keeps last 10 unpinned runs)
qa360 history gc

Important: Pinned runs are NEVER deleted by garbage collection. Use qa360 history pin <run-id> to protect important runs.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Verification failed | | 2 | File not found | | 3 | Invalid schema | | 4 | Missing key | | 5 | Internal error |

Requirements

• Node.js >= 18.0.0
• npm or pnpm

Documentation

• Quick Start
• Full Documentation

License

MIT