Implementation:Getgauge Taiko Write
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Testing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Concrete tool for typing text into input elements character-by-character provided by the Taiko library.
Description
The write function simulates real user keyboard input by dispatching individual key events for each character in the provided text string. The public API is defined in lib/taiko.js (lines 1092-1098), which validates the browser state, delegates to the internal write implementation in lib/actions/write.js (lines 38-81), and emits a success description event upon completion.
The internal implementation first normalizes the text input: null or undefined values are converted to an empty string with a console warning, and non-string values are coerced via toString(). The into parameter is then resolved: if it is a string, it is wrapped in a TextBoxWrapper; if it is a selector or element, it is used directly. If the into parameter is actually an options object (detected by checking it is not a selector, element, or string), the function reinterprets it as the options and leaves the target as undefined (meaning the currently focused element).
The low-level _write function (lines 16-36) performs the actual character-by-character input. For each character in the text string, it checks the USKeyboardLayout definitions: if the character corresponds to a known key (such as letters, numbers, and special keys), it dispatches keyDown and keyUp events via the CDP Input.dispatchKeyEvent protocol. For characters not in the keyboard layout (such as Unicode characters), it uses Input.dispatchKeyEvent with the sendCharacter method. An optional delay between keystrokes simulates natural typing speed.
Before typing, the function focuses the target element and, if running in headful mode, highlights it for visual feedback. After typing, it constructs a human-readable description of the action, masking the text with asterisks if the target is a password field or if hideText is enabled.
Usage
Use write() to input text into form fields during automated tests. Unlike directly setting element values, write() simulates real keystrokes, which triggers JavaScript event handlers (keydown, keypress, keyup, input, change) just as a real user's typing would. This is essential for testing applications that rely on keystroke events for validation, autocomplete, or real-time formatting.
Code Reference
Source Location
- Repository: Taiko
- File (public API):
lib/taiko.js - Lines: L1092-1098
- File (implementation):
lib/actions/write.js - Lines: L38-81 (write), L16-36 (_write character-by-character input)
Signature
async write(
text: string,
into?: Selector | Element | string,
options?: {
delay?: number,
hideText?: boolean,
waitForNavigation?: boolean,
navigationTimeout?: number,
waitForStart?: number,
waitForEvents?: string[],
force?: boolean,
}
) -> Promise<void>
Import
const { write, into, textBox } = require('taiko');
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | The text to type character-by-character into the target element. Null/undefined values are coerced to an empty string with a warning. Non-string values are converted via toString().
|
| into | Selector, Element, or string | No | The target input field to type into. When omitted, types into the currently focused element. Strings are automatically wrapped in a TextBoxWrapper.
|
| options.delay | number | No (default: 0) | Delay in milliseconds between each keystroke. Useful for simulating natural typing speed or for applications that process input character-by-character. |
| options.hideText | boolean | No (default: false) | When true, the typed text is masked as asterisks in log output. Automatically enabled for password fields. |
| options.waitForNavigation | boolean | No (default: true) | Whether to wait for page navigation after the write action completes. |
| options.navigationTimeout | number | No (default: 30000) | Maximum time in milliseconds to wait for navigation after writing. |
| options.waitForStart | number | No (default: 100) | Time in milliseconds to wait for navigation to start after the action. |
| options.waitForEvents | string[] | No (default: []) | Additional browser events to wait for after the write action. |
| options.force | boolean | No (default: false) | When true, performs the write action even on hidden or disabled elements, bypassing actionability checks. |
Outputs
| Name | Type | Description |
|---|---|---|
| return | Promise<void> | Resolves when the text has been fully typed and any awaited navigation has completed. |
| Description event | string | Emits a success event with a human-readable description such as "Wrote Hello into the text box 'Email'" or "Wrote ***** into the focused element" for password fields. |
Usage Examples
Type into Focused Element
const { write } = require('taiko');
// Types into whatever element currently has focus
await write('Hello World');
Type into Specific Field
const { write, into, textBox } = require('taiko');
// Type an email address into the Email text box
await write('admin@example.com', into(textBox('Email')));
Simulate Natural Typing Speed
const { write, into, textBox } = require('taiko');
// Type with a 100ms delay between each keystroke
await write('slow typing', into(textBox('Search')), { delay: 100 });
Hide Sensitive Text in Logs
const { write, into, textBox } = require('taiko');
// Text is masked as ***** in log output
await write('secret123', into(textBox('Password')), { hideText: true });
Force Write to Hidden Element
const { write, into, textBox } = require('taiko');
// Bypass actionability checks for hidden or disabled elements
await write('value', into(textBox({ id: 'hidden-input' })), { force: true });
const { write, into, textBox } = require('taiko');
// Useful for SPAs where typing does not trigger page navigation
await write('search term', into(textBox('Query')), { waitForNavigation: false });
Write into Field by CSS Selector String
const { write, into } = require('taiko');
// Target a field using a plain string (auto-wrapped in TextBoxWrapper)
await write('John Doe', into('Full Name'));