API utilitaires

[Traduction Bêta Non Officielle]

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Les API suivantes n'ont pas d'équivalent direct dans une interaction utilisateur réelle.
Leur comportement constitue donc une interprétation de la façon dont l'interaction "perçue" pourrait être traduite en événements réels sur le DOM.

clear()

clear(element: Element): Promise<void>

Cette API permet de vider facilement un élément éditable.

1. Donne le focus à l'élément

2. Sélectionne tout le contenu comme via le menu du navigateur

3. Supprime le contenu comme via le menu du navigateur

test('clear', async () => {
  const user = userEvent.setup()

  render(<textarea defaultValue="Hello, World!" />)

  await user.clear(screen.getByRole('textbox'))

  expect(screen.getByRole('textbox')).toHaveValue('')
})

La Promise est rejetée si l'élément ne peut pas recevoir le focus ou si le contenu ne peut pas être sélectionné.

selectOptions(), deselectOptions()

selectOptions(
  element: Element,
  values: HTMLElement | HTMLElement[] | string[] | string,
): Promise<void>
deselectOptions(
  element: Element,
  values: HTMLElement | HTMLElement[] | string[] | string,
): Promise<void>

Sélectionne/désélectionne les options spécifiées dans un HTMLSelectElement ou une listbox.

Le paramètre values peut référencer une option par sa valeur, son contenu HTML ou simplement fournir l'élément. Il accepte également un tableau de ces valeurs.

La sélection multiple et/ou la désélection d'options d'un HTMLSelectElement n'est possible que si l'attribut multiple est spécifié.

test('selectOptions', async () => {
  const user = userEvent.setup()

  render(
    <select multiple>
      <option value="1">A</option>
      <option value="2">B</option>
      <option value="3">C</option>
    </select>,
  )

  await user.selectOptions(screen.getByRole('listbox'), ['1', 'C'])

  expect(screen.getByRole('option', {name: 'A'}).selected).toBe(true)
  expect(screen.getByRole('option', {name: 'B'}).selected).toBe(false)
  expect(screen.getByRole('option', {name: 'C'}).selected).toBe(true)
})

test('deselectOptions', async () => {
  const user = userEvent.setup()

  render(
    <select multiple>
      <option value="1">A</option>
      <option value="2" selected>
        B
      </option>
      <option value="3">C</option>
    </select>,
  )

  await user.deselectOptions(screen.getByRole('listbox'), '2')

  expect(screen.getByText('B').selected).toBe(false)
})

Notez que cette API déclenche des événements de pointeur et est donc soumise à la vérification pointerEventsCheck.

type()

type(
  element: Element,
  text: KeyboardInput,
  options?: {
    skipClick?: boolean
    skipAutoClose?: boolean
    initialSelectionStart?: number
    initialSelectionEnd?: number
  }
): Promise<void>

Saisit du texte dans un élément d'entrée.

Utilisez keyboard() si vous souhaitez simplement simuler l'appui de touches clavier.
Utilisez type() si vous voulez simplement insérer commodément du texte dans un champ de saisie ou une zone de texte.

1. Clique sur l'élément sauf si skipClick est true.

2. Si initialSelectionStart est défini, positionne la sélection sur l'élément. Si initialSelectionEnd n'est pas défini, cela crée une sélection réduite à un point.

3. Saisit le text donné via keyboard().

4. Relâche toutes les touches pressées sauf si skipAutoClose est true.

test('type into an input field', async () => {
  const user = userEvent.setup()

  render(<input defaultValue="Hello," />)
  const input = screen.getByRole('textbox')

  await user.type(input, ' World!')

  expect(input).toHaveValue('Hello, World!')
})

upload()

upload(
  element: HTMLElement,
  fileOrFiles: File | File[],
): Promise<void>

Modifie un champ de fichier comme si l'utilisateur cliquait dessus et sélectionnait des fichiers dans la boîte de dialogue d'import qui s'affiche.

Les fichiers incompatibles avec la propriété accept seront automatiquement rejetés, sauf si applyAccept est défini sur false.

test('upload file', async () => {
  const user = userEvent.setup()

  render(
    <div>
      <label htmlFor="file-uploader">Upload file:</label>
      <input id="file-uploader" type="file" />
    </div>,
  )
  const file = new File(['hello'], 'hello.png', {type: 'image/png'})
  const input = screen.getByLabelText(/upload file/i)

  await user.upload(input, file)

  expect(input.files[0]).toBe(file)
  expect(input.files.item(0)).toBe(file)
  expect(input.files).toHaveLength(1)
})

test('upload multiple files', async () => {
  const user = userEvent.setup()

  render(
    <div>
      <label htmlFor="file-uploader">Upload file:</label>
      <input id="file-uploader" type="file" multiple />
    </div>,
  )
  const files = [
    new File(['hello'], 'hello.png', {type: 'image/png'}),
    new File(['there'], 'there.png', {type: 'image/png'}),
  ]
  const input = screen.getByLabelText(/upload file/i)

  await user.upload(input, files)

  expect(input.files).toHaveLength(2)
  expect(input.files[0]).toBe(files[0])
  expect(input.files[1]).toBe(files[1])
})