Keyboard Layouts in Webdriver

This issues discusses several solutions to keyboard layouts in WebDriver.

Background

While working on keyboard inputs in Chromium, several reviewers brought up keyboard layout and questioned why webdriver assumes a US layout. For the most part, they were primarily concerned with shortcuts that certain keyboard combinations would trigger (although in webdriver, events are emitted on the page, not at the browser level), but nonetheless confused by the assumption.

Problem

With the current specification, the code property of KeyboardEvents only works for US users and developers cannot test for international keyboard layouts.

• https://github.com/w3c/webdriver/issues/1282
• https://github.com/SeleniumHQ/selenium/issues/4523

Requirements

When coming up with solutions, the following requirements were imagined:

• All keyboard layouts should be testable (e.g. Dvorak, German, etc).
• Browser binary size must remain the same

Solutions

Native keyboard layouts

Within Chromium, we have code that can gather information about the current keyboard layout on the device it runs on. This can be used to get the current code. (I assume this is also the case with Firefox and Safari).

Pros

• Minimal code required.

Cons

• Testing becomes dependent on the testing OS (maybe a good thing? Otherwise, what's the point of testing different OSes).
• Potential cross-browser flakiness based on implementation (which can be mixed with OS problems; hard to debug).

Keyboard layout registry

We can add another API that handles registering keyboard layouts with a default to US.

Pros

• Minimal code on the vendor side.
• Testing is reproducible across browsers and OSes.

Cons

• Layout code lives in user-land (which can technically implement the first solution).

code value (recommended)

We can add an additional, optional code parameter to the key action object which is a KeyboardEvent code value specified in https://www.w3.org/TR/uievents-code/. It would default to the US layout.

This change would also require a slight modification of the dispatching mechanism; specifically, we should add the code and key to an input source's pressed state rather than just the key. Alternatively, we can store the code to mimic a real keyboard instead of key.

Pros

• Minimal code on the both sides.
• Testing is reproducible across browsers and OSes.
• No "layout" code required; just use the combination you need.

References

• https://www.w3.org/TR/webdriver/#dfn-code

CC: @gsnedders, @jgraham, @whimboo

The issue names no repository files or tests. Start with the WebDriver code definition and the linked WebDriver and Selenium issues, then compare the proposed key action and input-source state changes against the specification. Done means selecting a settled design that supports reproducible international layouts without increasing browser binary size.