feat: add toggleSelectOptions (#252)

* implement without test

* feat: support toggleOptions with tests

* fix: type definition for toggleOptions

* docs: add toggleOptions example

* fix: test coverage

* docs: fix README

* fix: avoid testid in docs and test

README.md

@@ -59,6 +59,7 @@ change the state of the checkbox.
   - [`upload(element, file, [{ clickInit, changeInit }])`](#uploadelement-file--clickinit-changeinit-)
   - [`clear(element)`](#clearelement)
   - [`selectOptions(element, values)`](#selectoptionselement-values)
+  - [`toggleSelectOptions(element, values)`](#toggleselectoptionselement-values)
   - [`tab({shift, focusTrap})`](#tabshift-focustrap)
 - [Issues](#issues)
   - [🐛 Bugs](#-bugs)
@@ -308,6 +309,38 @@ userEvent.selectOptions(screen.getByTestId('select-multiple'), [
 ])
 ```
 
+### `toggleSelectOptions(element, values)`
+
+Toggle the specified option(s) of a `<select multiple>` element.
+
+```jsx
+import * as React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+test('toggleSelectOptions', () => {
+  render(
+    <select multiple>
+      <option value="1">A</option>
+      <option value="2">B</option>
+      <option value="3">C</option>
+    </select>,
+  )
+
+  userEvent.toggleSelectOptions(screen.getByRole('listbox'), ['1', '3'])
+
+  expect(screen.getByText('A').selected).toBe(true)
+  expect(screen.getByText('C').selected).toBe(true)
+
+  userEvent.toggleSelectOptions(screen.getByRole('listbox'), ['1'])
+
+  expect(screen.getByText('A').selected).toBe(false)
+})
+```
+
+The `values` parameter can be either an array of values or a singular scalar
+value.
+
 ### `tab({shift, focusTrap})`
 
 Fires a tab event changing the document.activeElement in the same way the

src/__tests__/dblclick.js

@@ -205,15 +205,16 @@ test('should not blur when mousedown prevents default', () => {
   ])
 })
 
-
 it('should fire mouse events with the correct properties', () => {
   const events = []
-  const eventsHandler = jest.fn(evt => events.push({
-    type: evt.type,
-    button: evt.button,
-    buttons: evt.buttons,
-    detail: evt.detail
-  }))
+  const eventsHandler = jest.fn(evt =>
+    events.push({
+      type: evt.type,
+      button: evt.button,
+      buttons: evt.buttons,
+      detail: evt.detail,
+    }),
+  )
   render(
     <div
       data-testid="div"
@@ -233,68 +234,70 @@ it('should fire mouse events with the correct properties', () => {
       type: 'mouseover',
       button: 0,
       buttons: 0,
-      detail: 0
+      detail: 0,
     },
     {
       type: 'mousemove',
       button: 0,
       buttons: 0,
-      detail: 0
+      detail: 0,
     },
     {
       type: 'mousedown',
       button: 0,
       buttons: 1,
-      detail: 1
+      detail: 1,
     },
     {
       type: 'mouseup',
       button: 0,
       buttons: 1,
-      detail: 1
+      detail: 1,
     },
     {
       type: 'click',
       button: 0,
       buttons: 1,
-      detail: 1
+      detail: 1,
     },
     {
       type: 'mousedown',
       button: 0,
       buttons: 1,
-      detail: 2
+      detail: 2,
     },
     {
       type: 'mouseup',
       button: 0,
       buttons: 1,
-      detail: 2
+      detail: 2,
     },
     {
       type: 'click',
       button: 0,
       buttons: 1,
-      detail: 2
+      detail: 2,
     },
     {
       type: 'dblclick',
       button: 0,
       buttons: 1,
-      detail: 2
+      detail: 2,
     },
   ])
 })
 
 it('should fire mouse events with custom button property', () => {
   const events = []
-  const eventsHandler = jest.fn(evt => events.push({
-    type: evt.type,
-    button: evt.button,
-    buttons: evt.buttons,
-    detail: evt.detail,
-    altKey: evt.altKey
-  }))
+  const eventsHandler = jest.fn(evt =>
+    events.push({
+      type: evt.type,
+      button: evt.button,
+      buttons: evt.buttons,
+      detail: evt.detail,
+      altKey: evt.altKey,
+    }),
+  )
   render(
     <div
       data-testid="div"
@@ -310,7 +313,7 @@ it('should fire mouse events with custom button property', () => {
 
   userEvent.dblClick(screen.getByTestId('div'), {
     button: 1,
-    altKey: true
+    altKey: true,
   })
 
   expect(events).toEqual([
@@ -319,75 +322,77 @@ it('should fire mouse events with custom button property', () => {
       button: 0,
       buttons: 0,
       detail: 0,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'mousemove',
       button: 0,
       buttons: 0,
       detail: 0,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'mousedown',
       button: 1,
       buttons: 4,
       detail: 1,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'mouseup',
       button: 1,
       buttons: 4,
       detail: 1,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'click',
       button: 1,
       buttons: 4,
       detail: 1,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'mousedown',
       button: 1,
       buttons: 4,
       detail: 2,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'mouseup',
       button: 1,
       buttons: 4,
       detail: 2,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'click',
       button: 1,
       buttons: 4,
       detail: 2,
-      altKey: true
+      altKey: true,
     },
     {
       type: 'dblclick',
       button: 1,
       buttons: 4,
       detail: 2,
-      altKey: true
+      altKey: true,
     },
   ])
 })
 
 it('should fire mouse events with custom buttons property', () => {
   const events = []
-  const eventsHandler = jest.fn(evt => events.push({
-    type: evt.type,
-    button: evt.button,
-    buttons: evt.buttons,
-    detail: evt.detail
-  }))
+  const eventsHandler = jest.fn(evt =>
+    events.push({
+      type: evt.type,
+      button: evt.button,
+      buttons: evt.buttons,
+      detail: evt.detail,
+    }),
+  )
   render(
     <div
       data-testid="div"
@@ -402,63 +407,63 @@ it('should fire mouse events with custom buttons property', () => {
   )
 
   userEvent.dblClick(screen.getByTestId('div'), {
-    buttons: 4
+    buttons: 4,
   })
 
   expect(events).toEqual([
     {
       type: 'mouseover',
       button: 0,
       buttons: 0,
-      detail: 0
+      detail: 0,
     },
     {
       type: 'mousemove',
       button: 0,
       buttons: 0,
-      detail: 0
+      detail: 0,
     },
     {
       type: 'mousedown',
       button: 1,
       buttons: 4,
-      detail: 1
+      detail: 1,
     },
     {
       type: 'mouseup',
       button: 1,
       buttons: 4,
-      detail: 1
+      detail: 1,
     },
     {
       type: 'click',
       button: 1,
       buttons: 4,
-      detail: 1
+      detail: 1,
     },
     {
       type: 'mousedown',
       button: 1,
       buttons: 4,
-      detail: 2
+      detail: 2,
     },
     {
       type: 'mouseup',
       button: 1,
       buttons: 4,
-      detail: 2
+      detail: 2,
     },
     {
       type: 'click',
       button: 1,
       buttons: 4,
-      detail: 2
+      detail: 2,
     },
     {
       type: 'dblclick',
       button: 1,
       buttons: 4,
-      detail: 2
+      detail: 2,
     },
   ])
 })

src/__tests__/helpers/utils.js

@@ -181,4 +181,4 @@ afterEach(() => {
   eventListeners = []
 })
 
-export {setup, addEventListener}
+export {setup, addEventListener, addListeners}