feat: apis to set / change keyboard layout

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

@@ -260,6 +260,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]>
@@ -285,6 +288,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

@@ -321,6 +321,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,12 @@ 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.layout
+* since: v1.**
+- `layout` <[string]>

docs/src/api/params.md

@@ -307,7 +307,7 @@ When using [`method: Page.goto`], [`method: Page.route`], [`method: Page.waitFor
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
-Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. 
+Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.
 Use `null` to disable the consistent viewport emulation. Learn more about [viewport emulation](../emulation#viewport).
 
 :::note
@@ -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]>
+
+Keyboard layout.
 
 ## select-options-values
 * langs: java, js, csharp

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(locale: string): Promise<void> {
+    await this._page._channel.keyboardChangeLayout({ locale });
+  }
 }
 
 export class Mouse implements api.Mouse {

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

@@ -566,6 +566,7 @@ scheme.BrowserTypeLaunchPersistentContextParams = tObject({
   recordHar: tOptional(tType('RecordHarOptions')),
   strictSelectors: tOptional(tBoolean),
   serviceWorkers: tOptional(tEnum(['allow', 'block'])),
+  keyboardLayout: tOptional(tString),
   userDataDir: tString,
   slowMo: tOptional(tNumber),
 });
@@ -642,6 +643,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),
@@ -703,6 +705,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),
@@ -1117,6 +1120,10 @@ scheme.PageKeyboardPressParams = tObject({
   delay: tOptional(tNumber),
 });
 scheme.PageKeyboardPressResult = tOptional(tObject({}));
+scheme.PageKeyboardChangeLayoutParams = tObject({
+  locale: tString,
+});
+scheme.PageKeyboardChangeLayoutResult = tOptional(tObject({}));
 scheme.PageMouseMoveParams = tObject({
   x: tNumber,
   y: tNumber,
@@ -2241,6 +2248,7 @@ scheme.ElectronLaunchParams = tObject({
   strictSelectors: tOptional(tBoolean),
   timezoneId: tOptional(tString),
   tracesDir: tOptional(tString),
+  keyboardLayout: tOptional(tString),
 });
 scheme.ElectronLaunchResult = tObject({
   electronApplication: tChannel(['ElectronApplication']),
@@ -2455,6 +2463,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/dispatchers/pageDispatcher.ts

@@ -233,6 +233,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.locale);
+  }
+
   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

@@ -50,12 +50,11 @@ export class Keyboard {
   constructor(raw: RawKeyboard, page: Page) {
     this._raw = raw;
     this._page = page;
-    // TODO maybe replace env variable with a browserContext option?
-    this._keyboardLayout = getByLocale(process.env.PW_KEYBOARD_LAYOUT);
+    this._keyboardLayout = getByLocale(page._browserContext._options.keyboardLayout);
   }
 
-  _testKeyboardLayout(layoutName: string) {
-    this._keyboardLayout = getByLocale(layoutName);
+  changeLayout(locale: string) {
+    this._keyboardLayout = getByLocale(locale);
   }
 
   async down(key: string) {

packages/playwright-core/types/types.d.ts

@@ -12747,6 +12747,11 @@ export interface BrowserType<Unused = {}> {
      */
     javaScriptEnabled?: boolean;
 
+    /**
+     * Keyboard layout.
+     */
+    keyboardLayout?: string;
+
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
      * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
@@ -12958,7 +12963,7 @@ export interface BrowserType<Unused = {}> {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
      * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
      *
      * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
@@ -14154,6 +14159,11 @@ export interface AndroidDevice {
      */
     javaScriptEnabled?: boolean;
 
+    /**
+     * Keyboard layout.
+     */
+    keyboardLayout?: string;
+
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
      * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
@@ -14348,7 +14358,7 @@ export interface AndroidDevice {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
      * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
      *
      * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
@@ -16029,6 +16039,11 @@ export interface Browser extends EventEmitter {
      */
     javaScriptEnabled?: boolean;
 
+    /**
+     * Keyboard layout.
+     */
+    keyboardLayout?: string;
+
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
      * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
@@ -16283,7 +16298,7 @@ export interface Browser extends EventEmitter {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
      * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
      *
      * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
@@ -16899,6 +16914,11 @@ export interface Electron {
      */
     ignoreHTTPSErrors?: boolean;
 
+    /**
+     * Keyboard layout.
+     */
+    keyboardLayout?: string;
+
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
      * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
@@ -17543,6 +17563,12 @@ export interface FrameLocator {
  *
  */
 export interface Keyboard {
+  /**
+   * Changes keyboard layout.
+   * @param layout
+   */
+  changeLayout(layout: string): Promise<void>;
+
   /**
    * Dispatches a `keydown` event.
    *
@@ -19166,6 +19192,11 @@ export interface BrowserContextOptions {
    */
   javaScriptEnabled?: boolean;
 
+  /**
+   * Keyboard layout.
+   */
+  keyboardLayout?: string;
+
   /**
    * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
    * `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
@@ -19420,7 +19451,7 @@ export interface BrowserContextOptions {
   videosPath?: string;
 
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
    * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
    *
    * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined

packages/protocol/src/channels.ts

@@ -977,6 +977,7 @@ export type BrowserTypeLaunchPersistentContextParams = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   userDataDir: string,
   slowMo?: number,
 };
@@ -1048,6 +1049,7 @@ export type BrowserTypeLaunchPersistentContextOptions = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   slowMo?: number,
 };
 export type BrowserTypeLaunchPersistentContextResult = {
@@ -1150,6 +1152,7 @@ export type BrowserNewContextParams = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   proxy?: {
     server: string,
     bypass?: string,
@@ -1208,6 +1211,7 @@ export type BrowserNewContextOptions = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   proxy?: {
     server: string,
     bypass?: string,
@@ -1269,6 +1273,7 @@ export type BrowserNewContextForReuseParams = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   proxy?: {
     server: string,
     bypass?: string,
@@ -1327,6 +1332,7 @@ export type BrowserNewContextForReuseOptions = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   proxy?: {
     server: string,
     bypass?: string,
@@ -1754,6 +1760,7 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {
   keyboardInsertText(params: PageKeyboardInsertTextParams, metadata?: CallMetadata): Promise<PageKeyboardInsertTextResult>;
   keyboardType(params: PageKeyboardTypeParams, metadata?: CallMetadata): Promise<PageKeyboardTypeResult>;
   keyboardPress(params: PageKeyboardPressParams, metadata?: CallMetadata): Promise<PageKeyboardPressResult>;
+  keyboardChangeLayout(params: PageKeyboardChangeLayoutParams, metadata?: CallMetadata): Promise<PageKeyboardChangeLayoutResult>;
   mouseMove(params: PageMouseMoveParams, metadata?: CallMetadata): Promise<PageMouseMoveResult>;
   mouseDown(params: PageMouseDownParams, metadata?: CallMetadata): Promise<PageMouseDownResult>;
   mouseUp(params: PageMouseUpParams, metadata?: CallMetadata): Promise<PageMouseUpResult>;
@@ -2048,6 +2055,13 @@ export type PageKeyboardPressOptions = {
   delay?: number,
 };
 export type PageKeyboardPressResult = void;
+export type PageKeyboardChangeLayoutParams = {
+  locale: string,
+};
+export type PageKeyboardChangeLayoutOptions = {
+
+};
+export type PageKeyboardChangeLayoutResult = void;
 export type PageMouseMoveParams = {
   x: number,
   y: number,
@@ -4016,6 +4030,7 @@ export type ElectronLaunchParams = {
   strictSelectors?: boolean,
   timezoneId?: string,
   tracesDir?: string,
+  keyboardLayout?: string,
 };
 export type ElectronLaunchOptions = {
   executablePath?: string,
@@ -4051,6 +4066,7 @@ export type ElectronLaunchOptions = {
   strictSelectors?: boolean,
   timezoneId?: string,
   tracesDir?: string,
+  keyboardLayout?: string,
 };
 export type ElectronLaunchResult = {
   electronApplication: ElectronApplicationChannel,
@@ -4426,6 +4442,7 @@ export type AndroidDeviceLaunchBrowserParams = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   pkg?: string,
   args?: string[],
   proxy?: {
@@ -4482,6 +4499,7 @@ export type AndroidDeviceLaunchBrowserOptions = {
   recordHar?: RecordHarOptions,
   strictSelectors?: boolean,
   serviceWorkers?: 'allow' | 'block',
+  keyboardLayout?: string,
   pkg?: string,
   args?: string[],
   proxy?: {