drishti-qa

v1.0.5

Published

2 months ago

Drishti (दृष्टि) — The All-Seeing Eye. 43-category automated website tester. One command replaces 10+ QA tools. Zero config. Zero test code.

Drishti (दृष्टि) — See Everything. Miss Nothing.

One command. 43 test categories. Zero manual testing.

Drishti is a comprehensive automated website testing framework that replaces your entire QA stack — accessibility, performance, security, visual, SEO, cross-browser, and 37 more categories — with a single command. No test code to write. No configuration required.

Replace 10+ separate testing tools (Lighthouse, axe, Percy, OWASP ZAP, BrowserStack, etc.) with one.

Why Drishti?

| Problem | Drishti's Solution | |---------|-------------------| | Manual QA is slow, expensive, and misses edge cases | 43 automated test categories with zero human intervention | | Need 10+ tools for full coverage (a11y, perf, security, visual...) | One tool covers everything | | Writing E2E tests takes weeks | Zero test code required — point at a project and run | | QA expertise spread across multiple people | One report covers accessibility, performance, security, SEO, and more | | Different tools = different reports = no single view | One unified HTML/JSON/PDF report with all findings |

What Makes Drishti Different

| Tool | Categories | Config Required | Test Code | Price | |------|-----------|----------------|-----------|-------| | Drishti | 43 | None | None | Free | | Lighthouse | 5 | None | None | Free | | axe/Deque | 1 (a11y) | Moderate | None | $4K-40K/yr | | Percy | 1 (visual) | Heavy | Required | $399-899/mo | | Cypress | Custom | Heavy | Required | $75-300/mo | | OWASP ZAP | 1 (security) | Heavy | None | Free (complex) | | BrowserStack | 1 (cross-browser) | Moderate | Required | $29-199/mo |

Quick Start

Prerequisites

| Requirement | Why | |------------|-----| | Node.js v18+ | Runtime environment | | ~500 MB disk | Playwright browser binaries (Chromium, Firefox, WebKit) |

Installation

# Clone the repository
git clone https://github.com/your-org/drishti.git
cd drishti

# Install dependencies
npm install

# Install browser engines
npx playwright install chromium firefox webkit

Run Your First Test

# Test a local project (starts dev server automatically)
node test.js /path/to/your-project

# Test a live URL directly
node test.js --url https://your-site.com

That's it. No configuration. No test files. Open the generated HTML report and review all 43 categories.

Usage

Dual-Mode Execution

Drishti supports two modes of operation:

Project Folder Mode

node test.js <project-folder> [options]

Points to a local project directory. Drishti starts the dev server automatically, runs all 43 test categories, and generates a report. This mode provides deeper analysis because it has access to your source code — API route discovery, SSR validation, dev-mode warning detection, and framework-specific insights.

URL Mode

node test.js --url <url> [options]

Tests any live URL directly — production sites, staging environments, even competitor websites. No server setup needed. Runs the same 43 test categories against the live page.

CLI Options

| Flag | Description | |------|-------------| | --url <url> | Test a live URL directly (skips dev server startup) | | --phase <name> | Run a single phase only (e.g., --phase accessibility) | | --skip-api | Skip tests requiring external API endpoints | | --fast | Quick scan — runs only the top 10 most critical phases | | --json | Output JSON to stdout for CI/CD pipeline integration | | --verbose | Show detailed console output during testing | | --help | Show help with all available phases |

Examples

# Full 43-category test on a local project
node test.js /Users/Projects/my-website

# Test a production URL
node test.js --url https://example.com

# Run only accessibility tests
node test.js /Users/Projects/my-website --phase accessibility

# Test staging URL, skip API tests
node test.js --url https://staging.example.com --skip-api

# Verbose output for debugging
node test.js /Users/Projects/my-website --verbose

# Single phase on a live URL
node test.js --url https://example.com --phase performance

Fast Mode Phases

When using --fast, Drishti runs these 10 critical phases:

Homepage Load
Visual Audit
Accessibility
Responsive
Navigation
Forms
Performance
SEO
Security
Content Quality

Quality Score

Every scan produces a score from 0-100 using weighted deductions:

| Severity | First N issues | Cost per issue | After N issues | Cost per issue | |----------|---------------|----------------|----------------|----------------| | Critical | First 5 | 3 points each | 6-15 | 2 points each | | Warning | First 10 | 1 point each | 11+ | 0.5 points each | | Info | First 20 | 0.25 points each | 21+ | Free |

| Score | Rating | |-------|--------| | 80-100 | Good | | 50-79 | Needs Work | | 0-49 | Poor |

