ODAVL Guardian — Silent Failure Detector

ODAVL Guardian detects silent user failures by interacting with websites as real users do and reporting interactions that produce no observable effect.

The Problem

Many websites appear to work correctly while users silently encounter broken interactions:

Buttons are clickable but do nothing

Navigation links loop or lead nowhere

Forms submit without feedback

UI toggles change state without changing content

These failures:

Do not appear in logs

Do not trigger errors

Are invisible to analytics

Cause users to leave without explanation

What ODAVL Guardian Does

ODAVL Guardian:

Opens the target URL in a real browser

Interacts with visible user-facing elements

Observes actual outcomes (navigation, DOM changes, feedback)

Confirms failures through retries and stability checks

Reports confirmed silent failures only

It focuses exclusively on what users can see and experience.

What It Does NOT Do

ODAVL Guardian does not:

Test authentication or authorization flows

Perform security or penetration testing

Analyze backend logic or source code

Measure performance or SEO

Act as a generic test framework

Its scope is intentionally narrow and user-focused.

Installation

Using npx (recommended)

npx @odavl/guardian silent --url https://example.com

Global installation

npm install -g @odavl/guardian
guardian silent --url https://example.com

Local installation

npm install @odavl/guardian
npx guardian silent --url https://example.com

Note: Guardian requires Playwright browsers. On first run, install them with:

npx playwright install --with-deps chromium

Usage

guardian silent --url <url>

Or using npx:

npx @odavl/guardian silent --url <url>

Guardian analyzes the target URL, tests interactive elements, and reports confirmed silent failures. The output summarizes failures by severity and provides evidence for each finding.

Output

Guardian produces:

A clear console summary with:

Total confirmed silent failures

Severity distribution (HIGH / MEDIUM / LOW)

Detailed entries for each failure, including:

Interaction type

Description

Severity

Evidence references

Severity levels indicate impact:

HIGH — critical, above-the-fold interactions

MEDIUM — visible but less critical elements

LOW — footer or secondary interactions

Evidence artifacts include:

Before/after screenshots for visual confirmation

A JSON report containing structured failure data, descriptions, severity, and scores

Exit Codes

• 0 - No silent failures found
• 1 - Silent failures detected
• 2 - Tool error (invalid URL, browser failure, etc.)

Using Guardian in CI

Guardian automatically detects CI environments and suppresses welcome messages. Use it in GitHub Actions:

name: Check Silent Failures

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18.x'
      
      - name: Install Guardian
        run: npm install -g @odavl/guardian
      
      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium
      
      - name: Run Guardian
        env:
          CI: true
        run: guardian silent --url https://your-site.com

The workflow will:

• ✅ Pass (exit 0) if no silent failures are found
• ❌ Fail (exit 1) if silent failures are detected
• ❌ Fail (exit 2) if Guardian encounters an error

See .github/workflows/guardian-silent-example.yml for a complete example.

Installation

Using npx (recommended)

npx @odavl/guardian silent --url https://example.com

Global installation

npm install -g @odavl/guardian
guardian silent --url https://example.com

Local installation

npm install @odavl/guardian
npx guardian silent --url https://example.com

Note: Guardian requires Playwright browsers. On first run, install them with:

npx playwright install --with-deps chromium

Versioning

ODAVL Guardian follows Semantic Versioning.

Breaking Changes

Breaking changes are indicated by a major version bump (e.g., 1.0.0 → 2.0.0). Breaking changes may include:

• Changes to exit code behavior
• Changes to JSON report structure
• Removal of CLI flags or commands
• Changes to config file format
• Changes to minimum Node.js version requirements

Non-breaking changes (minor/patch versions) include:

• New optional features
• New CLI flags (backward compatible)
• Bug fixes
• Performance improvements

See CHANGELOG.md for detailed version history.

Philosophy

ODAVL Guardian tests reality as users experience it. It simulates real interactions and observes genuine responses, focusing on observable effects rather than implementation details. This approach surfaces failures that users encounter but automated tests often miss.