feat(type): support special characters (like {enter}) (#308)

Closes #306 Closes #301 Closes #235 Closes #181 Closes #172 Closes #31
testing-library · Jun 4, 2020 · d38e493 · d38e493
2 parents 5c4746b + 1cf8743
commit d38e493
Show file tree

Hide file tree

Showing 12 changed files with 1,118 additions and 438 deletions.
diff --git a/README.md b/README.md
@@ -50,6 +50,7 @@ change the state of the checkbox.
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
 - [Installation](#installation)
 - [API](#api)
   - [`click(element)`](#clickelement)
@@ -158,8 +159,8 @@ import userEvent from '@testing-library/user-event'
 test('type', async () => {
   render(<textarea />)
 
-  await userEvent.type(screen.getByRole('textbox'), 'Hello, World!')
-  expect(screen.getByRole('textbox')).toHaveAttribute('value', 'Hello, World!')
+  await userEvent.type(screen.getByRole('textbox'), 'Hello,{enter}World!')
+  expect(screen.getByRole('textbox')).toHaveValue('Hello,\nWorld!')
 })
 ```
 
@@ -170,6 +171,32 @@ one character at the time. `false` is the default value.
 are typed. By default it's 0. You can use this option if your component has a
 different behavior for fast or slow users.
 
+#### Special characters
+
+The following special character strings are supported:
+
+| Text string   | Key       | Modifier   | Notes                                                                              |
+| ------------- | --------- | ---------- | ---------------------------------------------------------------------------------- |
+| `{enter}`     | Enter     | N/A        | Will insert a newline character (`<textarea />` only).                             |
+| `{esc}`       | Escape    | N/A        |                                                                                    |
+| `{backspace}` | Backspace | N/A        | Will delete the previous character (or the characters within the `selectedRange`). |
+| `{shift}`     | Shift     | `shiftKey` | Does **not** capitalize following characters.                                      |
+| `{ctrl}`      | Control   | `ctrlKey`  |                                                                                    |
+| `{alt}`       | Alt       | `altKey`   |                                                                                    |
+| `{meta}`      | OS        | `metaKey`  |                                                                                    |
+
+> **A note about modifiers:** Modifier keys (`{shift}`, `{ctrl}`, `{alt}`,
+> `{meta}`) will activate their corresponding event modifiers for the duration
+> of type command or until they are closed (via `{/shift}`, `{/ctrl}`, etc.).
+
+<!-- space out these notes -->
+
+> We take the same
+> [stance as Cypress](https://docs.cypress.io/api/commands/type.html#Modifiers)
+> in that we do not simulate the behavior that happens with modifier key
+> combinations as different operating systems function differently in this
+> regard.
+
 ### `upload(element, file, [{ clickInit, changeInit }])`
 
 Uploads file to an `<input>`. For uploading multiple files use `<input>` with
@@ -411,6 +438,7 @@ Thanks goes to these people ([emoji key][emojis]):
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.