43 Test Categories

Foundational Tests (1-14)

| # | Phase | What It Tests | |---|-------|---------------| | 1 | Homepage Load | HTTP status, blank screen, title, hydration errors, load time, redirect chains, meta refresh traps, mixed content (HTTP on HTTPS), HSTS header, preload/prefetch validation | | 2 | Visual Audit | Overlapping elements, broken images, text overflow, invisible text, z-index issues, font FOIT/FOUT detection, above-the-fold CTA visibility, Windows High Contrast mode | | 3 | Accessibility | WCAG 2.1 AA: alt text, contrast, labels, headings, ARIA, touch targets, skip navigation link, ARIA live regions, link text quality ("click here" detection), :focus-visible CSS | | 4 | Responsive | 7 device viewports + orientation, overflow, text sizing, touch targets | | 5 | Interactions | Button/link clicks with error capture, double-click debounce testing, right-click context menu detection | | 6 | Forms | Valid/invalid data, XSS injection, Unicode, CSRF token presence, autocomplete attributes, fieldset/legend grouping for radio/checkbox | | 7 | Navigation | Internal/external/anchor links, 404 detection, back/forward, redirect chain length analysis, breadcrumb navigation detection | | 8 | Keyboard | Tab order, focus rings, Enter/Space/ESC, keyboard traps, reverse tab (Shift+Tab), keyboard shortcut conflict detection | | 9 | Modals & Overlays | Open/close, backdrop click, ESC, focus trap, scroll lock, focus restoration on close, aria-labelledby validation, nested modal stacking | | 10 | Animations | Framer Motion, scroll-triggered, hover effects, prefers-reduced-motion, FPS measurement | | 11 | Scroll | Full page scroll, sticky elements, horizontal overflow | | 12 | Drag & Drop | Draggable element detection, constraint testing, gesture simulation | | 13 | Canvas/WebGL | Render verification, WASD/arrow key input, click coordinates, FPS monitoring | | 14 | Media | Video controls, download buttons, aspect ratio validation |

Performance & Quality Tests (15-26)

| # | Phase | What It Tests | |---|-------|---------------| | 15 | Performance | LCP, CLS, TTFB, INP (Interaction to Next Paint), FPS, memory, DOM size, long tasks, unused JS detection (Coverage API), resource timing (slow resources > 3s), third-party script impact | | 16 | SEO | Title, meta, OG, Twitter cards, canonical, headings, favicon, robots.txt, JSON-LD structured data validation, hreflang tags, meta robots noindex detection, OG image dimensions | | 17 | Security | API key exposure, XSS, localStorage secrets, inline handlers, CSP header validation, SRI for CDN scripts, X-Frame-Options/clickjacking, mixed content, CORS misconfiguration, sensitive data in URLs | | 18 | Cross-Browser | Chromium + Firefox + WebKit rendering comparison and error detection | | 19 | Error Handling | Blocked CSS, slow 3G, 404 page, accumulated errors, offline mode handling, error recovery UI (retry/back/home buttons) | | 20 | Edge Cases | Rapid clicks, 10K input, special chars, resize, copy-paste behavior, background tab simulation, zero-width character handling | | 21 | User Flows | Scroll journey, button exploration, mobile flow, search functionality testing, notification/toast detection | | 22 | Content Quality | Placeholder text, React warnings, hydration, debug logs, spell check on headings (50 common typos), outdated year detection, all-caps heading warning | | 23 | Zoom & Scaling | 125%, 150%, 200% zoom + text scaling | | 24 | Color Vision | Protanopia, deuteranopia, tritanopia, achromatopsia + dark mode + high contrast | | 25 | Print | Print stylesheet, blank print check, fixed elements, page break validation, print URL display | | 26 | State Persistence | localStorage/sessionStorage audit, refresh, clear storage, IndexedDB detection, session cookie expiry analysis |

Advanced Tests (27-43)

