keyboardWithDelay static method Null safety

Future<KeyboardState> keyboardWithDelay(
  1. String text,
  2. Duration delay,
  3. {KeyboardState? keyboardState,
  4. bool autoModify = false,
  5. List<Map>? keyboardMap}
)

Simulates the keyboard events described by text with a delay between each keystroke.

This is similar to UserEvent.typeWithDelay but without any clicking or changing the selection range.

WARNING: When using keyboardWithDelay, the element being typed in must be allowed to keep focus or the test will fail. When running tests concurrently, do not use keyboardWithDelay, instead use UserEvent.keyboard.

Use UserEvent.keyboard for no delay.

See: github.com/testing-library/user-event#keyboardtext-options

Keystrokes can be described:

  • Per printable character
  UserEvent.keyboard('foo') // translates to: f, o, o

The brackets { and [ are used as special characters and can be referenced by doubling them.

UserEvent.keyboard('{{a[[') // translates to: {, a, [

UserEvent.keyboard('{Shift}{f}{o}{o}') // translates to: Shift, f, o, o

This does not keep any key pressed. So Shift will be lifted before pressing f.

UserEvent.keyboard('[ShiftLeft][KeyF][KeyO][KeyO]') // translates to: Shift, f, o, o
  • Per legacy UserEvent.type modifier/specialChar The modifiers like {shift} (note the lowercase) will automatically be kept pressed. You can cancel this behavior by adding a / to the end of the descriptor.
UserEvent.keyboard('{shift}{ctrl/}a{/shift}') // translates to: Shift(down), Control(down+up), a, Shift(up)

Keys can be kept pressed by adding a > to the end of the descriptor - and lifted by adding a / to the beginning of the descriptor:

UserEvent.keyboard('{Shift>}A{/Shift}') // translates to: Shift(down), A, Shift(up)

Options

keyboardState

keyboard returns a keyboard state that can be used to continue keyboard operations.

final keyboardState = UserEvent.keyboard('[ControlLeft>]') // keydown [ControlLeft]
// ... inspect some changes ...
UserEvent.keyboard('a', {keyboardState: keyboardState}) // press [KeyA] with active ctrlKey modifier

keyboardMap

The mapping of key to code is performed by a default key map portraying a "default" US-keyboard. You can provide your own local keyboard mapping per option.

UserEvent.keyboard('?', {keyboardMap: myOwnLocaleKeyboardMap})

autoModify

Future versions might try to interpolate the modifiers needed to reach a printable key on the keyboard. E.g. Automatically pressing {Shift} when CapsLock is not active and A is referenced. If you don't wish this behavior, set autoModify to false (this is false by default).

Warning About Errors

Unlike the JS API, any uncaught errors thrown during event propagation will get rethrown. This helps surface errors that could otherwise go unnoticed since they aren't printed to the terminal when running tests.

{@category UserActions}

Implementation

static Future<KeyboardState> keyboardWithDelay(
  String text,
  Duration delay, {
  KeyboardState? keyboardState,
  bool autoModify = false,
  List<Map>? keyboardMap,
}) {
  final options = {
    'delay': delay.inMilliseconds,
    'autoModify': autoModify,
    if (keyboardState != null) 'keyboardState': keyboardState,
    if (keyboardMap != null) 'keyboardMap': keyboardMap,
  };
  return eventHandlerErrorCatcher(() {
    return promiseToFuture(getProperty(_userEvent, 'keyboard')(
      text,
      jsifyAndAllowInterop(options),
      // Cast return type of JS function to be compatible with `promiseToFuture`.
    ) as Object);
  });
}