New option: autoFocusDocumentBeforeTyping to reduce real browser testing flakiness

src/keyboard/index.ts

@@ -1,6 +1,7 @@
+import {fireEvent} from '@testing-library/dom'
 import type {Instance} from '../setup'
 import type {keyboardKey} from '../system/keyboard'
-import {wait} from '../utils'
+import {getActiveElementOrBody, wait} from '../utils'
 import {parseKeyDef} from './parseKeyDef'
 
 interface KeyboardAction {
@@ -11,6 +12,9 @@ interface KeyboardAction {
 }
 
 export async function keyboard(this: Instance, text: string): Promise<void> {
+  if (this.config.autoFocusDocumentBeforeTyping) {
+    fireEvent.focus(getActiveElementOrBody(this.config.document))
+  }
   const actions: KeyboardAction[] = parseKeyDef(this.config.keyboardMap, text)
 
   for (let i = 0; i < actions.length; i++) {

src/options.ts

@@ -35,6 +35,16 @@ export interface Options {
    */
   autoModify?: boolean
 
+  /**
+   * Automatically focus the active document before interacting with the keyboard.
+   *
+   * Recommended to enable it whenever the test is running against a real web browser and
+   * a real user interaction may interfere with the test.
+   *
+   * @default false
+   */
+  autoFocusDocumentBeforeTyping?: boolean
+
   /**
    * Between some subsequent inputs like typing a series of characters
    * the code execution is delayed per `setTimeout` for (at least) `delay` seconds.

src/setup/setup.ts

@@ -21,6 +21,7 @@ import {DirectOptions} from './directApi'
 const defaultOptionsDirect: Required<Options> = {
   applyAccept: true,
   autoModify: true,
+  autoFocusDocumentBeforeTyping: false,
   delay: 0,
   document: globalThis.document,
   keyboardMap: defaultKeyboardMap,