feat: support for different keyboard layouts

docs/src/api/class-androiddevice.md

@@ -149,6 +149,9 @@ Optional package name to launch instead of default Chrome for Android.
 ### option: AndroidDevice.launchBrowser.args = %%-browser-option-args-%%
 * since: v1.29
 
+### option: AndroidDevice.launchBrowser.keyboardLayout = %%-context-option-keyboard-layout-%%
+* since: v1.**
+
 ## async method: AndroidDevice.longTap
 * since: v1.9
 

docs/src/api/class-browser.md

@@ -259,6 +259,9 @@ await browser.CloseAsync();
 ### option: Browser.newContext.storageStatePath = %%-csharp-java-context-option-storage-state-path-%%
 * since: v1.9
 
+### option: Browser.newContext.keyboardLayout = %%-context-option-keyboard-layout-%%
+* since: v1.**
+
 ## async method: Browser.newPage
 * since: v1.8
 - returns: <[Page]>
@@ -284,6 +287,9 @@ testing frameworks should explicitly create [`method: Browser.newContext`] follo
 ### option: Browser.newPage.storageStatePath = %%-csharp-java-context-option-storage-state-path-%%
 * since: v1.9
 
+### option: Browser.newPage.keyboardLayout = %%-context-option-keyboard-layout-%%
+* since: v1.**
+
 ## async method: Browser.startTracing
 * since: v1.11
 * langs: java, js, python

docs/src/api/class-browsertype.md

@@ -337,6 +337,9 @@ use a temporary directory instead.
 ### option: BrowserType.launchPersistentContext.-inline- = %%-shared-context-params-list-v1.8-%%
 * since: v1.8
 
+### option: BrowserType.launchPersistentContext.keyboardLayout = %%-context-option-keyboard-layout-%%
+* since: v1.**
+
 ## async method: BrowserType.launchServer
 * since: v1.8
 * langs: js

docs/src/api/class-electron.md

