@a11y-oracle/keyboard-engine

CDP-based keyboard dispatch engine for accessibility testing. Sends native hardware-level keystrokes via Input.dispatchKeyEvent and reads focused element information via Runtime.evaluate.

This is a low-level building block used internally by @a11y-oracle/core-engine. Most users should use the Playwright or Cypress plugin instead.

Installation

npm install @a11y-oracle/keyboard-engine

Usage

import { KeyboardEngine } from '@a11y-oracle/keyboard-engine';

const keyboard = new KeyboardEngine(cdpSession);

// Press a key
await keyboard.press('Tab');

// Press with modifiers
await keyboard.press('Tab', { shift: true });   // Shift+Tab (backward)
await keyboard.press('a', { ctrl: true });       // Ctrl+A (select all)

// Get info about the currently focused element
const el = await keyboard.getFocusedElement();
if (el) {
  console.log(el.tag);      // "BUTTON"
  console.log(el.id);       // "submit-btn"
  console.log(el.role);     // "button"
  console.log(el.tabIndex); // 0
  console.log(el.rect);     // { x: 100, y: 200, width: 120, height: 40 }
}

API Reference

KeyboardEngine

constructor(cdp: CDPSessionLike)

Create a new keyboard engine.

• cdp — Any object with a send(method, params?) method compatible with CDP.

press(key: string, modifiers?: ModifierKeys): Promise<void>

Dispatch a native key press via CDP Input.dispatchKeyEvent. Sends a keyDown event followed by a keyUp event, matching the behavior of a physical key press.

• key — Key name from KEY_DEFINITIONS (see table below).
• modifiers — Optional modifier keys to hold during the press.

Modifier keys map to the CDP bitmask: Alt = 1, Ctrl = 2, Meta = 4, Shift = 8.

Throws if the key name is not in KEY_DEFINITIONS.

getFocusedElement(): Promise<FocusedElementInfo | null>

Get information about the currently focused DOM element via Runtime.evaluate.

Returns null if no interactive element has focus (e.g., document.body or document.documentElement is focused).

Supported Keys

Types

KeyDefinition

CDP keyboard event parameters for a single key:

interface KeyDefinition {
  key: string;     // CDP key property (e.g. "Tab")
  code: string;    // CDP code property (e.g. "Tab")
  keyCode: number; // Windows virtual key code (e.g. 9)
}

ModifierKeys

Modifier keys for key press combinations:

interface ModifierKeys {
  shift?: boolean;
  ctrl?: boolean;
  alt?: boolean;
  meta?: boolean;
}

FocusedElementInfo

Information about the currently focused DOM element:

interface FocusedElementInfo {
  tag: string;        // "BUTTON"
  id: string;         // "submit-btn"
  className: string;  // "btn primary"
  textContent: string; // "Submit"
  role: string;       // "button" (from role attribute)
  ariaLabel: string;  // "Submit form" (from aria-label)
  tabIndex: number;   // 0
  rect: { x: number; y: number; width: number; height: number };
}

Exports

export { KeyboardEngine } from '@a11y-oracle/keyboard-engine';
export { KEY_DEFINITIONS } from '@a11y-oracle/keyboard-engine';
export type {
  KeyDefinition,
  ModifierKeys,
  FocusedElementInfo,
} from '@a11y-oracle/keyboard-engine';

How It Works

The engine uses two CDP domains:

1. Input.dispatchKeyEvent — Sends real hardware-level keystroke events (keyDown + keyUp) directly to the browser. This bypasses synthetic JavaScript event dispatch (element.dispatchEvent()), so the browser handles focus management natively — just as if a user physically pressed the key.

2. Runtime.evaluate — Executes a JavaScript expression in the page context to read document.activeElement properties (tag, id, class, role, aria-label, tabIndex, bounding rect).