Skip to content

Enhance default userEvent.keyboard fallback mechanism #46

@Romulad

Description

@Romulad

Describe the feature you'd like:

Current behavior

The current implementation of userEvent.keyboard parses input and looks up a mapping in keyMap.ts:

  • Special interactions (e.g. [Enter]) use the code field
  • Regular characters use the hex field
  • When no mapping is found, it falls back to:
{ code: descriptor, hex: "Unknown" }

This value is then written to the process via stdin.write.

Problem

When a character is not mapped, the fallback "Unknown" is written to output.
For example:

userEvent.keyboard('https://google.com');

Produces:

httpsUnknownUnknownUnknowngoogle.com

Instead of:

https://google.com

My suggestion

Instead of falling back to:

{ code: descriptor, hex: "Unknown" }

Fallback to:

{ code: descriptor, hex: descriptor }

This would allow unmapped characters to pass through directly to stdin.write.

Why this approach

  • Supports a much wider range of characters without requiring explicit mappings
  • Reduces maintenance overhead of manually updating the key map
  • Leverages Node.js native handling of character input instead of re-implementing it
    At the same time:
  • Special interactions (e.g. [Enter]) would still rely on explicit mappings
  • The [] syntax remains reserved and deterministic for non-text interactions

Suggested implementation:

  • Change the fallback behavior to use the raw descriptor instead of "Unknown"
  • Keep explicit mappings for special keys
  • Ensure [] syntax remains strict and reserved for special interactions

Describe alternatives you've considered:

Teachability, Documentation, Adoption, Migration Strategy:

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions