Focus
For a given WebClient, focus can be on at most one element at any given time.
Focus does not need to be set on any element.
There are several ways to move focus between elements.
The simplest way is to call HtmlPage.setFocusedElement(HtmlElement).
This method removes focus from whichever element currently holds focus (if any) and sets focus
to the target component, triggering any defined onfocus and onblur handlers along the way.
final HtmlInput userName = page.getHtmlElementById("userName");
page.setFocusedElement(userName);
The element currently owning focus can be retrieved with a call to
HtmlPage.getFocusedElement().
HtmlElement elem = page.getFocusedElement();
Item Traversal
To simulate keyboard navigation via the Tab key, call
HtmlPage.tabToNextElement() and HtmlPage.tabToPreviousElement()
to cycle forward or backward through the tab order.
This order is governed by the
tabindex
attribute on elements as defined by the HTML specification.
You can query all tabbable elements in order using HtmlPage.getTabbableElements().
Typing the Tab key (e.g. htmlElement.type(KeyboardEvent.DOM_VK_TAB) or as part of a
Keyboard) does the same, like in real browsers: the keydown event is fired
at the element having the focus, the focus moves to the next element in the tab order (to the previous one
if the shift key is pressed) and the keyup event is fired at the newly focused element.
The text of a text input getting the focus this way is selected. All following keys of the same
Keyboard are typed into the newly focused element.
If the keydown event is canceled, the focus does not move.
To assert that every tabbable element on a page has an explicit tabindex attribute set,
use WebAssert.assertAllTabIndexAttributesSet(page).
Access Keys
Access keys (keyboard mnemonics) can be simulated using the method
HtmlPage.pressAccessKey(char).
Special Keys
To send special keys, use htmlElement.type(int) with constants such as KeyboardEvent.DOM_VK_PAGE_DOWN.
To simulate typing while holding modifier keys (Shift/Ctrl/Alt/Meta), use the Keyboard class.
For example, to simulate Ctrl+C to copy content to the clipboard:
final HtmlInput input = (HtmlInput) page.getElementById("i1");
final Keyboard kb = new Keyboard();
kb.press(KeyboardEvent.DOM_VK_CONTROL);
kb.type('c');
kb.release(KeyboardEvent.DOM_VK_CONTROL);
input.type(kb);
Modifier Keys
The modifier keys are KeyboardEvent.DOM_VK_SHIFT, DOM_VK_CONTROL,
DOM_VK_ALT and DOM_VK_META.
Keyboard.press(int) presses a modifier until it is released by
Keyboard.release(int); all key events fired in between have the corresponding
shiftKey, ctrlKey, altKey or metaKey
property set.
Like in real browsers, a character typed while the control key is pressed fires no
keypress event and is not inserted into the text; only the shortcuts
Ctrl+A (select all), Ctrl+C (copy), Ctrl+X (cut) and Ctrl+V (paste) are processed.
When simulating Firefox, the same is true for the meta key.
Pressing and Releasing Single Keys
Keyboard.type(char) and Keyboard.press(int) for a key that is not a modifier
simulate a complete keystroke (keydown, keypress if the key produces a character,
input if the text was changed, keyup).
To hold a key down while other keys are typed, use keyDown() and keyUp().
keyDown() fires the keydown event (and for a character also keypress,
types the character and fires the input event); keyUp() fires only the
keyup event:
final Keyboard kb = new Keyboard();
// press 'a' and 'b' and release them in the same order:
// keydown a, keypress a, input, keydown b, keypress b, input, keyup a, keyup b
kb.keyDown('a');
kb.keyDown('b');
kb.keyUp('a');
kb.keyUp('b');
// hold the arrow left key while typing 'x'
kb.keyDown(KeyboardEvent.DOM_VK_LEFT);
kb.type('x');
kb.keyUp(KeyboardEvent.DOM_VK_LEFT);
input.type(kb);
Left and Right Keys
Some keys are available on both sides of the keyboard. By default, HtmlUnit uses the left one
(e.g. code is ShiftLeft and location is
KeyboardEvent.DOM_KEY_LOCATION_LEFT). To simulate the right one, pass the location
to keyDown(int, int) and keyUp(int, int):
final Keyboard kb = new Keyboard();
// the right shift key: code is 'ShiftRight', location is 2
kb.keyDown(KeyboardEvent.DOM_VK_SHIFT, KeyboardEvent.DOM_KEY_LOCATION_RIGHT);
kb.type('A');
kb.keyUp(KeyboardEvent.DOM_VK_SHIFT, KeyboardEvent.DOM_KEY_LOCATION_RIGHT);
input.type(kb);
Keyboard.DEFAULT_LOCATION selects the default location of the key code.
Already Pressed Modifiers
If a Keyboard continues a key sequence started by another one (e.g. the shift key
was pressed by a previous Keyboard and is still held), use
setPressedModifiers(shift, ctrl, alt, meta). These modifiers are treated as pressed
without firing keydown events for them again:
final Keyboard kb = new Keyboard();
// shift is still pressed
kb.setPressedModifiers(true, false, false, false);
kb.type('B');
kb.release(KeyboardEvent.DOM_VK_SHIFT);
input.type(kb);
Key and Input Events
The keyboard events fired by HtmlUnit provide the properties
key (e.g. ArrowUp, Enter or a),
code (e.g. ArrowUp, Enter or KeyA),
keyCode, which and location.
The current state of the modifiers is also available using getModifierState().
The input event is only fired if typing has changed the text. It is an
InputEvent providing inputType (e.g. insertText,
insertLineBreak, deleteContentBackward or insertFromPaste)
and data (the inserted text).
Clipboard
Clipboard interaction is disabled by default in WebClient to prevent side effects during testing
and to remove the requirement for a running graphical environment (e.g., Windows/X11/xvfb).
To enable clipboard support, set a clipboard handler on the WebClient.
HtmlUnit provides AwtClipboardHandler, which integrates with system/desktop clipboards:
final ClipboardHandler clipboardHandler = new AwtClipboardHandler();
webClient.setClipboardHandler(clipboardHandler);
Note: The provided AwtClipboardHandler will not work if your Java VM runs in headless mode.
If you need clipboard interaction in headless mode, write a custom implementation of ClipboardHandler.
You can directly manage clipboard content from your test cases:
clipboardHandler.setClipboardContent("HtmlUnit");
You can also implement your custom ClipboardHandler for full control over clipboard behaviors.
To interact with the clipboard, send standard keyboard shortcuts:
final Keyboard kb = new Keyboard();
// Select all
kb.press(KeyboardEvent.DOM_VK_CONTROL);
kb.type('a');
kb.release(KeyboardEvent.DOM_VK_CONTROL);
// Copy
kb.press(KeyboardEvent.DOM_VK_CONTROL);
kb.type('c');
kb.release(KeyboardEvent.DOM_VK_CONTROL);
input.type(kb);
final Keyboard kb = new Keyboard();
// Paste
kb.press(KeyboardEvent.DOM_VK_CONTROL);
kb.type('v');
kb.release(KeyboardEvent.DOM_VK_CONTROL);
input.type(kb);

