@diyor28/qa-core 0.1.0

package/src/report/builder.ts

@@ -0,0 +1,94 @@
+import type { QaReport, QaFinding, QaArtifact } from '../types.js';
+
+export interface BuildReportOptions {
+  findings: QaFinding[];
+  artifacts: QaArtifact[];
+  metadata: {
+    scenarioName: string;
+    baseUrl: string;
+    viewport: { width: number; height: number };
+    timestamp: string;
+  };
+  duration: number;
+  summary: string;
+}
+
+export class ReportBuilder {
+  static buildReport(options: BuildReportOptions): QaReport {
+    const { findings, artifacts, metadata, duration, summary } = options;
+
+    // Determine overall status
+    let status: 'passed' | 'failed' | 'issues_found' = 'passed';
+
+    if (findings.some((f) => f.severity === 'critical' || f.severity === 'high')) {
+      status = 'failed';
+    } else if (findings.length > 0) {
+      status = 'issues_found';
+    }
+
+    // Generate summary if not provided
+    let finalSummary = summary;
+    if (!finalSummary) {
+      finalSummary = this.generateSummary(findings, status);
+    }
+
+    return {
+      summary: finalSummary,
+      status,
+      duration,
+      findings,
+      artifacts,
+      metadata,
+    };
+  }
+
+  private static generateSummary(findings: QaFinding[], status: string): string {
+    if (status === 'passed') {
+      return 'Test completed successfully with no issues found.';
+    }
+
+    const critical = findings.filter((f) => f.severity === 'critical').length;
+    const high = findings.filter((f) => f.severity === 'high').length;
+    const medium = findings.filter((f) => f.severity === 'medium').length;
+    const low = findings.filter((f) => f.severity === 'low').length;
+
+    const parts: string[] = [`Test completed with ${findings.length} issue(s) found:`];
+
+    if (critical > 0) parts.push(`${critical} critical`);
+    if (high > 0) parts.push(`${high} high`);
+    if (medium > 0) parts.push(`${medium} medium`);
+    if (low > 0) parts.push(`${low} low`);
+
+    return parts.join(', ') + '.';
+  }
+
+  static aggregateFindingsByCategory(findings: QaFinding[]): Record<string, QaFinding[]> {
+    const byCategory: Record<string, QaFinding[]> = {
+      functional: [],
+      ux: [],
+      ui: [],
+      accessibility: [],
+    };
+
+    for (const finding of findings) {
+      byCategory[finding.category].push(finding);
+    }
+
+    return byCategory;
+  }
+
+  static aggregateFindingsBySeverity(findings: QaFinding[]): Record<string, QaFinding[]> {
+    const bySeverity: Record<string, QaFinding[]> = {
+      critical: [],
+      high: [],
+      medium: [],
+      low: [],
+    };
+
+    for (const finding of findings) {
+      bySeverity[finding.severity].push(finding);
+    }
+
+    return bySeverity;
+  }
+}

package/src/runner.ts

