Keyboard interactor

[cowboyd]

Both Cypress and RTL have the concept of "typing" input directly into the keyboard rather than associating input with a single component as we do with our fillIn() action. In other words, to simulate filling out a password form in cypress, you could, with the focus on the username field say:

cy.type("cowboyd{tab}my-password{enter}")

https://docs.cypress.io/api/commands/type.html

Similarly in RTL, you would say:

UserEvent.type(document.activeElement, "cowboyd{tab}my-password{enter}")

https://github.com/testing-library/user-event#typeelement-text-options

This approach has several advantages. The first is purely practical. It allows you to define keyboard interactions that span input elements. So while we could enhance the fillIn helper to generate control character events, it would be weird to submit a login form by "filling in" the just the username field:

TextField("username").fillIn("cowboyd{tab}my-password{enter}")

Some interactions aren't targeted at a field at all. What about if I want to test dismissing a modal dialog by pressing the ESC key? In that case, it's doesn't matter which element has focus. Choosing anything other than the current focus to do that feels arbitrary.... and could even fail to catch bugs if the application's key handler is misconfigured and catches key events from the element the test case is dispatching do, but not to catch key events that are dispatched from the document's current natural focus.

The second advantage is philosophical in that it is more aligned with what users actually do and how they think. They don't enter text directly into a component. They enter a stream of character inputs into the keyboard which then inserts characters on their behalf onto the component with focus.

What if we had a separate Keybord interactor whose element was whatever happened to have the document focus?

export const { Keyboard } = createInteractor('keyboard')({
  selector: ':focus',
  actions: {
    type: (sequence) => {/*...*/}
  }
});

which could then be used as:

Kebyoard.type("{tab}{tab}{tab}");

This isn't to say that individual components don't have fillIn actions, but they can delegate to the keyboard interactor where appropriate:

export const { TextField } = createInteractor('keyboard')({
  actions: {
    fillIn: async (interactor, value) => {
      await interactor.focus();
      await Keyboard().type(value);
      await interactor.blur();
    })
  }
});

This lets us have the best of both worlds.

[jbolda]

This feels like a positive change. My greatest curiosity though would be if we could remove the focus requirement as that has been a constant "gotcha".

[cowboyd]

Yeah, it is pretty annoying, though hopefully less so with a headless mode. What do we do if there is no document focus? Issue a warning and dispatch it on a the document? That might be a good compromise

[jbolda]

Considering integrating this in other libraries and the possible lack of existence / usability of headless mode, it feels like we should address it. The document dispatch might work fine? I don't remember running into this with other setups, I wonder what they do?