qa360 2.1.7 → 2.2.1

package/core/src/vault/schema.sql

@@ -0,0 +1,168 @@
+-- QA360 Evidence Vault Schema
+-- SQLite WAL mode for concurrent access and performance
+
+-- Enable WAL mode and performance optimizations
+PRAGMA journal_mode = WAL;
+PRAGMA journal_size_limit = 67108864; -- 64MB
+PRAGMA synchronous = NORMAL;
+PRAGMA cache_size = 10000;
+PRAGMA foreign_keys = ON;
+PRAGMA temp_store = MEMORY;
+
+-- Runs table: core execution records
+CREATE TABLE IF NOT EXISTS runs (
+    id TEXT PRIMARY KEY,                    -- UUID v4
+    run_key TEXT UNIQUE,                   -- Idempotence key (nullable, unique when not null)
+    started_at INTEGER NOT NULL,          -- Epoch milliseconds
+    ended_at INTEGER,                      -- Epoch milliseconds (nullable until finished)
+    pack_hash TEXT NOT NULL,               -- SHA256 of normalized pack.yml
+    pack_path TEXT NOT NULL,               -- Original pack file path
+    status TEXT NOT NULL DEFAULT 'running', -- running|passed|failed|cancelled|error
+    trust_score INTEGER,                   -- 0-100 (nullable until calculated)
+    weights_json TEXT,                     -- JSON weights configuration
+    sign_alg TEXT DEFAULT 'ed25519',       -- Signature algorithm
+    signature_hex TEXT,                    -- Signature of proof.json (nullable until signed)
+    proof_pdf_path TEXT,                   -- CAS path to proof PDF
+    pinned INTEGER DEFAULT 0,              -- 0|1 for GC protection
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Indexes for runs
+CREATE INDEX IF NOT EXISTS idx_runs_started_at ON runs(started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_runs_run_key ON runs(run_key) WHERE run_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);
+CREATE INDEX IF NOT EXISTS idx_runs_pack_hash ON runs(pack_hash);
+CREATE INDEX IF NOT EXISTS idx_runs_pinned ON runs(pinned) WHERE pinned = 1;
+
+-- Gates table: individual test gate results
+CREATE TABLE IF NOT EXISTS gates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,                    -- api_smoke|ui|perf|sast|dast|a11y|deps|secrets
+    status TEXT NOT NULL,                  -- passed|failed|skipped|warn
+    duration_ms INTEGER,                   -- Execution duration
+    metrics_json TEXT,                     -- JSON metrics (p95, a11y score, etc.)
+    budgets_json TEXT,                     -- JSON budget definitions
+    started_at INTEGER,                    -- Gate start time
+    ended_at INTEGER,                      -- Gate end time
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Indexes for gates
+CREATE INDEX IF NOT EXISTS idx_gates_run_id ON gates(run_id);
+CREATE INDEX IF NOT EXISTS idx_gates_run_name ON gates(run_id, name);
+CREATE INDEX IF NOT EXISTS idx_gates_status ON gates(status);
+CREATE INDEX IF NOT EXISTS idx_gates_name ON gates(name);
+
+-- Findings table: security and quality findings
+CREATE TABLE IF NOT EXISTS findings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    gate TEXT NOT NULL,                    -- Gate that produced this finding
+    severity TEXT NOT NULL,                -- info|low|medium|high|critical
+    rule TEXT NOT NULL,                    -- Rule identifier (semgrep:xxx, zap:yyy, etc.)
+    location TEXT,                         -- File path, URL, or CSS selector
+    message TEXT,                          -- Redacted finding message
+    raw_output TEXT,                       -- Original tool output (redacted)
+    fingerprint TEXT,                      -- Unique fingerprint for deduplication
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Indexes for findings
+CREATE INDEX IF NOT EXISTS idx_findings_run_id ON findings(run_id);
+CREATE INDEX IF NOT EXISTS idx_findings_run_gate ON findings(run_id, gate);
+CREATE INDEX IF NOT EXISTS idx_findings_severity ON findings(severity);
+CREATE INDEX IF NOT EXISTS idx_findings_rule ON findings(rule);
+CREATE INDEX IF NOT EXISTS idx_findings_fingerprint ON findings(fingerprint);
+
+-- Artifacts table: Content-Addressable Storage metadata
+CREATE TABLE IF NOT EXISTS artifacts (
+    sha256 TEXT PRIMARY KEY,               -- Content hash
+    mime_type TEXT NOT NULL,               -- MIME type
+    size_bytes INTEGER NOT NULL,           -- File size in bytes
+    cas_path TEXT NOT NULL,                -- CAS storage path
+    original_name TEXT,                    -- Original filename (if applicable)
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    last_accessed INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Indexes for artifacts
+CREATE INDEX IF NOT EXISTS idx_artifacts_mime_type ON artifacts(mime_type);
+CREATE INDEX IF NOT EXISTS idx_artifacts_size ON artifacts(size_bytes);
+CREATE INDEX IF NOT EXISTS idx_artifacts_created_at ON artifacts(created_at);
+CREATE INDEX IF NOT EXISTS idx_artifacts_last_accessed ON artifacts(last_accessed);
+
+-- Run artifacts table: N-N relationship between runs and artifacts
+CREATE TABLE IF NOT EXISTS run_artifacts (
+    run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    sha256 TEXT NOT NULL REFERENCES artifacts(sha256) ON DELETE CASCADE,
+    label TEXT NOT NULL,                   -- proof_pdf, ui_screenshot_login, zap_report, etc.
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+    PRIMARY KEY (run_id, sha256, label)
+);
+
+-- Indexes for run_artifacts
+CREATE INDEX IF NOT EXISTS idx_run_artifacts_run_id ON run_artifacts(run_id);
+CREATE INDEX IF NOT EXISTS idx_run_artifacts_sha256 ON run_artifacts(sha256);
+CREATE INDEX IF NOT EXISTS idx_run_artifacts_label ON run_artifacts(label);
+
+-- Vault metadata table: schema version and configuration
+CREATE TABLE IF NOT EXISTS vault_metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Insert initial metadata
+INSERT OR IGNORE INTO vault_metadata (key, value) VALUES 
+    ('schema_version', '1.0.0'),
+    ('created_at', strftime('%s', 'now') * 1000),
+    ('vault_format', 'qa360-evidence-vault-v1');
+
+-- Triggers for updated_at timestamps
+CREATE TRIGGER IF NOT EXISTS trigger_runs_updated_at 
+    AFTER UPDATE ON runs
+    BEGIN
+        UPDATE runs SET updated_at = strftime('%s', 'now') * 1000 WHERE id = NEW.id;
+    END;
+
+CREATE TRIGGER IF NOT EXISTS trigger_artifacts_last_accessed
+    AFTER UPDATE ON artifacts
+    BEGIN
+        UPDATE artifacts SET last_accessed = strftime('%s', 'now') * 1000 WHERE sha256 = NEW.sha256;
+    END;
+
+-- Views for common queries
+CREATE VIEW IF NOT EXISTS v_recent_runs AS
+SELECT 
+    r.id,
+    r.run_key,
+    r.started_at,
+    r.ended_at,
+    r.status,
+    r.trust_score,
+    r.pack_path,
+    COUNT(g.id) as gate_count,
+    COUNT(CASE WHEN g.status = 'passed' THEN 1 END) as gates_passed,
+    COUNT(CASE WHEN g.status = 'failed' THEN 1 END) as gates_failed,
+    COUNT(f.id) as finding_count,
+    COUNT(CASE WHEN f.severity IN ('high', 'critical') THEN 1 END) as critical_findings
+FROM runs r
+LEFT JOIN gates g ON r.id = g.run_id
+LEFT JOIN findings f ON r.id = f.run_id
+GROUP BY r.id
+ORDER BY r.started_at DESC;
+
+CREATE VIEW IF NOT EXISTS v_gate_trends AS
+SELECT 
+    g.name,
+    g.status,
+    r.started_at,
+    r.trust_score,
+    g.duration_ms,
+    g.metrics_json
+FROM gates g
+JOIN runs r ON g.run_id = r.id
+WHERE r.status IN ('passed', 'failed')
+ORDER BY r.started_at DESC;

package/core/src/visual/README.md

@@ -0,0 +1,185 @@
+# QA360 Visual Regression Module
+
+Visual comparison testing for UI changes using screenshot comparison with configurable thresholds.
+
+## Features
+
+- **Screenshot Comparison**: Pixel-by-pixel diffing
+- **Baseline Management**: Create, update, and compare against baselines
+- **Configurable Thresholds**: Control sensitivity of differences
+- **Diff Generation**: Visual diff images showing changes
+- **Anti-aliasing Handling**: Option to ignore anti-aliasing differences
+- **CAS Integration**: Store screenshots in content-addressable storage
+
+## Usage
+
+```typescript
+import { VisualRegressionTester, createVisualRegressionTester } from 'qa360-core';
+
+// Create tester
+const tester = new VisualRegressionTester({
+  baselineDir: '.qa360/visual/baselines',  // Baseline images
+  actualDir: '.qa360/visual/actual',       // Current screenshots
+  diffDir: '.qa360/visual/diffs',          // Diff images
+  maxDiffThreshold: 0.01,                  // Max pixel diff (0-1)
+  maxDifferentPixels: 0.001,               // Max diff ratio (0-1)
+  ignoreAntiAliasing: true,                // Ignore AA differences
+  diffColor: { r: 255, g: 0, b: 0 },       // Diff highlight color (red)
+});
+
+// Take screenshot and compare
+const screenshot = await page.screenshot({ type: 'png' });
+const viewportSize = page.viewportSize();
+
+const result = await tester.compare('homepage', screenshot, viewportSize.width, viewportSize.height);
+
+console.log(`Status: ${result.status}`);  // 'pass', 'fail', or 'updated'
+console.log(`Diff pixels: ${result.diffPixels}`);
+console.log(`Diff percentage: ${result.diffPercentage}%`);
+
+if (result.status === 'fail') {
+  console.log(`Diff image: ${result.diffImagePath}`);
+}
+```
+
+## Configuration Options
+
+```typescript
+interface VisualRegressionConfig {
+  baselineDir?: string;        // Baseline images directory
+  actualDir?: string;          // Current screenshots directory
+  diffDir?: string;            // Diff images directory
+  maxDiffThreshold?: number;   // Max allowed pixel difference (0-1)
+  maxDifferentPixels?: number; // Max allowed different pixels ratio (0-1)
+  updateBaselines?: boolean;   // Update baselines on failure
+  ignoreAntiAliasing?: boolean;// Ignore anti-aliasing differences
+  diffColor?: {                // Highlight color for diffs
+    r: number;  // Red (0-255)
+    g: number;  // Green (0-255)
+    b: number;  // Blue (0-255)
+  };
+}
+
+interface VisualRegressionResult {
+  name: string;                // Test name
+  status: 'pass' | 'fail' | 'updated';
+  diffPixels: number;          // Number of different pixels
+  diffPercentage: number;      // Percentage of different pixels
+  diffImagePath?: string;      // Path to diff image
+  baselinePath: string;        // Path to baseline
+  actualPath: string;          // Path to actual screenshot
+  error?: string;              // Error message
+}
+```
+
+## Workflow
+
+### Initial Run (Create Baselines)
+
+```typescript
+const tester = new VisualRegressionTester({
+  updateBaselines: true,  // Create baselines on first run
+});
+
+const result = await tester.compare('homepage', screenshot, width, height);
+// Status: 'updated' - baseline created
+```
+
+### Regression Testing
+
+```typescript
+const tester = new VisualRegressionTester({
+  updateBaselines: false,  // Don't update, fail on differences
+});
+
+const result = await tester.compare('homepage', screenshot, width, height);
+// Status: 'pass' if no significant differences
+// Status: 'fail' if differences detected
+```
+
+### Update Baselines
+
+```typescript
+const tester = new VisualRegressionTester({
+  updateBaselines: true,  // Update when intentional changes occur
+});
+
+const result = await tester.compare('homepage', screenshot, width, height);
+// Status: 'updated' - baseline replaced with new screenshot
+```
+
+## Convenience Function
+
+```typescript
+import { runVisualRegressionTests } from 'qa360-core';
+
+const tests = [
+  {
+    name: 'homepage',
+    screenshot: pageScreenshot1,
+    width: 1280,
+    height: 720,
+  },
+  {
+    name: 'checkout',
+    screenshot: pageScreenshot2,
+    width: 1280,
+    height: 720,
+  },
+];
+
+const { results, summary } = await runVisualRegressionTests(tests, {
+  updateBaselines: false,
+  maxDiffThreshold: 0.01,
+});
+
+console.log(`Total: ${summary.total}`);
+console.log(`Passed: ${summary.passed}`);
+console.log(`Failed: ${summary.failed}`);
+console.log(`Updated: ${summary.updated}`);
+```
+
+## Threshold Guidelines
+
+| Threshold | Use Case |
+|-----------|----------|
+| `maxDiffThreshold: 0.01` | Strict comparison (1% pixel diff) |
+| `maxDiffThreshold: 0.05` | Allow minor rendering variations |
+| `maxDiffThreshold: 0.1` | Allow significant variations |
+| `maxDifferentPixels: 0.001` | Very strict (0.1% of pixels) |
+| `maxDifferentPixels: 0.01` | Moderate (1% of pixels) |
+| `maxDifferentPixels: 0.05` | Lenient (5% of pixels) |
+
+## Best Practices
+
+1. **Consistent Viewports**: Always use the same viewport size
+2. **Wait for Stability**: Wait for animations/images to load
+3. **Dynamic Content**: Mask or hide dynamic content (dates, counters)
+4. **Anti-aliasing**: Enable `ignoreAntiAliasing` for cross-browser tests
+5. **CI Integration**: Run in CI with strict thresholds, update manually
+
+## Integration with Playwright
+
+```typescript
+import { VisualRegressionTester } from 'qa360-core';
+
+const tester = new VisualRegressionTester();
+
+// Full-page screenshot
+const screenshot = await page.screenshot({
+  type: 'png',
+  fullPage: true,
+});
+
+const result = await tester.compare(
+  'page-name',
+  screenshot,
+  screenshot.width,
+  screenshot.length / screenshot.height * screenshot.width  // Approx height
+);
+
+if (!result.passed) {
+  console.log(`Visual regression detected!`);
+  console.log(`View diff: ${result.diffImagePath}`);
+}
+```

package/core/src/visual/index.ts

@@ -0,0 +1,14 @@
+/**
+ * QA360 Visual Regression Module
+ *
+ * Visual comparison testing for UI changes
+ */
+
+export {
+  VisualRegressionTester,
+  createVisualRegressionTester,
+  runVisualRegressionTests,
+  type VisualRegressionConfig,
+  type VisualRegressionResult,
+  type ScreenshotData,
+} from './visual-regression.js';