# qa360 **QA360 Proof CLI** - Quality as Cryptographic Proof [![Version](https://img.shields.io/npm/v/qa360.svg)](https://www.npmjs.com/package/qa360) [![License](https://img.shields.io/npm/l/qa360.svg)](https://github.com/xyqotech/qa360/blob/main/LICENSE) [![Tests](https://img.shields.io/badge/tests-282%20passing-success)](https://github.com/xyqotech/qa360) [![Coverage](https://img.shields.io/badge/coverage-55%25-brightgreen)](https://github.com/xyqotech/qa360) > **Official package** published by [xyqotech](https://github.com/xyqotech) with npm provenance signatures ## Installation ### Option 1: Global installation (recommended for regular use) ```bash # 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) ```bash # 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 ```bash # 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 ```bash qa360 run ``` ### 3. Verify proof ```bash qa360 verify .qa360/runs/ ``` ## Usage ```bash # 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 # Export proof bundle qa360 history export --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 qa360 history unpin # 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: ```bash # 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 ` | Show detailed run information | `qa360 history show abc123` | | `diff ` | Compare two test runs | `qa360 history diff abc123 def456` | | `trend` | Show trust score trends | `qa360 history trend --window 30` | | `export ` | Export run as ZIP bundle | `qa360 history export abc123 --bundle proof.zip` | | `gc` | Garbage collect old runs | `qa360 history gc --keep-last 10` | | `pin ` | Pin run (protect from gc) | `qa360 history pin abc123` | | `unpin ` | Unpin run | `qa360 history unpin abc123` | #### Export Bundle Contents When exporting a run with `qa360 history export --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: ```bash # 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 ` 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](https://github.com/xyqotech/qa360/blob/main/docs/quickstart-5min.md) - [Full Documentation](https://github.com/xyqotech/qa360/blob/main/docs/README.md) ## License MIT