oculusqasum: A JavaScript repository from scottvr

/ˈɑːkjʊləs ˌkjuː.eɪˈsuːm/ "ä′k-yo͞o-ləs kyo͞o-ā′-so͞om" (AHK-yoo-luhs cue-AY-soom)

Oculus Quod Assumit.
The eye that takes what it takes.

motto “Nihil assume. Omnia observa. Quidvis resolve.” Assume nothing. Observe everything. Resolve anything.

Vision

OculusQAsum is a powerful visual QA system that bridges the gap between design and development, ensuring pixel-perfect implementation of web interfaces. It automatically detects visual inconsistencies, generates tickets, fixes bugs, and monitors for regressions - all with a blend of technical precision and intelligent automation.

What sets it apart from tools that inspired it (Percy, Chromatic, etc) is that OculusQAsum goes further, opening and resolving issues using your ticket tracker and submitting PRs with tested fixes for the issues it detects.

Features

Visual Inconsistency Detection: Pixel-perfect comparison between design mockups and developed UI
Auto-Generated GitHub Issues: Creates detailed tickets with visual evidence and priority labels
LLM-Powered Bug Fixing: Uses AI to analyze discrepancies and generate code fixes
Automated Pull Requests: Creates PRs with suggested fixes for quick resolution
Continuous Monitoring: Prevents visual regressions through scheduled checks
Multi-Viewport Testing: Verifies consistency across desktop, tablet, and mobile views
Real-time Alerts: Integrates with Slack, Teams, and email for instant notifications

Quick Start

# Install globally
npm install -g oculus-qasum

# Initialize in your project
npx oculus-qasum init

# Compare design with implementation
npx oculus-qasum compare --design path/to/design.png --implementation https://yourapp.com

# Start monitoring to prevent regressions
npx oculus-qasum monitor --create-baselines

How It Works

OculusQAsum works through four main components:

Comparison Engine: Captures and compares screenshots with advanced image analysis
Issue Tracker: Manages the entire bug lifecycle from detection to resolution
Fix Generator: Uses AI to understand visual discrepancies and generate code fixes
Live Monitor: Continuously watches for regressions in your production environment

graph TD
    A[Design System] --> C[1\. Comparison Engine]
    B[Implementation] --> C
    C --> D[Discrepancy Analysis]
    D --> E[2\. Issue Tracker]
    D --> F[3\. Fix Generator]
    G[Production UI] --> H[4\. Live Monitor]
    H --> D
    
    E --> I[GitHub Issues]
    F --> J[Automated PRs]
    H --> K[Regression Alerts]

Installation

See our detailed Installation Guide for complete setup instructions.

Quick Install

# Clone the repository
git clone https://github.com/scottvr/oculus-qasum.git
cd oculus-qasum

# Install dependencies
npm install

# Setup configuration
cp .env.example .env
# Edit .env with your API keys

# Run the CLI
./cli.js init

Configuration

OculusQAsum is highly configurable through a YAML configuration file:

comparison:
  thresholds:
    pixelDifference: 0.05
  browser:
    headless: true
  llm:
    enabled: true
    model: "gpt-4-vision-preview"

github:
  owner: "your-username"
  repo: "your-repo"
  issueLabels: ["visual-regression", "automated"]

# Additional configuration options...

See Configuration Reference for all available options.

🖥️ CLI Commands

OculusQAsum provides an intuitive command-line interface:

Commands:
  init                       Initialize OculusQAsum in the current directory
  compare [options]          Compare design mockup with implementation
  monitor [options]          Start continuous monitoring for visual regressions

Options:
  -v, --version              Display version information
  -h, --help                 Display help information

See CLI Reference for detailed command documentation.

API Usage

OculusQAsum can be used programmatically in your Node.js applications:

const { OculusQAsum } = require('oculus-qasum');

// Initialize with configuration
const oqa = new OculusQAsum({
  comparison: {
    thresholds: { pixelDifference: 0.05 }
  }
});

// Run automated visual QA workflow
async function runVisualQA() {
  const results = await oqa.runWorkflow(
    'https://figma.com/file/abc123',
    'https://myapp.com/component',
    '.hero-section',
    sourceCode,
    { componentName: 'Hero Section' }
  );
  
  console.log(results);
}

See API Reference for complete documentation.

Integrations

OculusQAsum integrates with popular design, development, and communication tools:

Design Tools: Figma, Sketch, Adobe XD
Issue Trackers: GitHub, Jira, Linear
Version Control: GitHub, GitLab
Communication: Slack, Microsoft Teams, Email
CI/CD: GitHub Actions, CircleCI, Jenkins

Example Results


Visual Difference Detection	Auto-Generated GitHub Issue

Contributing

PRs and Issues are welcome.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

Built with Playwright
Visual comparison powered by pixelmatch and ResembleJS
LLM capabilities by OpenAI and Anthropic
Inspired by tools like Percy, Chromatic, and BackstopJS

sacred incantation

Observatio
Cognitio
Universalis
Logica
Ultima
Systema

Questionis
Assumptionisque

Summa

scottvr/oculusqasum