feat(paste): Add paste API (fixes #311)

README.md

@@ -55,6 +55,7 @@ change the state of the checkbox.
   - [`click(element)`](#clickelement)
   - [`dblClick(element)`](#dblclickelement)
   - [`async type(element, text, [options])`](#async-typeelement-text-options)
+  - [`async paste(element, text, [options])`](#async-pasteelement-text-options)
   - [`upload(element, file, [{ clickInit, changeInit }])`](#uploadelement-file--clickinit-changeinit-)
   - [`clear(element)`](#clearelement)
   - [`selectOptions(element, values)`](#selectoptionselement-values)
@@ -166,9 +167,6 @@ test('type', async () => {
 })
 ```
 
-If `options.allAtOnce` is `true`, `type` will write `text` at once rather than
-one character at the time. `false` is the default value.
-
 `options.delay` is the number of milliseconds that pass between two characters
 are typed. By default it's 0. You can use this option if your component has a
 different behavior for fast or slow users.
@@ -199,6 +197,23 @@ The following special character strings are supported:
 > combinations as different operating systems function differently in this
 > regard.
 
+### `async paste(element, text, [options])`
+
+Pastes `text` inside an `<input>` or a `<textarea>`.
+
+```jsx
+import React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+test('paste', async () => {
+  render(<textarea />)
+
+  await userEvent.paste(screen.getByRole('textbox'), 'Hello,{enter}World!')
+  expect(screen.getByRole('textbox')).toHaveValue('Hello,\nWorld!')
+})
+```
+
 ### `upload(element, file, [{ clickInit, changeInit }])`
 
 Uploads file to an `<input>`. For uploading multiple files use `<input>` with
@@ -517,6 +532,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.

src/__tests__/paste.js

@@ -0,0 +1,157 @@
+import React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '..'
+import {setup} from './helpers/utils'
+import './helpers/customElement'
+
+test('should paste text', async () => {
+  const {element, getEventCalls} = setup(<input />)
+  await userEvent.paste(element, 'Sup')
+  expect(getEventCalls()).toMatchInlineSnapshot(`
+    focus
+    input: "{CURSOR}" -> "Sup"
+  `)
+})
+
+test('does not paste when readOnly', () => {
+  const handleChange = jest.fn()
+  render(<input data-testid="input" readOnly onChange={handleChange} />)
+  userEvent.paste(screen.getByTestId('input'), 'hi')
+  expect(handleChange).not.toHaveBeenCalled()
+})
+
+test('does not paste when disabled', () => {
+  const handleChange = jest.fn()
+  render(<input data-testid="input" disabled onChange={handleChange} />)
+  userEvent.paste(screen.getByTestId('input'), 'hi')
+  expect(handleChange).not.toHaveBeenCalled()
+})
+
+test.each(['input', 'textarea'])('should paste text in <%s>', type => {
+  const onChange = jest.fn()
+  render(
+    React.createElement(type, {
+      'data-testid': 'input',
+      onChange,
+    }),
+  )
+  const text = 'Hello, world!'
+  userEvent.paste(screen.getByTestId('input'), text)
+
+  expect(onChange).toHaveBeenCalledTimes(1)
+  expect(screen.getByTestId('input')).toHaveProperty('value', text)
+})
+
+test.each(['input', 'textarea'])(
+  'should paste text in <%s> up to maxLength if provided',
+  async type => {
+    const onChange = jest.fn()
+    const onKeyDown = jest.fn()
+    const onKeyPress = jest.fn()
+    const onKeyUp = jest.fn()
+    const maxLength = 10
+
+    render(
+      React.createElement(type, {
+        'data-testid': 'input',
+        onChange,
+        onKeyDown,
+        onKeyPress,
+        onKeyUp,
+        maxLength,
+      }),
+    )
+
+    const text = 'superlongtext'
+    const slicedText = text.slice(0, maxLength)
+
+    const inputEl = screen.getByTestId('input')
+
+    await userEvent.type(inputEl, text)
+
+    expect(inputEl).toHaveProperty('value', slicedText)
+    expect(onChange).toHaveBeenCalledTimes(slicedText.length)
+    expect(onKeyPress).toHaveBeenCalledTimes(text.length)
+    expect(onKeyDown).toHaveBeenCalledTimes(text.length)
+    expect(onKeyUp).toHaveBeenCalledTimes(text.length)
+
+    inputEl.value = ''
+    onChange.mockClear()
+    onKeyPress.mockClear()
+    onKeyDown.mockClear()
+    onKeyUp.mockClear()
+
+    userEvent.paste(inputEl, text)
+
+    expect(inputEl).toHaveProperty('value', slicedText)
+    expect(onChange).toHaveBeenCalledTimes(1)
+    expect(onKeyPress).not.toHaveBeenCalled()
+    expect(onKeyDown).not.toHaveBeenCalled()
+    expect(onKeyUp).not.toHaveBeenCalled()
+  },
+)
+
+test.each(['input', 'textarea'])(
+  'should append text in <%s> up to maxLength if provided',
+  async type => {
+    const onChange = jest.fn()
+    const onKeyDown = jest.fn()
+    const onKeyPress = jest.fn()
+    const onKeyUp = jest.fn()
+    const maxLength = 10
+
+    render(
+      React.createElement(type, {
+        'data-testid': 'input',
+        onChange,
+        onKeyDown,
+        onKeyPress,
+        onKeyUp,
+        maxLength,
+      }),
+    )
+
+    const text1 = 'superlong'
+    const text2 = 'text'
+    const text = text1 + text2
+    const slicedText = text.slice(0, maxLength)
+
+    const inputEl = screen.getByTestId('input')
+
+    await userEvent.type(inputEl, text1)
+    await userEvent.type(inputEl, text2)
+
+    expect(inputEl).toHaveProperty('value', slicedText)
+    expect(onChange).toHaveBeenCalledTimes(slicedText.length)
+    expect(onKeyPress).toHaveBeenCalledTimes(text.length)
+    expect(onKeyDown).toHaveBeenCalledTimes(text.length)
+    expect(onKeyUp).toHaveBeenCalledTimes(text.length)
+
+    inputEl.value = ''
+    onChange.mockClear()
+    onKeyPress.mockClear()
+    onKeyDown.mockClear()
+    onKeyUp.mockClear()
+
+    userEvent.paste(inputEl, text)
+
+    expect(inputEl).toHaveProperty('value', slicedText)
+    expect(onChange).toHaveBeenCalledTimes(1)
+    expect(onKeyPress).not.toHaveBeenCalled()
+    expect(onKeyDown).not.toHaveBeenCalled()
+    expect(onKeyUp).not.toHaveBeenCalled()
+  },
+)
+
+test('should replace selected text all at once', async () => {
+  const onChange = jest.fn()
+  const {
+    container: {firstChild: input},
+  } = render(<input defaultValue="hello world" onChange={onChange} />)
+  const selectionStart = 'hello world'.search('world')
+  const selectionEnd = selectionStart + 'world'.length
+  input.setSelectionRange(selectionStart, selectionEnd)
+  await userEvent.paste(input, 'friend')
+  expect(onChange).toHaveBeenCalledTimes(1)
+  expect(input).toHaveValue('hello friend')
+})

src/__tests__/type.js

@@ -69,15 +69,6 @@ it('types text in textarea', async () => {
   `)
 })
 
-test('should append text all at once', async () => {
-  const {element, getEventCalls} = setup(<input />)
-  await userEvent.type(element, 'Sup', {allAtOnce: true})
-  expect(getEventCalls()).toMatchInlineSnapshot(`
-    focus
-    input: "{CURSOR}" -> "Sup"
-  `)
-})
-
 test('does not fire input event when keypress calls prevent default', async () => {
   const {element, getEventCalls} = setup(
     <input onKeyPress={e => e.preventDefault()} />,
@@ -164,20 +155,6 @@ test.each(['input', 'textarea'])(
   },
 )
 
-test('does not type when readOnly even with allAtOnce', () => {
-  const handleChange = jest.fn()
-  render(<input data-testid="input" readOnly onChange={handleChange} />)
-  userEvent.type(screen.getByTestId('input'), 'hi', {allAtOnce: true})
-  expect(handleChange).not.toHaveBeenCalled()
-})
-
-test('does not type when disabled even with allAtOnce', () => {
-  const handleChange = jest.fn()
-  render(<input data-testid="input" disabled onChange={handleChange} />)
-  userEvent.type(screen.getByTestId('input'), 'hi', {allAtOnce: true})
-  expect(handleChange).not.toHaveBeenCalled()
-})
-
 test('should delay the typing when opts.delay is not 0', async () => {
   const inputValues = [{timestamp: Date.now(), value: ''}]
   const onInput = jest.fn(event => {
@@ -202,131 +179,6 @@ test('should delay the typing when opts.delay is not 0', async () => {
   }
 })
 
-test.each(['input', 'textarea'])(
-  'should type text in <%s> all at once',
-  type => {
-    const onChange = jest.fn()
-    render(
-      React.createElement(type, {
-        'data-testid': 'input',
-        onChange,
-      }),
-    )
-    const text = 'Hello, world!'
-    userEvent.type(screen.getByTestId('input'), text, {
-      allAtOnce: true,
-    })
-
-    expect(onChange).toHaveBeenCalledTimes(1)
-    expect(screen.getByTestId('input')).toHaveProperty('value', text)
-  },
-)
-
-test.each(['input', 'textarea'])(
-  'should enter text in <%s> up to maxLength if provided',
-  async type => {
-    const onChange = jest.fn()
-    const onKeyDown = jest.fn()
-    const onKeyPress = jest.fn()
-    const onKeyUp = jest.fn()
-    const maxLength = 10
-
-    render(
-      React.createElement(type, {
-        'data-testid': 'input',
-        onChange,
-        onKeyDown,
-        onKeyPress,
-        onKeyUp,
-        maxLength,
-      }),
-    )
-
-    const text = 'superlongtext'
-    const slicedText = text.slice(0, maxLength)
-
-    const inputEl = screen.getByTestId('input')
-
-    await userEvent.type(inputEl, text)
-
-    expect(inputEl).toHaveProperty('value', slicedText)
-    expect(onChange).toHaveBeenCalledTimes(slicedText.length)
-    expect(onKeyPress).toHaveBeenCalledTimes(text.length)
-    expect(onKeyDown).toHaveBeenCalledTimes(text.length)
-    expect(onKeyUp).toHaveBeenCalledTimes(text.length)
-
-    inputEl.value = ''
-    onChange.mockClear()
-    onKeyPress.mockClear()
-    onKeyDown.mockClear()
-    onKeyUp.mockClear()
-
-    userEvent.type(inputEl, text, {
-      allAtOnce: true,
-    })
-
-    expect(inputEl).toHaveProperty('value', slicedText)
-    expect(onChange).toHaveBeenCalledTimes(1)
-    expect(onKeyPress).not.toHaveBeenCalled()
-    expect(onKeyDown).not.toHaveBeenCalled()
-    expect(onKeyUp).not.toHaveBeenCalled()
-  },
-)
-
-test.each(['input', 'textarea'])(
-  'should append text in <%s> up to maxLength if provided',
-  async type => {
-    const onChange = jest.fn()
-    const onKeyDown = jest.fn()
-    const onKeyPress = jest.fn()
-    const onKeyUp = jest.fn()
-    const maxLength = 10
-
-    render(
-      React.createElement(type, {
-        'data-testid': 'input',
-        onChange,
-        onKeyDown,
-        onKeyPress,
-        onKeyUp,
-        maxLength,
-      }),
-    )
-
-    const text1 = 'superlong'
-    const text2 = 'text'
-    const text = text1 + text2
-    const slicedText = text.slice(0, maxLength)
-
-    const inputEl = screen.getByTestId('input')
-
-    await userEvent.type(inputEl, text1)
-    await userEvent.type(inputEl, text2)
-
-    expect(inputEl).toHaveProperty('value', slicedText)
-    expect(onChange).toHaveBeenCalledTimes(slicedText.length)
-    expect(onKeyPress).toHaveBeenCalledTimes(text.length)
-    expect(onKeyDown).toHaveBeenCalledTimes(text.length)
-    expect(onKeyUp).toHaveBeenCalledTimes(text.length)
-
-    inputEl.value = ''
-    onChange.mockClear()
-    onKeyPress.mockClear()
-    onKeyDown.mockClear()
-    onKeyUp.mockClear()
-
-    userEvent.type(inputEl, text, {
-      allAtOnce: true,
-    })
-
-    expect(inputEl).toHaveProperty('value', slicedText)
-    expect(onChange).toHaveBeenCalledTimes(1)
-    expect(onKeyPress).not.toHaveBeenCalled()
-    expect(onKeyDown).not.toHaveBeenCalled()
-    expect(onKeyUp).not.toHaveBeenCalled()
-  },
-)
-
 test('should fire events on the currently focused element', async () => {
   const changeFocusLimit = 7
   const onKeyDown = jest.fn(event => {
@@ -423,19 +275,6 @@ test('should replace selected text one by one up to maxLength if provided', asyn
   expect(input).toHaveValue(slicedText)
 })
 
-test('should replace selected text all at once', async () => {
-  const onChange = jest.fn()
-  const {
-    container: {firstChild: input},
-  } = render(<input defaultValue="hello world" onChange={onChange} />)
-  const selectionStart = 'hello world'.search('world')
-  const selectionEnd = selectionStart + 'world'.length
-  input.setSelectionRange(selectionStart, selectionEnd)
-  await userEvent.type(input, 'friend', {allAtOnce: true})
-  expect(onChange).toHaveBeenCalledTimes(1)
-  expect(input).toHaveValue('hello friend')
-})
-
 test('does not continue firing events when disabled during typing', async () => {
   function TestComp() {
     const [disabled, setDisabled] = React.useState(false)