@alexberriman/visual-dom-auditor NPM

📖 Table of Contents

✨ Why Visual DOM Auditor?

Your CSS looks perfect. Your code validates. But your site still breaks visually. Visual DOM Auditor catches what other tools miss — the real layout issues that frustrate users.

🔥 Features

⚡ Installation

# Use directly (recommended)
npx @alexberriman/visual-dom-auditor --url https://example.com

# Or install globally
npm install -g @alexberriman/visual-dom-auditor

🎯 Quick Examples

Basic Usage

# Analyze a single page
npx @alexberriman/visual-dom-auditor --url https://example.com

# Test mobile layout
npx @alexberriman/visual-dom-auditor --url https://example.com --viewport mobile

# Save results
npx @alexberriman/visual-dom-auditor --url https://example.com --save report.json

Advanced Usage

# Test multiple pages with custom viewport
npx @alexberriman/visual-dom-auditor \
  --urls https://example.com https://example.com/about \
  --viewport 1366x768 \
  --save results.json

# Crawl entire site
npx @alexberriman/visual-dom-auditor \
  --url https://example.com \
  --crawl \
  --max-pages 50 \
  --max-threads 5

# Run specific detectors only
npx @alexberriman/visual-dom-auditor \
  --url https://example.com \
  --detectors "overlap,console-error"

🛠️ Command Reference

Core Options

Option	Description	Default
`--url`	Single URL to analyze	-
`--urls`	Multiple URLs to analyze	-
`--viewport`	`desktop`, `tablet`, `mobile`, or `WIDTHxHEIGHT`	`desktop`
`--save`	Save results to file	-
`--format`	Output format	`json`
`--verbose`	Show detailed logs	`false`
`--exit-early`	Stop on first critical error	`false`

Detector Options

Option	Description	Default
`--detectors`	Comma-separated list of detectors	All enabled

Crawling Options

Option	Description	Default
`--crawl`	Enable site crawling	`false`
`--max-depth`	Maximum crawl depth (1-10)	`3`
`--max-pages`	Maximum pages to crawl (1-1000)	`50`
`--max-threads`	Concurrent threads (1-10)	`3`

🧪 Detectors

🎯 Enabled by Default

{
  "type": "overlap",
  "severity": "critical",
  "elements": [
    {"selector": ".header-logo", "description": "Header logo"},
    {"selector": ".nav-menu", "description": "Navigation menu"}
  ],
  "overlapPercentage": 65
}

{
  "type": "padding",
  "severity": "major",
  "element": {"selector": ".submit-btn", "description": "Submit button"},
  "insufficientSides": ["top", "bottom"]
}

{
  "type": "spacing",
  "severity": "minor",
  "spacing": 2,
  "recommendedSpacing": 8
}

{
  "type": "container-overflow",
  "severity": "major",
  "overflowDirection": "right",
  "overflowAmount": 15
}

{
  "type": "scrollbar",
  "severity": "critical",
  "overflowAmount": 320
}

{
  "type": "flex-grid",
  "severity": "major",
  "issue": "overflow"
}

{
  "type": "console-error",
  "severity": "critical",
  "level": "error",
  "message": "TypeError: Cannot read property 'foo' of undefined"
}

🔵 Disabled by Default

Centering Detector — Enable with --detectors centering

🕷️ Site Crawling

Automatically discover and analyze your entire website.

# Basic crawl
npx @alexberriman/visual-dom-auditor --url https://example.com --crawl

# Advanced crawl with limits
npx @alexberriman/visual-dom-auditor \
  --url https://example.com \
  --crawl \
  --max-depth 5 \
  --max-pages 100 \
  --max-threads 5 \
  --save crawl-report.json

How It Works

🚀 Starts from your URL
🔍 Discovers internal links
🧹 Filters external/asset links
⚡ Analyzes pages concurrently
📊 Reports aggregated results

📊 Output Formats

Single URL

{
  "url": "https://example.com",
  "timestamp": "2023-05-20T10:15:30Z",
  "issues": [...],
  "metadata": {
    "totalIssuesFound": 3,
    "criticalIssues": 1,
    "issuesByType": {...}
  }
}

Multiple URLs / Crawl

{
  "timestamp": "2023-05-20T10:15:30Z",
  "results": [...],
  "summary": {
    "totalUrls": 15,
    "urlsWithIssues": 8,
    "totalIssuesFound": 23
  },
  "crawlMetadata": {
    "startUrl": "https://example.com",
    "pagesSkipped": 32,
    "crawlDuration": 45000
  }
}

🔄 CI/CD Integration

GitHub Actions

name: Visual Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Playwright
        run: npx playwright install chromium
      - name: Run Visual Audit
        run: |
          npx @alexberriman/visual-dom-auditor \
            --url https://staging.example.com \
            --crawl \
            --exit-early \
            --save report.json
      - uses: actions/upload-artifact@v3
        with:
          name: audit-report
          path: report.json

Quick CI Commands

# Fail fast on critical issues
npx @alexberriman/visual-dom-auditor --url $STAGING_URL --exit-early

# Full site audit
npx @alexberriman/visual-dom-auditor --url $STAGING_URL --crawl --max-pages 25

🎨 Advanced Usage

Pipe to Other Tools

# Pretty print with jq
npx @alexberriman/visual-dom-auditor --url https://example.com | jq '.'

# Extract critical issues
npx @alexberriman/visual-dom-auditor --url https://example.com | \
  jq '.issues[] | select(.severity == "critical")'

# Count issues by type
npx @alexberriman/visual-dom-auditor --url https://example.com | \
  jq '.metadata.issuesByType'

Programmatic Usage

import { analyzePage } from "@alexberriman/visual-dom-auditor/core/analyzer";
import { allDetectors } from "@alexberriman/visual-dom-auditor/core/detectors";

// Custom analysis
const result = await analyzePage(page, config, allDetectors);

🤝 Contributing

We love contributions! Check out our contributing guide to get started.

# Fork and clone
git clone https://github.com/YOUR_USERNAME/visual-dom-auditor
cd visual-dom-auditor

# Install dependencies
npm install

# Make your changes
# ...

# Test
npm test

# Submit PR