@@ -0,0 +1,166 @@
+import { BrowserController } from './browser/controller.js';
+import { VisionAnalyzer } from './vision/analyzer.js';
+import { AgentLoop } from './agent/loop.js';
+import { ReportBuilder } from './report/builder.js';
+import type { QaReport, QaRunnerConfig, QaProgressEvent, QaArtifact } from './types.js';
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+export class QaRunner {
+  private config: QaRunnerConfig;
+  private browserController: BrowserController | null = null;
+  private visionAnalyzer: VisionAnalyzer | null = null;
+
+  constructor(config: QaRunnerConfig) {
+    this.config = config;
+  }
+
+  async run(): Promise<QaReport> {
+    const startTime = Date.now();
+
+    try {
+      // Initialize components
+      this.emitProgress('step_started', { step: 'initialization', message: 'Initializing QA runner' });
+
+      this.browserController = new BrowserController({
+        headless: this.config.browser.headless,
+        viewport: this.config.browser.viewport,
+        enableTrace: this.config.browser.enableTrace,
+        traceDir: this.config.browser.traceDir,
+      });
+
+      this.visionAnalyzer = new VisionAnalyzer(this.config.models.geminiApiKey);
+
+      await this.browserController.launch();
+
+      this.emitProgress('step_completed', { step: 'initialization', message: 'Browser launched successfully' });
+
+      // Run agent loop
+      this.emitProgress('step_started', { step: 'execution', message: 'Starting test execution' });
+
+      const agentLoop = new AgentLoop({
+        cerebrasApiKey: this.config.models.cerebrasApiKey,
+        browserController: this.browserController,
+        visionAnalyzer: this.visionAnalyzer,
+        scenarioName: this.config.scenario.name,
+        scenarioContent: this.config.scenario.content,
+        baseUrl: this.config.baseUrl,
+        defectsToCheck: this.config.defectsToCheck || ['Visual overflow', 'Bad UX', 'Poor contrast'],
+        maxIterations: this.config.maxIterations,
+        onProgress: this.config.onProgress,
+      });
+
+      const agentResult = await agentLoop.run();
+
+      this.emitProgress('step_completed', {
+        step: 'execution',
+        message: 'Test execution completed',
+        findings: agentResult.findings.length,
+      });
+
+      // Collect artifacts
+      this.emitProgress('step_started', { step: 'artifacts', message: 'Collecting artifacts' });
+
+      const artifacts: QaArtifact[] = [];
+
+      // Add all screenshots from browser controller
+      const screenshots = this.browserController.getAllScreenshots();
+      for (const screenshot of screenshots) {
+        artifacts.push({
+          type: 'screenshot',
+          name: screenshot.name,
+          data: screenshot.buffer,
+          contentType: 'image/png',
+        });
+      }
+
+      // Add trace file if enabled
+      if (this.config.browser.enableTrace && this.config.browser.traceDir) {
+        try {
+          const traceFiles = readdirSync(this.config.browser.traceDir).filter((f) => f.startsWith('trace-'));
+
+          if (traceFiles.length > 0) {
+            // Get the most recent trace file
+            const latestTrace = traceFiles.sort().pop()!;
+            const tracePath = join(this.config.browser.traceDir, latestTrace);
+            const traceBuffer = readFileSync(tracePath);
+
+            artifacts.push({
+              type: 'trace',
+              name: latestTrace,
+              data: traceBuffer,
+              contentType: 'application/zip',
+            });
+          }
+        } catch (error) {
+          console.warn('[QaRunner] Failed to collect trace file:', error);
+        }
+      }
+
+      this.emitProgress('step_completed', {
+        step: 'artifacts',
+        message: 'Artifacts collected',
+        count: artifacts.length,
+      });
+
+      // Build report
+      const duration = Date.now() - startTime;
+
+      const report = ReportBuilder.buildReport({
+        findings: agentResult.findings,
+        artifacts,
+        metadata: {
+          scenarioName: this.config.scenario.name,
+          baseUrl: this.config.baseUrl,
+          viewport: this.config.browser.viewport,
+          timestamp: new Date().toISOString(),
+        },
+        duration,
+        summary: agentResult.summary,
+      });
+
+      return report;
+    } catch (error) {
+      console.error('[QaRunner] Error during test execution:', error);
+
+      // Build error report
+      const duration = Date.now() - startTime;
+
+      return ReportBuilder.buildReport({
+        findings: [
+          {
+            severity: 'critical',
+            title: 'Test execution failed',
+            description: `Error during test execution: ${error instanceof Error ? error.message : String(error)}`,
+            reproSteps: ['Test runner encountered an error'],
+            category: 'functional',
+          },
+        ],
+        artifacts: [],
+        metadata: {
+          scenarioName: this.config.scenario.name,
+          baseUrl: this.config.baseUrl,
+          viewport: this.config.browser.viewport,
+          timestamp: new Date().toISOString(),
+        },
+        duration,
+        summary: `Test execution failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    } finally {
+      // Always close browser
+      if (this.browserController) {
+        await this.browserController.close();
+      }
+    }
+  }
+
+  private emitProgress(type: QaProgressEvent['type'], data: Record<string, unknown>) {
+    if (this.config.onProgress) {
+      this.config.onProgress({
+        type,
+        data,
+        timestamp: Date.now(),
+      });
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+export interface QaScenario {
+  name: string;
+  content: string; // Markdown instructions
+}
+
+export interface QaFinding {
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  title: string;
+  description: string;
+  reproSteps: string[];
+  expected?: string;
+  actual?: string;
+  screenshotName?: string;
+  category: 'functional' | 'ux' | 'ui' | 'accessibility';
+}
+
+export interface QaArtifact {
+  type: 'screenshot' | 'trace';
+  name: string;
+  data: Buffer;
+  contentType: string;
+}
+
+export interface QaReport {
+  summary: string;
+  status: 'passed' | 'failed' | 'issues_found';
+  duration: number;
+  findings: QaFinding[];
+  artifacts: QaArtifact[];
+  metadata: {
+    scenarioName: string;
+    baseUrl: string;
+    viewport: { width: number; height: number };
+    timestamp: string;
+  };
+}
+
+export interface QaProgressEvent {
+  type: 'step_started' | 'step_completed' | 'screenshot_captured' | 'finding_discovered' | 'context_usage';
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface ScreenshotEntry {
+  timestamp: number;
+  name: string;
+  buffer: Buffer;
+  context: string;
+  url: string;
+}
+
+export interface QaRunnerConfig {
+  browser: {
+    headless?: boolean;
+    viewport: { width: number; height: number };
+    enableTrace?: boolean;
+    traceDir?: string;
+  };
+  models: {
+    cerebrasApiKey: string;
+    geminiApiKey: string;
+  };
+  baseUrl: string;
+  scenario: QaScenario;
+  defectsToCheck?: string[];
+  maxIterations?: number;
+  onProgress?: (event: QaProgressEvent) => void;
+}

package/src/vision/analyzer.ts

@@ -0,0 +1,61 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import type { QaFinding } from '../types.js';
+import { buildVisionPrompt } from './prompts.js';
+
+export class VisionAnalyzer {
+  private genAI: GoogleGenerativeAI;
+  private model: any;
+
+  constructor(apiKey: string) {
+    this.genAI = new GoogleGenerativeAI(apiKey);
+    this.model = this.genAI.getGenerativeModel({
+      model: 'gemini-3-flash-preview',
+    });
+  }
+
+  async analyzeScreenshot(
+    screenshot: Buffer,
+    context: string,
+    url: string
+  ): Promise<QaFinding[]> {
+    try {
+      const base64Image = screenshot.toString('base64');
+      const prompt = buildVisionPrompt(context, url);
+
+      const result = await this.model.generateContent([
+        {
+          inlineData: {
+            mimeType: 'image/png',
+            data: base64Image,
+          },
+        },
+        { text: prompt },
+      ]);
+
+      const response = await result.response;
+      const text = response.text();
+
+      // Parse JSON response
+      const jsonMatch = text.match(/\{[\s\S]*\}/);
+      if (!jsonMatch) {
+        console.warn('[VisionAnalyzer] No JSON found in response:', text);
+        return [];
+      }
+
+      const parsed = JSON.parse(jsonMatch[0]);
+      const findings = parsed.findings || [];
+
+      // Convert vision findings to QaFinding format
+      return findings.map((finding: any) => ({
+        severity: finding.severity || 'medium',
+        title: finding.title,
+        description: `${finding.description}\n\nSuggestion: ${finding.suggestion || 'N/A'}`,
+        reproSteps: [`Screenshot captured at: ${url}`, `Context: ${context}`],
+        category: finding.category,
+      }));
+    } catch (error) {
+      console.error('[VisionAnalyzer] Error analyzing screenshot:', error);
+      return [];
+    }
+  }
+}

package/src/vision/prompts.ts

@@ -0,0 +1,28 @@
+export function buildVisionPrompt(context: string, url: string): string {
+  return `You are a ruthless UX/UI critic analyzing a screenshot of a web application.
+
+Context: ${context}
+URL: ${url}
+
+Analyze this screenshot for:
+- Visual overflow (content cut off, horizontal scroll)
+- Poor color contrast (WCAG AA violations)
+- Bad UX (confusing navigation, hidden CTAs, poor hierarchy)
+- Accessibility issues (missing labels, poor focus indicators)
+
+Return findings as JSON array with structure:
+{
+  "findings": [
+    {
+      "category": "ux" | "ui" | "accessibility",
+      "severity": "low" | "medium" | "high",
+      "title": "Short title",
+      "description": "Detailed description",
+      "suggestion": "How to fix"
+    }
+  ]
+}
+
+Be concise and specific. Only report actual issues you can clearly see in the screenshot.
+If everything looks good, return an empty findings array.`;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}