ConsoleSentinel

API Reference

Use ConsoleSentinel programmatically in Node.js scripts, test suites, and custom tooling.

Installation

npm install consolesentinel

Quick Example

import { ConsoleSentinel } from 'consolesentinel';

const sentinel = new ConsoleSentinel({
  url: 'https://example.com',
  maxPages: 25,
});

const report = await sentinel.scan();

console.log(`Grade: ${report.grade}`);     // "A"
console.log(`Score: ${report.score}`);      // 94
console.log(`Issues: ${report.findings.length}`);

ConsoleSentinel Class

Constructor

new ConsoleSentinel(options: ScanOptions): ConsoleSentinel

Accepts the same options as the config file. See Configuration for all fields.

Methods

scan(): Promise<ScanReport>

Run a full scan and return the report.

const report = await sentinel.scan();

scanPage(url: string): Promise<PageReport>

Scan a single page without crawling.

const page = await sentinel.scanPage('https://example.com/about');

compare(baseline: ScanReport, current: ScanReport): DeltaReport

Compare two reports and return the differences.

const delta = sentinel.compare(oldReport, newReport);
console.log(`New issues: ${delta.newFindings.length}`);
console.log(`Resolved: ${delta.resolvedFindings.length}`);

on(event: string, handler: Function): void

Listen to scan lifecycle events.

sentinel.on('page:start', ({ url }) => {
  console.log(`Scanning: ${url}`);
});

sentinel.on('page:complete', ({ url, findings }) => {
  console.log(`${url}: ${findings.length} findings`);
});

sentinel.on('scan:complete', (report) => {
  console.log(`Done! Grade: ${report.grade}`);
});

Types

ScanOptions

interface ScanOptions {
  url: string;
  maxPages?: number;
  maxDepth?: number;
  timeout?: number;
  viewport?: { width: number; height: number };
  userAgent?: string;
  headers?: Record<string, string>;
  auditors?: AuditorConfig;
  exclude?: string[];
  include?: string[];
  output?: OutputConfig;
  ci?: CIConfig;
  integrations?: IntegrationConfig;
}

ScanReport

interface ScanReport {
  version: string;
  url: string;
  timestamp: string;
  duration: number;
  grade: string;
  score: number;
  pages: PageReport[];
  findings: Finding[];
  summary: {
    totalPages: number;
    totalFindings: number;
    critical: number;
    high: number;
    medium: number;
    low: number;
    info: number;
  };
}

PageReport

interface PageReport {
  url: string;
  statusCode: number;
  loadTime: number;
  findings: Finding[];
  metrics: {
    lcp: number;
    cls: number;
    fid: number;
    ttfb: number;
  };
}

Finding

interface Finding {
  id: string;
  module: string;
  eventKind: string;
  severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
  title: string;
  description: string;
  url: string;
  selector?: string;
  evidence?: string;
  recommendation?: string;
}

DeltaReport

interface DeltaReport {
  baseline: { grade: string; score: number };
  current: { grade: string; score: number };
  scoreDelta: number;
  newFindings: Finding[];
  resolvedFindings: Finding[];
  unchangedFindings: Finding[];
}

Integration with Test Frameworks

Vitest / Jest

import { describe, it, expect } from 'vitest';
import { ConsoleSentinel } from 'consolesentinel';

describe('Production QA', () => {
  it('should score above 80', async () => {
    const sentinel = new ConsoleSentinel({
      url: process.env.DEPLOY_URL!,
      maxPages: 20,
    });
    const report = await sentinel.scan();
    expect(report.score).toBeGreaterThanOrEqual(80);
  });

  it('should have zero critical findings', async () => {
    const sentinel = new ConsoleSentinel({
      url: process.env.DEPLOY_URL!,
      maxPages: 20,
    });
    const report = await sentinel.scan();
    expect(report.summary.critical).toBe(0);
  });
});

Playwright

import { test, expect } from '@playwright/test';
import { ConsoleSentinel } from 'consolesentinel';

test('full site audit passes', async () => {
  const sentinel = new ConsoleSentinel({
    url: 'http://localhost:3000',
    maxPages: 50,
  });
  const report = await sentinel.scan();
  expect(report.grade).toMatch(/^[AB]/);
});

Error Handling

import { ConsoleSentinel, ScanError, TimeoutError } from 'consolesentinel';

try {
  const report = await sentinel.scan();
} catch (err) {
  if (err instanceof TimeoutError) {
    console.error('Scan timed out:', err.message);
  } else if (err instanceof ScanError) {
    console.error('Scan failed:', err.message);
  } else {
    throw err;
  }
}

Next Steps