| # | Phase | What It Tests | |---|-------|---------------| | 27 | API Testing | Route discovery, empty body, malformed JSON, wrong methods, rate limit headers, API response time | | 28 | SSR & Hydration | Raw HTML inspection, meta tags in SSR, hydration mismatch detection | | 29 | PWA & Manifest | manifest.json, icons, theme-color, favicon, display mode validation, start URL validation | | 30 | Social Preview | OG image validation, title/description length, Twitter card type validation, OG locale tags | | 31 | Memory Leaks | Heap growth, DOM node growth, GC verification, event listener count, timer leak detection | | 32 | Deep API Testing | Payload testing, schema validation, SQL injection, XSS reflection, rate limiting | | 33 | Auth Flows | Login validation, protected routes, token exposure, cookie flags, session timeout detection, password visibility toggle | | 34 | Visual Regression | Baseline screenshots, diff tracking, section comparison, dynamic content masking | | 35 | Load Testing | Concurrent requests (5/10/20), degradation analysis, stress test, gradual ramp-up (1→2→4→8) | | 36 | Deep SSR | SSR vs client comparison, streaming detection, hydration timing | | 37 | i18n | Unicode (9 charsets), RTL layout, text expansion, locale number format detection, language switcher detection | | 38 | File Operations | File inputs, download links, drag-drop zones, clipboard testing | | 39 | Caching | Cache-Control headers, service worker, cache hit rate, stale content, ETag/Last-Modified (conditional requests), cache-busting hash detection | | 40 | E2E Workflows | Scroll + expand, form + submit, keyboard journey, browser back button form state, deep link restoration | | 41 | Cookies & Privacy | Cookie security audit, third-party cookies, tracking scripts, GDPR indicators, cookie consent enforcement verification, Do Not Track support | | 42 | Lighthouse Audit | FCP, TTI, render-blocking, DOM depth, image optimization, a11y/SEO scoring, INP proxy measurement, unused CSS detection (Coverage API), critical request chain analysis | | 43 | Error Monitoring | Error categorization, failed requests, recurring patterns, unhandled rejections, error frequency by phase, rejection reason categorization |

Output & Reports

After every test run, Drishti generates a timestamped report directory:

reports/<project>/<timestamp>/
├── report.html        # Interactive dashboard with filters and visual breakdown
├── report.json        # Machine-readable structured data (for CI/CD integration)
├── report.pdf         # Printable summary for stakeholders
└── screenshots/       # Organized by phase
    ├── homepage/
    ├── responsive/
    ├── interactions/
    ├── color-vision/
    ├── cross-browser/
    └── ...            # One folder per phase

HTML Report Features

Summary dashboard with critical/warning/info issue counts
Phase-by-phase status (pass/warn/fail) with duration
Filterable issue list by severity and category
Inline screenshots for visual verification
Console log and network request analysis
Actionable fix suggestions with WCAG references

JSON Report Structure

{
  "project": "my-website",
  "timestamp": "2026-03-31T10:00:00Z",
  "duration": "4m 32s",
  "summary": {
    "critical": 3,
    "warning": 12,
    "info": 28,
    "phasesPassed": 38,
    "phasesFailed": 5,
    "screenshots": 147
  },
  "phases": {
    "accessibility": {
      "status": "fail",
      "duration": 8200,
      "issues": [...]
    }
  }
}

Configuration

Default Configuration

Drishti works out of the box with sensible defaults. All configuration lives in src/config.js:

| Setting | Default | Description | |---------|---------|-------------| | Viewports | 7 devices | iPhone SE, iPhone 14 Pro, Galaxy S21, iPad Mini, iPad Pro, Desktop (1440px), Ultrawide (2560px) | | Server Timeout | 90s | Max wait for dev server to start | | Page Load Timeout | 30s | Max wait for page load | | Phase Timeout | 5 min | Max time per test phase | | Max Buttons | 30 | Buttons to click per page | | Max Links | 20 | Links to test per page | | Max Inputs | 10 | Form inputs to fill per page | | LCP Threshold | 2.5s | Largest Contentful Paint target | | CLS Threshold | 0.1 | Cumulative Layout Shift target | | TTFB Threshold | 800ms | Time to First Byte target |

Custom Configuration

Create a drishti.config.js in your project root to override defaults:

export default {
  viewports: {
    'Mobile': { width: 375, height: 812 },
    'Desktop': { width: 1920, height: 1080 },
  },
  thresholds: {
    lcp: 3000,       // ms
    cls: 0.15,
    ttfb: 1000,      // ms
  },
  limits: {
    maxButtons: 50,
    maxLinks: 30,
  },
  skipPhases: ['drag-drop', 'canvas-webgl'],  // Skip phases not relevant to your project
  apiPaths: ['/api/users', '/api/auth'],       // Custom API routes to test
};

CI/CD Integration

GitHub Actions

Drishti includes a ready-to-use GitHub Actions workflow:

# .github/workflows/qa-test.yml
name: Drishti QA
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  qa:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install Drishti
        run: npm ci && npx playwright install chromium --with-deps

      - name: Run QA Tests
        run: node test.js /path/to/project

      - name: Upload Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: drishti-report
          path: reports/
          retention-days: 30

