keyboard static method Null safety

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

Simulates the keyboard events described by text.

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

To add a delay between each keystroke, use UserEvent.keyboardWithDelay.

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 KeyboardState keyboard(
  String text, {
  KeyboardState? keyboardState,
  bool autoModify = false,
  List<Map>? keyboardMap,
}) {
  final options = {
    'autoModify': autoModify,
    if (keyboardState != null) 'keyboardState': keyboardState,
    if (keyboardMap != null) 'keyboardMap': keyboardMap,
  };
  return eventHandlerErrorCatcher(() {
    return getProperty(_userEvent, 'keyboard')(
      text,
      jsifyAndAllowInterop(options),
    ) as KeyboardState;
  });
}