@@ -145,3 +145,6 @@ Maximum time in milliseconds to wait for the application to start. Defaults to `
 
 ### option: Electron.launch.tracesDir = %%-browser-option-tracesdir-%%
 * since: v1.36
+
+### option: Electron.launch.keyboardLayout = %%-context-option-keyboard-layout-%%
+* since: v1.**

docs/src/api/class-keyboard.md

@@ -374,3 +374,14 @@ Dispatches a `keyup` event.
 - `key` <[string]>
 
 Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
+
+## async method: Keyboard.changeLayout
+* since: v1.**
+
+Changes keyboard layout.
+
+### param: Keyboard.changeLayout.layoutName
+* since: v1.**
+- `layoutName` <[string]>
+
+%%-template-keyboard-layouts-%%

docs/src/api/params.md

@@ -734,6 +734,10 @@ Whether to allow sites to register Service workers. Defaults to `'allow'`.
 * `'allow'`: [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can be registered.
 * `'block'`: Playwright will block all registration of Service Workers.
 
+## context-option-keyboard-layout
+- `keyboardLayout` <[string]>
+
+%%-template-keyboard-layouts-%%
 
 ## select-options-values
 * langs: java, js, csharp
@@ -1731,3 +1735,23 @@ In this config:
 1. Since `snapshotPathTemplate` resolves to relative path, it will be resolved relative to `configDir`.
 1. Forward slashes `"/"` can be used as path separators on any platform.
 
+## template-keyboard-layouts
+
+Keyboard layout code. Currently, the following values are supported:
+
+| Values | Name |
+| :- | :- |
+| `us`, `en-US` | [US English](https://learn.microsoft.com/en-us/globalization/keyboards/kbdus_7) <!-- 00000409 --> |
+| `gb`, `en-GB` | [British](https://learn.microsoft.com/en-us/globalization/keyboards/kbduk) <!-- 00000809 --> |
+| `dk`, `da-DK` | [Danish](https://learn.microsoft.com/en-us/globalization/keyboards/kbdda) <!-- 00000406 --> |
+| `fr`, `fr-FR` | [French](https://learn.microsoft.com/en-us/globalization/keyboards/kbdfr) <!-- 0000040C --> |
+| `de`, `de-DE` | [German](https://learn.microsoft.com/en-us/globalization/keyboards/kbdgr) <!-- 00000407  --> |
+| `it`, `it-IT` | [Italian](https://learn.microsoft.com/en-us/globalization/keyboards/kbdit) <!-- 00000410 --> |
+| `pt`, `pt-PT` | [Portuguese (Portugal)](https://learn.microsoft.com/en-us/globalization/keyboards/kbdpo) <!-- 00000816 --> |
+| `br`, `pt-BR` | [Portuguese (Brazil)](https://learn.microsoft.com/en-us/globalization/keyboards/kbdbr_1) <!-- 00000416 --> |
+| `ru`, `ru-RU` | [Russian](https://learn.microsoft.com/en-us/globalization/keyboards/kbdru) <!-- 00000419 --> |
+| `ua`, `uk-UA` | [Ukrainian](https://learn.microsoft.com/en-us/globalization/keyboards/kbdur1) <!-- 00020422 --> |
+| `es`, `es-ES`, `ca-ES` | [Spanish & Catalan (Spain)](https://learn.microsoft.com/en-us/globalization/keyboards/kbdsp) <!-- 0000040A --> |
+| `latam` | [Spanish (Latin America)](https://learn.microsoft.com/en-us/globalization/keyboards/kbdla) <!-- 0000080A --> |
+| `ch`, `de-CH` | [German (Switzerland)](https://learn.microsoft.com/en-us/globalization/keyboards/kbdsg) <!-- 00000807 --> |
+| `fr-CH`, `it-CH` | [French and Italian (Switzerland)](https://learn.microsoft.com/en-us/globalization/keyboards/kbdsf_2) <!-- 0000100C --> |

packages/playwright-core/src/client/input.ts

@@ -45,6 +45,10 @@ export class Keyboard implements api.Keyboard {
   async press(key: string, options: channels.PageKeyboardPressOptions = {}) {
     await this._page._channel.keyboardPress({ key, ...options });
   }
+
+  async changeLayout(layoutName: string): Promise<void> {
+    await this._page._channel.keyboardChangeLayout({ layoutName });
+  }
 }
 
 export class Mouse implements api.Mouse {

packages/playwright-core/src/protocol/validator.ts

@@ -568,6 +568,7 @@ scheme.BrowserTypeLaunchPersistentContextParams = tObject({
   recordHar: tOptional(tType('RecordHarOptions')),
   strictSelectors: tOptional(tBoolean),
   serviceWorkers: tOptional(tEnum(['allow', 'block'])),
+  keyboardLayout: tOptional(tString),
   userDataDir: tString,
   slowMo: tOptional(tNumber),
 });
@@ -644,6 +645,7 @@ scheme.BrowserNewContextParams = tObject({
   recordHar: tOptional(tType('RecordHarOptions')),
   strictSelectors: tOptional(tBoolean),
   serviceWorkers: tOptional(tEnum(['allow', 'block'])),
+  keyboardLayout: tOptional(tString),
   proxy: tOptional(tObject({
     server: tString,
     bypass: tOptional(tString),
@@ -705,6 +707,7 @@ scheme.BrowserNewContextForReuseParams = tObject({
   recordHar: tOptional(tType('RecordHarOptions')),
   strictSelectors: tOptional(tBoolean),
   serviceWorkers: tOptional(tEnum(['allow', 'block'])),
+  keyboardLayout: tOptional(tString),
   proxy: tOptional(tObject({
     server: tString,
     bypass: tOptional(tString),
@@ -1119,6 +1122,10 @@ scheme.PageKeyboardPressParams = tObject({
   delay: tOptional(tNumber),
 });
 scheme.PageKeyboardPressResult = tOptional(tObject({}));
+scheme.PageKeyboardChangeLayoutParams = tObject({
+  layoutName: tString,
+});
+scheme.PageKeyboardChangeLayoutResult = tOptional(tObject({}));
 scheme.PageMouseMoveParams = tObject({
   x: tNumber,
   y: tNumber,
@@ -2243,6 +2250,7 @@ scheme.ElectronLaunchParams = tObject({
   strictSelectors: tOptional(tBoolean),
   timezoneId: tOptional(tString),
   tracesDir: tOptional(tString),
+  keyboardLayout: tOptional(tString),
 });
 scheme.ElectronLaunchResult = tObject({
   electronApplication: tChannel(['ElectronApplication']),
@@ -2457,6 +2465,7 @@ scheme.AndroidDeviceLaunchBrowserParams = tObject({
   recordHar: tOptional(tType('RecordHarOptions')),
   strictSelectors: tOptional(tBoolean),
   serviceWorkers: tOptional(tEnum(['allow', 'block'])),
+  keyboardLayout: tOptional(tString),
   pkg: tOptional(tString),
   args: tOptional(tArray(tString)),
   proxy: tOptional(tObject({

packages/playwright-core/src/server/DEPS.list

@@ -21,3 +21,6 @@
 ./electron/
 ./firefox/
 ./webkit/
+
+[input.ts]
+./keyboards/

packages/playwright-core/src/server/dispatchers/pageDispatcher.ts

@@ -232,6 +232,10 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
     await this._page.keyboard.press(params.key, params);
   }
 
+  async keyboardChangeLayout(params: channels.PageKeyboardChangeLayoutParams, metadata?: CallMetadata): Promise<void> {
+    this._page.keyboard.changeLayout(params.layoutName);
+  }
+
   async mouseMove(params: channels.PageMouseMoveParams, metadata: CallMetadata): Promise<void> {
     await this._page.mouse.move(params.x, params.y, params);
   }

packages/playwright-core/src/server/input.ts

@@ -15,11 +15,12 @@
  */
 
 import { assert } from '../utils';
-import * as keyboardLayout from './usKeyboardLayout';
 import type * as types from './types';
 import type { Page } from './page';
+import type { KeyboardLayout } from './keyboards';
+import { defaultKeyboardLayout, defaultKeyboardLayoutName, keyboardLayoutNamesMapping } from './keyboards';
 
-export const keypadLocation = keyboardLayout.keypadLocation;
+export { keypadLocation } from './keyboards';
 
 type KeyDescription = {
   keyCode: number,
@@ -29,8 +30,13 @@ type KeyDescription = {
   code: string,
   location: number,
   shifted?: KeyDescription;
+  deadKeyMappings?: Map<string, string>;
 };
 
+// either the key description or a sequence of keys for accented keys
+// e.g. in portuguese, 'à' will be ['Shift+BracketRight', 'a']
+type KeyboardLayoutClosure = Map<string, KeyDescription | string[]>;
+
 const kModifiers: types.KeyboardModifier[] = ['Alt', 'Control', 'Meta', 'Shift'];
 
 export interface RawKeyboard {
@@ -44,40 +50,66 @@ export class Keyboard {
   private _pressedKeys = new Set<string>();
   private _raw: RawKeyboard;
   private _page: Page;
+  private _layoutName: string;
+  private _keyboardLayout: KeyboardLayoutClosure;
+  private _deadKeyMappings?: Map<string, string>;
 
   constructor(raw: RawKeyboard, page: Page) {
     this._raw = raw;
     this._page = page;
+    const layoutName = page._browserContext._options.keyboardLayout;
+    this._keyboardLayout = getByKeyboardLayoutName(layoutName);
+    this._layoutName = layoutName ?? 'us';
+  }
+
+  changeLayout(layoutName: string) {
+    this._keyboardLayout = getByKeyboardLayoutName(layoutName);
+    this._layoutName = layoutName;
+    this._deadKeyMappings = undefined;
   }
 
   async down(key: string) {
     const description = this._keyDescriptionForString(key);
+    if (description.key !== 'Shift') this._deadKeyMappings = undefined;
     const autoRepeat = this._pressedKeys.has(description.code);
     this._pressedKeys.add(description.code);
     if (kModifiers.includes(description.key as types.KeyboardModifier))
       this._pressedModifiers.add(description.key as types.KeyboardModifier);
-    const text = description.text;
-    await this._raw.keydown(this._pressedModifiers, description.code, description.keyCode, description.keyCodeWithoutLocation, description.key, description.location, autoRepeat, text);
+    await this._raw.keydown(this._pressedModifiers, description.code, description.keyCode, description.keyCodeWithoutLocation, description.key, description.location, autoRepeat, description.text);
   }
 
   private _keyDescriptionForString(keyString: string): KeyDescription {
-    let description = usKeyboardLayout.get(keyString);
+    let description = this._keyboardLayout.get(keyString);
     assert(description, `Unknown key: "${keyString}"`);
+    assert(!Array.isArray(description), `Accented key "${keyString}" cannot be typed with a single keypress on "${normalizeLayoutName(this._layoutName)}" keyboard layout.\nUse type() method that will generate multiple key presses.`);
+
     const shift = this._pressedModifiers.has('Shift');
     description = shift && description.shifted ? description.shifted : description;
 
     // if any modifiers besides shift are pressed, no text should be sent
     if (this._pressedModifiers.size > 1 || (!this._pressedModifiers.has('Shift') && this._pressedModifiers.size === 1))
       return { ...description, text: '' };
-    return description;
+
+    if (!this._deadKeyMappings || description.key === 'Shift') return description;
+
+    // handle deadkeys / accented keys
+    const deadKeyText = this._deadKeyMappings.get(description.text);
+
+    // this will be handled properly in the future with IME support.
+    // For now, if there's no dead key mapping for current key, we'll skip it.
+    if (!deadKeyText) return description;
+
+    return { ...description, text: deadKeyText, key: deadKeyText };
   }
 
   async up(key: string) {
     const description = this._keyDescriptionForString(key);
     if (kModifiers.includes(description.key as types.KeyboardModifier))
       this._pressedModifiers.delete(description.key as types.KeyboardModifier);
     this._pressedKeys.delete(description.code);
-    await this._raw.keyup(this._pressedModifiers, description.code, description.keyCode, description.keyCodeWithoutLocation, description.key, description.location);
+    const descKey = description.deadKeyMappings ? 'Dead' : description.key;
+    await this._raw.keyup(this._pressedModifiers, description.code, description.keyCode, description.keyCodeWithoutLocation, descKey, description.location);
+    if (description.key !== 'Shift') this._deadKeyMappings = description.deadKeyMappings;
   }
 
   async insertText(text: string) {
@@ -87,8 +119,14 @@ export class Keyboard {
   async type(text: string, options?: { delay?: number }) {
     const delay = (options && options.delay) || undefined;
     for (const char of text) {
-      if (usKeyboardLayout.has(char)) {
-        await this.press(char, { delay });
+      const descOrKeySequence = this._keyboardLayout.get(char);
+      if (descOrKeySequence) {
+        if (Array.isArray(descOrKeySequence)) {
+          for (const key of descOrKeySequence)
+            await this.press(key, { delay });
+        } else {
+          await this.press(char, { delay });
+        }
       } else {
         if (delay)
           await new Promise(f => setTimeout(f, delay));
@@ -241,10 +279,38 @@ const aliases = new Map<string, string[]>([
   ['Enter', ['\n', '\r']],
 ]);
 
-const usKeyboardLayout = buildLayoutClosure(keyboardLayout.USKeyboardLayout);
+const defaultKeyboard = _buildLayoutClosure(defaultKeyboardLayout);
+const cache = new Map<string, KeyboardLayoutClosure>(
+    // initialized with the default keyboard layout
+    [[defaultKeyboardLayoutName, defaultKeyboard]]
+);
+
+function getByKeyboardLayoutName(layoutName?: string): KeyboardLayoutClosure {
+  if (!layoutName) return defaultKeyboard;
+
+  const normalizedLayoutName = normalizeLayoutName(layoutName);
+  const klid = keyboardLayoutNamesMapping.get(normalizedLayoutName);
+  if (!klid) throw new Error(`Keyboard layout name "${layoutName}" not found`);
+
+  const cached = cache.get(klid);
+  if (cached) return cached;
+
+  const layout: KeyboardLayout = require(`./keyboards/layouts/${klid}`).default;
+  assert(layout, `No layout found for klid ${klid}`);
 
-function buildLayoutClosure(layout: keyboardLayout.KeyboardLayout): Map<string, KeyDescription> {
-  const result = new Map<string, KeyDescription>();
+  const result = _buildLayoutClosure(layout);
+
+  cache.set(klid, result);
+  return result;
+}
+
+function normalizeLayoutName(layoutName: string) {
+  return layoutName.replace(/-/g, '_').toLowerCase();
+}
+
+function _buildLayoutClosure(layout: KeyboardLayout): KeyboardLayoutClosure {
+  const result = new Map<string, KeyDescription | string[]>();
+  const accents = new Map<string, string[]>();
   for (const code in layout) {
     const definition = layout[code];
     const description: KeyDescription = {
@@ -254,19 +320,22 @@ function buildLayoutClosure(layout: keyboardLayout.KeyboardLayout): Map<string,
       code,
       text: definition.text || '',
       location: definition.location || 0,
+      deadKeyMappings: definition.key && definition.deadKeyMappings ? new Map(Object.entries(definition.deadKeyMappings)) : undefined,
     };
-    if (definition.key.length === 1)
+    if (definition.key?.length === 1)
       description.text = description.key;
 
     // Generate shifted definition.
     let shiftedDescription: KeyDescription | undefined;
     if (definition.shiftKey) {
-      assert(definition.shiftKey.length === 1);
+      assert(definition.shiftKey === 'Dead' || definition.shiftKey.length === 1);
       shiftedDescription = { ...description };
       shiftedDescription.key = definition.shiftKey;
-      shiftedDescription.text = definition.shiftKey;
+      shiftedDescription.text = definition.shiftKey === 'Dead' ? '' : definition.shiftKey;
       if (definition.shiftKeyCode)
         shiftedDescription.keyCode = definition.shiftKeyCode;
+      if (definition.shiftDeadKeyMappings)
+        shiftedDescription.deadKeyMappings = new Map(Object.entries(definition.shiftDeadKeyMappings));
     }
 
     // Map from code: Digit3 -> { ... descrption, shifted }
@@ -286,10 +355,29 @@ function buildLayoutClosure(layout: keyboardLayout.KeyboardLayout): Map<string,
     if (description.key.length === 1)
       result.set(description.key, description);
 
-    // Map from shiftKey, no shifted
-    if (shiftedDescription)
-      result.set(shiftedDescription.key, { ...shiftedDescription, shifted: undefined });
+    // Map from accented keys
+    if (definition.deadKeyMappings) {
+      for (const [k, v] of Object.entries(definition.deadKeyMappings))
+        accents.set(v, [code, k]);
+    }
+
+    if (shiftedDescription) {
+      if (shiftedDescription.key !== 'Dead')
+        // Map from shiftKey, no shifted
+        result.set(shiftedDescription.key, { ...shiftedDescription, shifted: undefined });
+
+      // Map from shifted accented keys
+      if (definition.shiftDeadKeyMappings) {
+        for (const [k, v] of Object.entries(definition.shiftDeadKeyMappings))
+          accents.set(v, [`Shift+${code}`, k]);
+      }
+    }
   }
+
+  for (const [k, v] of accents.entries())
+    // if result already has a dedicated accented key, we don't add deadkey generated accents
+    if (!result.has(k)) result.set(k, v);
+
   return result;
 }
 

packages/playwright-core/src/server/keyboards/DEPS.list

@@ -0,0 +1,2 @@
+[*]
+./layouts/