Exit Codes

| Code | Meaning | |------|---------| | 0 | All phases passed (no critical issues) | | 1 | One or more critical issues found |

Use exit codes to gate deployments — block merges when Drishti finds critical issues.

Architecture

drishti/
├── test.js                    # CLI entry point (dual-mode: project folder + URL)
├── generate-pdf.js            # Standalone PDF re-generator from existing report.json
├── package.json               # Dependencies (Playwright, Chalk, PDFKit, tree-kill)
├── src/
│   ├── config.js              # Central configuration (viewports, timeouts, thresholds)
│   ├── config-loader.js       # Loads user's drishti.config.js and merges with defaults
│   ├── runner.js              # Main orchestrator — runs all 43 phases sequentially
│   ├── server.js              # Dev server lifecycle (auto-detects framework)
│   ├── phases/                # 43 test phase modules
│   │   ├── 01-homepage.js
│   │   ├── 02-visual-audit.js
│   │   ├── 03-accessibility.js
│   │   ├── ...
│   │   └── 43-error-monitoring.js
│   ├── utils/                 # Shared utilities
│   │   ├── console-monitor.js # Captures console errors, warnings, page crashes
│   │   ├── network-monitor.js # Tracks requests, responses, timing, sizes
│   │   ├── screenshots.js     # Screenshot capture and organization
│   │   ├── element-map.js     # DOM element discovery and interaction mapping
│   │   ├── dom-helpers.js     # DOM analysis utilities
│   │   ├── color-utils.js     # Color contrast calculation (WCAG formula)
│   │   ├── severity.js        # Issue categorization and deduplication
│   │   ├── reporter.js        # HTML/JSON report generation
│   │   ├── pdf-report.js      # PDF report generation
│   │   ├── wait.js            # Wait conditions and timeouts
│   │   └── port.js            # Available port detection
│   └── fixtures/
│       └── test-data.js       # Test data (emails, passwords, injection strings, Unicode)
├── reports/                   # Generated test reports (timestamped)
├── web/                       # Next.js web frontend (SaaS dashboard)
│   ├── app/                   # Pages and API routes
│   ├── components/            # UI components
│   └── lib/                   # Scan store, utilities
└── .github/workflows/
    └── qa-test.yml            # CI/CD pipeline

How It Works

Input (project folder or URL)
  │
  ├── Project Mode: Start dev server → detect port → wait for ready
  └── URL Mode: Use provided URL directly
  │
  ▼
Launch Browser (Playwright: Chromium headless)
  │
  ├── Attach ConsoleMonitor (capture errors, warnings, logs)
  ├── Attach NetworkMonitor (track requests, responses, timing)
  └── Attach ScreenshotManager (organize captures by phase)
  │
  ▼
Execute 43 Phases Sequentially
  │
  Each phase:
  ├── Navigate/interact with the page
  ├── Capture issues (severity: critical/warning/info)
  ├── Take screenshots as evidence
  └── Respect timeout limits (5 min max per phase)
  │
  ▼
Aggregate Results
  │
  ├── Generate report.html (interactive dashboard)
  ├── Generate report.json (structured data)
  ├── Generate report.pdf (printable summary)
  └── Save screenshots by phase
  │
  ▼
Exit (code 0 = pass, code 1 = critical issues found)

Security Testing Details

Drishti scans for exposed secrets from 10+ providers:

| Provider | Pattern Detected | |----------|-----------------| | OpenAI | sk- prefixed keys | | Stripe | pk_live_, sk_live_, pk_test_, sk_test_ | | AWS | AKIA followed by 16 alphanumeric characters | | GitHub | ghp_ prefixed tokens | | Google | AIza prefixed API keys | | Slack | xox prefixed tokens | | SendGrid | SG. prefixed keys | | Generic | secret_, key-, token_ patterns |

Additionally tests for:

Content Security Policy (CSP) — missing or overly permissive (unsafe-inline, unsafe-eval)
Subresource Integrity (SRI) — external scripts/stylesheets missing integrity attribute
Clickjacking protection — missing X-Frame-Options or CSP frame-ancestors
Mixed content — HTTPS pages loading HTTP resources
CORS misconfiguration — overly permissive Access-Control-Allow-Origin: *
HSTS header — missing Strict-Transport-Security
CSRF tokens — forms missing anti-forgery tokens
Sensitive data in URLs — tokens, passwords, API keys in query parameters
XSS injection vulnerabilities (reflected and stored)
SQL injection patterns in login forms
javascript: protocol in href attributes
Missing rel="noopener" on external links
Inline event handlers (onclick, onerror)
Sensitive data in localStorage/sessionStorage
Cookie security flags (Secure, HttpOnly, SameSite)
Third-party tracking script inventory

