A CLI tool for detecting layout issues on websites by analyzing the DOM using Playwright.

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

📖 Table of Contents

• ✨ Why Visual DOM Auditor?
• 🔥 Features
• ⚡ Installation
• 🎯 Quick Examples
• 🛠️ Command Reference
• 🧪 Detectors
• 🕷️ Site Crawling
• 📊 Output Formats
• 🔄 CI/CD Integration
• 🎨 Advanced Usage
• 🤝 Contributing
• 📜 License

✨ 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

1. 🚀 Starts from your URL
2. 🔍 Discovers internal links
3. 🧹 Filters external/asset links
4. ⚡ Analyzes pages concurrently
5. 📊 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

📜 License

MIT © Alex Berriman