Core Testing

/**
 * Runs accessibility tests against the provided HTML page and returns issue list
 * @param context - Optional context specification for limiting scope
 * @param options - Optional configuration for rules, reporter, and behavior
 * @param callback - Optional callback for non-Promise usage
 * @returns Promise resolving to test results, or void if callback provided
 */
function run(context?: ElementContext): Promise<AxeResults>;
function run(options: RunOptions): Promise<AxeResults>;
function run(context: ElementContext, options: RunOptions): Promise<AxeResults>;
function run(callback: RunCallback): void;
function run(context: ElementContext, callback: RunCallback): void;
function run(options: RunOptions, callback: RunCallback): void;
function run(context: ElementContext, options: RunOptions, callback: RunCallback): void;

// Run on entire page
axe.run().then(results => {
  console.log('Violations:', results.violations);
  console.log('Passes:', results.passes);
  console.log('Incomplete:', results.incomplete);
});

// Run on specific element
axe.run('#main-content').then(results => {
  console.log('Main content results:', results);
});

// Run with context object
axe.run({
  include: [['#main']],
  exclude: [['.advertisement']]
}).then(results => {
  console.log('Filtered results:', results);
});

// Run with options
axe.run({
  runOnly: {
    type: 'tag',
    values: ['wcag2a', 'wcag2aa']
  },
  reporter: 'v2'
}).then(results => {
  console.log('WCAG AA results:', results);
});

// Run with both context and options
axe.run('#form-section', {
  rules: {
    'color-contrast': { enabled: false }
  }
}).then(results => {
  console.log('Form results without color contrast:', results);
});

// Callback style
axe.run((error, results) => {
  if (error) {
    console.error('Test failed:', error);
  } else {
    console.log('Results:', results);
  }
});

/**
 * Run axe in the current window only
 * @param context - Context specification for limiting scope
 * @param options - Configuration options
 * @returns Promise resolving to partial result for use in finishRun
 */
function runPartial(context: ElementContext, options: RunOptions): Promise<PartialResult>;

// Run partial test in current frame
const partialResult = await axe.runPartial(document, {
  runOnly: { type: 'tag', values: ['wcag2a'] }
});
console.log('Partial result:', partialResult);

/**
 * Create a report from axe.runPartial results
 * @param partialResults - Array of results from axe.runPartial calls
 * @param options - Configuration options for final processing
 * @returns Promise resolving to complete axe results
 */
function finishRun(partialResults: PartialResults, options: RunOptions): Promise<AxeResults>;

// Collect results from multiple frames and finish
const results = [
  await axe.runPartial(document, options),
  await axe.runPartial(iframe1.contentDocument, options),
  await axe.runPartial(iframe2.contentDocument, options)
];

const finalResults = await axe.finishRun(results, options);
console.log('Complete cross-frame results:', finalResults);

interface AxeResults {
  toolOptions: RunOptions;
  passes: Result[];
  violations: Result[];
  incomplete: Result[];
  inapplicable: Result[];
  testEngine: TestEngine;
  testRunner: TestRunner;
  testEnvironment: TestEnvironment;
  url: string;
  timestamp: string;
}

interface Result {
  description: string;
  help: string;
  helpUrl: string;
  id: string;
  impact?: 'minor' | 'moderate' | 'serious' | 'critical' | null;
  tags: string[];
  nodes: NodeResult[];
}

interface NodeResult {
  html: string;
  impact?: 'minor' | 'moderate' | 'serious' | 'critical' | null;
  target: string[];
  xpath?: string[];
  ancestry?: string[];
  any: CheckResult[];
  all: CheckResult[];
  none: CheckResult[];
  failureSummary?: string;
  element?: HTMLElement;
}

interface CheckResult {
  id: string;
  impact: string;
  message: string;
  data: any;
  relatedNodes?: RelatedNode[];
}

interface RelatedNode {
  html: string;
  target: string[];
  xpath?: string[];
  ancestry?: string[];
  element?: HTMLElement;
}

interface PartialResult {
  frames: SerialDqElement[];
  results: PartialRuleResult[];
  environmentData?: EnvironmentData;
}

type PartialResults = Array<PartialResult | null>;

interface RunOptions {
  runOnly?: RunOnly | string[] | string;
  rules?: RuleObject;
  reporter?: 'v1' | 'v2' | 'raw' | 'rawEnv' | 'no-passes' | string;
  resultTypes?: ('inapplicable' | 'passes' | 'incomplete' | 'violations')[];
  selectors?: boolean;
  ancestry?: boolean;
  xpath?: boolean;
  absolutePaths?: boolean;
  iframes?: boolean;
  elementRef?: boolean;
  frameWaitTime?: number;
  preload?: boolean | PreloadOptions;
  performanceTimer?: boolean;
  pingWaitTime?: number;
}

interface RunOnly {
  type: 'rule' | 'rules' | 'tag' | 'tags';
  values: string[];
}

interface RuleObject {
  [ruleId: string]: {
    enabled: boolean;
  };
}

interface PreloadOptions {
  assets: string[];
  timeout?: number;
}

type ElementContext = string | Element | NodeList | Selector[] | ContextObject;

interface ContextObject {
  include?: ElementContext;
  exclude?: ElementContext;
}

type Selector = string | Element | LabelledShadowDomSelector | LabelledFramesSelector;

interface LabelledShadowDomSelector {
  fromShadowDom: string[];
}

interface LabelledFramesSelector {
  fromFrames: string[][];
}

type RunCallback = (error: Error | null, results: AxeResults) => void;

interface TestEngine {
  name: string;
  version: string;
}

interface TestRunner {
  name: string;
}

interface TestEnvironment {
  userAgent: string;
  windowWidth: number;
  windowHeight: number;
  orientationAngle?: number;
  orientationType?: string;
}

interface EnvironmentData {
  testEngine: TestEngine;
  testRunner: TestRunner;
  testEnvironment: TestEnvironment;
  url: string;
  timestamp: string;
}