Accessibility Testing Details

Drishti performs WCAG 2.1 AA compliance checks:

| Check | WCAG Criterion | What It Validates | |-------|---------------|-------------------| | Alt text | 1.1.1 | Every <img> has meaningful alt text | | Color contrast | 1.4.3 | Text meets 4.5:1 (normal) / 3:1 (large) ratio | | Form labels | 1.3.1 | Every input has an associated label | | Heading hierarchy | 1.3.1 | No skipped heading levels (h1 → h3) | | Touch targets | 2.5.5 | Minimum 44x44px touch targets on mobile | | Focus visible | 2.4.7 | Keyboard focus rings are visible | | ARIA attributes | 4.1.2 | Valid ARIA roles and properties | | Language | 3.1.1 | lang attribute on <html> | | Link purpose | 2.4.4 | Links have descriptive text (not "click here") | | Skip navigation | 2.4.1 | Skip-to-main-content link for keyboard users | | ARIA live regions | 4.1.3 | Dynamic errors announced via role="alert" or aria-live | | Focus-visible | 2.4.7 | :focus-visible CSS prevents mouse-click focus rings | | Modal labeling | 4.1.2 | Dialogs have aria-labelledby or aria-label |

Color vision simulation tests across 4 types of color blindness plus dark mode and high contrast.

Performance Metrics

| Metric | Good | Needs Work | Poor | |--------|------|-----------|------| | LCP (Largest Contentful Paint) | < 2.5s | 2.5-4.0s | > 4.0s | | CLS (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 | | TTFB (Time to First Byte) | < 800ms | 800-1800ms | > 1800ms | | INP (Interaction to Next Paint) | < 200ms | 200-500ms | > 500ms | | FPS (Frames Per Second) | > 50 | 30-50 | < 30 | | DOM Nodes | < 1,500 | 1,500-3,000 | > 3,000 | | Memory | < 50 MB | 50-100 MB | > 100 MB |

Tested Viewports

| Device | Width | Height | Type | |--------|-------|--------|------| | iPhone SE | 375px | 667px | Mobile | | iPhone 14 Pro | 393px | 852px | Mobile | | Galaxy S21 | 360px | 800px | Mobile | | iPad Mini | 768px | 1024px | Tablet | | iPad Pro | 1024px | 1366px | Tablet | | Desktop | 1440px | 900px | Desktop | | Ultrawide | 2560px | 1080px | Desktop |

Tech Stack

| Component | Technology | Purpose | |-----------|-----------|---------| | Runtime | Node.js 18+ | JavaScript execution | | Browser Automation | Playwright 1.50 | Multi-browser testing (Chromium, Firefox, WebKit) | | Terminal UI | Chalk 5.3 | Colored console output | | PDF Generation | PDFKit 0.18 | PDF report creation | | Process Management | tree-kill 1.2 | Graceful dev server cleanup |

Total codebase: ~12,700 lines across 43 phase modules, 12 utility modules, and core orchestration. ~540 individual test checks.

Zero external SaaS dependencies — Drishti runs entirely on your machine. No data leaves your environment.

Troubleshooting

Common Issues

| Issue | Solution | |-------|---------| | Playwright browsers not found | Run npx playwright install chromium firefox webkit | | Dev server timeout | Increase TIMEOUTS.serverReady in src/config.js (default: 90s) | | Port already in use | Drishti auto-detects available ports. Kill stale processes if needed | | Phase timeout (5 min) | Complex phases may need longer. Adjust TIMEOUTS.phaseMax in config | | Cross-browser phase fails | Ensure all 3 browser engines are installed via Playwright | | Permission denied on screenshots | Ensure reports/ directory is writable |

Debug Mode

# Run with verbose output to see detailed logs
node test.js /path/to/project --verbose

Contributing

Contributions are welcome! Drishti is organized for easy extension:

Add a new test phase: Create a file in src/phases/ following the existing pattern (export a run() function)
Add test data: Extend src/fixtures/test-data.js with new injection strings or input patterns
Improve detection: Enhance utilities in src/utils/ for better element discovery or issue categorization

# Development workflow
git clone https://github.com/your-org/drishti.git
cd drishti
npm install
npx playwright install chromium firefox webkit

# Run against a test project
node test.js /path/to/test-project --verbose

License

MIT