Simulated User Events

`.type()` is one of Cypress's action commands: it takes the element the chain is holding, waits for it to be ready, and then plays your string at it as real keyboard events. What surprises people first is that the string is not sent verbatim — Cypress parses it, and anything inside curly braces is an instruction rather than text. ## What a keystroke actually is If the element is not already focused, Cypress issues a `.click()` on it first to bring focus there. Then, for each character, it fires the events a browser would fire: `keydown`, `keypress`, `beforeinput`, `textInput`, `input`, `keyup`. Not every key produces all six — `keypress` fires only for keys that produce one, `textInput` only when a character would actually be inserted, and `input` only when the element's value really changes. A `change` event follows either when `{enter}` is pressed and the value has moved since the last focus, or when the element later loses focus. Cypress also honours cancellation: if your app calls `preventDefault()` on `keydown`, the later events in that chain do not fire, exactly as in a real browser. ## The sequences and what each one does | Sequence | Effect | | --- | --- | | `{enter}` | Presses Enter, and fires `change` if the value moved since focus | | `{esc}` | Presses Escape | | `{backspace}` / `{del}` | Deletes to the left / right of the caret | | `{selectall}` | Selects the whole value by creating a selection range | | `{moveToStart}` / `{moveToEnd}` | Puts the caret at the start / end of a typeable element | | `{leftArrow}` `{rightArrow}` `{upArrow}` `{downArrow}` | Moves the caret | | `{home}` `{end}` `{pageUp}` `{pageDown}` | Line and page navigation | | `{insert}` | Inserts to the right of the caret | | `{ctrl}` `{shift}` `{alt}` `{meta}` | Activate a modifier for the rest of the command | The modifiers are the odd ones out, because they are a flag rather than a key press. `cy.get('#catalogue-notes').type('{ctrl}b')` types the letter `b` with `ctrlKey: true` set on its key events. By default every modifier is released when the command ends. Passing `{ release: false }` keeps it held across the commands that follow in the same test, which is how you build a shift-click; Cypress releases every modifier between tests regardless, so a held key cannot leak into the next `it`. ## When a brace is not a sequence An unknown group in braces is an **error, not literal text**. Typing a borrower's note that happens to read `{hold}` fails with: ``` Special character sequence: `{hold}` is not recognized. Available sequences are: ... If you want to skip parsing special character sequences and type the text exactly as written, pass the option: `{ parseSpecialCharSequences: false }` ``` That error is a good thing — the alternative would be a test that silently types nine characters where you meant a key press. It bites most often on generated data: ISBNs are safe, but note fields, JSON pasted into a textarea, and passwords from a generator are not. ## The two escape hatches 1. **`{{}` types a literal opening brace.** A closing `}` with no opener is already literal, so `.type('{{}hold}')` puts `{hold}` in the field. This is the surgical option when one brace in a mostly-normal string needs escaping. 2. **`{ parseSpecialCharSequences: false }` turns parsing off for the whole call.** Nothing in that string is interpreted, which is what you want for opaque values — a generated password, a pasted payload — where you cannot know in advance what braces it contains. Neither is a backslash escape. `.type('\\{hold}')` types a backslash followed by the same rejected sequence. ## Why `.clear()` inherits all of this `.clear()` has no keyboard machinery of its own — Cypress runs it as `.type('{selectall}{del}')` against the same element. That explains three things people find odd about it: - It only accepts an `input` or a `textarea`, because that is what `{selectall}` can act on. - It fires the same `input` and `keydown` events a user emptying the field would fire, so a controlled component's `onChange` runs. It is not a silent value reset. - It goes through the same readiness wait as any other action, so clearing a field hidden behind a collapsed panel fails the same way typing into it would. ## In a library catalogue suite Typical uses look like this: `cy.get('[data-cy=catalogue-search]').type('Dune{enter}')` submits the search the way a reader would; `.type('{selectall}Le Guin')` replaces the previous term without a separate `.clear()`; and `.type('{esc}')` closes an open suggestion list. When the string comes from a fixture rather than a literal — a borrower note, an imported record — reach for `parseSpecialCharSequences: false` rather than hoping the data is brace-free. Two more constraints are worth knowing before you go looking for a bug. `.type()` refuses an empty string (*cannot accept an empty string. You need to actually type something*) — use `.clear()` for that. And it requires a typeable element: an `input` with a text-like `type`, a `textarea`, `body`, or anything carrying `tabindex` or `contenteditable`. Targeting a child node of a `contenteditable` element fails, because the child is not itself editable; click the editable element first, then type into it.