Implementation:Getgauge Taiko USKeyboardLayout

Knowledge Sources	Getgauge_Taiko
Domains	Browser Automation, Input Simulation
Last Updated	2026-02-12 03:00 GMT

Overview

USKeyboardLayout is a comprehensive static mapping of US keyboard keys to Chrome DevTools Protocol (CDP) key definition objects, used by Taiko to simulate keyboard input during browser automation.

Description

The USKeyboardLayout module (located at lib/data/USKeyboardLayout.js) is a pure-data JavaScript file that exports a single flat object mapping approximately 450 key identifiers to their corresponding CDP KeyDefinition descriptors. Each key entry is an object that may contain the following properties: keyCode, shiftKeyCode, key, shiftKey, code, text, shiftText, and location.

This module was originally imported from the Puppeteer project (https://github.com/GoogleChrome/puppeteer) with minor modifications applied by the Taiko maintainers. It is licensed under Apache License 2.0 and carries the Thoughtworks copyright header. The file defines the KeyDefinition JSDoc typedef at the top for documentation purposes.

The mapping covers the full spectrum of a US QWERTY keyboard, including: digit keys (0-9 and their shifted symbols), alphabetic keys (a-z, A-Z), function keys (F1-F24), modifier keys (Shift, Control, Alt, Meta with left/right variants), navigation keys (Arrow keys, Home, End, PageUp, PageDown), numpad keys with their NumLock-toggled alternates, punctuation and symbol keys with shift variants, and special keys such as media controls (AudioVolumeMute, MediaPlayPause), system keys (Power, Eject, PrintScreen), and editing keys (Backspace, Delete, Insert). The location property distinguishes between left-side (1), right-side (2), and numpad (3) key positions, which is critical for correct CDP event dispatch.

Usage

This module is consumed whenever Taiko needs to translate a human-readable key name or character into the low-level parameters required by the CDP Input.dispatchKeyEvent method. Specifically, it is imported by two consumers:

• lib/handlers/inputHandler.js -- The core input handler that dispatches keyDown, keyUp, and char events to the browser via CDP. It uses the layout to resolve key names (e.g., "Enter", "ShiftLeft") into the correct keyCode, code, key, and text values.
• lib/actions/write.js -- The write action that types text character-by-character into focused elements. It looks up each character in this mapping to produce the correct sequence of key events.

The layout is used at runtime but is never modified; it serves as an immutable reference table.

Code Reference

Source Location

• Repository: Getgauge_Taiko
• File: lib/data/USKeyboardLayout.js
• Lines: 1-490

Signature

/**
 * @typedef {Object} KeyDefinition
 * @property {number=} keyCode
 * @property {number=} shiftKeyCode
 * @property {string=} key
 * @property {string=} shiftKey
 * @property {string=} code
 * @property {string=} text
 * @property {string=} shiftText
 * @property {number=} location
 */

/**
 * @type {Object<string, KeyDefinition>}
 */
module.exports = {
  // ~450 key entries ...
};

Import

const keyDefinitions = require("../data/USKeyboardLayout");

I/O Contract

Inputs

Name	Type	Required	Description
(none)	N/A	N/A	This is a static data module with no function parameters. Consumers access entries by key name lookup, e.g., keyDefinitions["Enter"] or keyDefinitions["a"].

Outputs

Name	Type	Description
module.exports	Object<string, KeyDefinition>	A flat object where each key is a string identifier (key name, character, or code name) and each value is a KeyDefinition object.

KeyDefinition properties:

Property	Type	Description
keyCode	number (optional)	The numeric key code sent in CDP key events (e.g., 13 for Enter, 65 for 'a').
shiftKeyCode	number (optional)	The key code to use when Shift is held (primarily for numpad keys).
key	string (optional)	The key value for the CDP event (e.g., "Enter", "a", "Shift").
shiftKey	string (optional)	The key value produced when Shift is held (e.g., "A" for KeyA, "!" for Digit1).
code	string (optional)	The physical key code identifier (e.g., "KeyA", "Enter", "ShiftLeft").
text	string (optional)	The text to insert for this key (e.g., "\r" for Enter).
shiftText	string (optional)	The text to insert when Shift is held.
location	number (optional)	Key location: 1 = left, 2 = right, 3 = numpad. Absent for standard keys.

Usage Examples

Looking Up a Named Key

const keyDefinitions = require("./lib/data/USKeyboardLayout");

// Resolve the Enter key
const enterDef = keyDefinitions["Enter"];
// => { keyCode: 13, code: "Enter", key: "Enter", text: "\r" }

// Resolve a lowercase letter
const aDef = keyDefinitions["a"];
// => { keyCode: 65, key: "a", code: "KeyA" }

Resolving Shift Variants

const keyDefinitions = require("./lib/data/USKeyboardLayout");

// The physical key "Digit1" knows its shift variant
const digit1 = keyDefinitions["Digit1"];
// => { keyCode: 49, code: "Digit1", shiftKey: "!", key: "1" }

// The character "!" maps directly as well
const exclamation = keyDefinitions["!"];
// => { keyCode: 49, key: "!", code: "Digit1" }

Distinguishing Left vs Right Modifier Keys

const keyDefinitions = require("./lib/data/USKeyboardLayout");

const shiftLeft = keyDefinitions["ShiftLeft"];
// => { keyCode: 16, code: "ShiftLeft", key: "Shift", location: 1 }

const shiftRight = keyDefinitions["ShiftRight"];
// => { keyCode: 16, code: "ShiftRight", key: "Shift", location: 2 }

Numpad Key with Location

const keyDefinitions = require("./lib/data/USKeyboardLayout");

const numpad5 = keyDefinitions["Numpad5"];
// => { keyCode: 12, shiftKeyCode: 101, key: "Clear", code: "Numpad5", shiftKey: "5", location: 3 }
// When NumLock is off: "Clear"; when on: "5"

Related Pages

• Principle:Getgauge_Taiko_Text_Input