Emphasize most common uses of fireEvent

[nareshbhatia]

• @testing-library/dom version: 7.5.7
• Testing Framework and version: Jest 26.0.1
• DOM Environment: jsdom 16.2.2

Relevant code or config:

import React from 'react';
import { fireEvent, render } from '@testing-library/react';

describe('fireEvent', () => {
    test("fireEvent.click() works!", () => {
        const handleClick = (event: any) => {
            console.log('--->', event.button);
        };

        const { getByText } = render(
            <div onClick={handleClick}>
                Submit
            </div>
        );
        const element = getByText("Submit");

        // ------------------------------------------------
        // This fires only twice, for button=0 and button=1
        // ------------------------------------------------
        fireEvent.click(element, { button: 0 });
        fireEvent.click(element, { button: 1 });
        fireEvent.click(element, { button: 2 });
    });
});

What you did:

I was trying to right-click on an element in my test using fireEvent.click(element, { button: 2 }).

What happened:

No event was fired.

Reproduction:

Please see code above. The click handler is called only twice, with button=0 and button=1. It is not called with button=2.

Problem description:

fireEvent.click() does not work for right-click.

Also the docs are a bit confusing. They imply that for left-click use button=0 and for right-click use button=2. However according to MDN docs, 0 is no buttons, 1 is left button, 2 is right button - there is a mismatch. Please see below:

• 0 : No button or un-initialized
• 1 : Primary button (usually the left button)
• 2 : Secondary button (usually the right button)
• 4 : Auxilary button (usually the mouse wheel button or middle button)
• 8 : 4th button (typically the "Browser Back" button)
• 16 : 5th button (typically the "Browser Forward" button)

[eps1lon]

click events are usually not dispatched on middle or right mouse presses. You can observe this in https://jsbin.com/hexafikiza/edit?html,js,console,output. This follows the spec

[...] The click event type MUST be dispatched [...], when the user presses down and releases the primary pointer button [...]

The click event should only be fired for the primary pointer button (i.e., when button value is 0, buttons value is 1). Secondary buttons (like the middle or right button on a standard mouse) MUST NOT fire click events. See auxclick for a corresponding event that is associated with the non-primary buttons.

-- https://w3c.github.io/uievents/#event-type-click

That being said: You can still dispatch synthetic clicks and trigger the handler. React just does not register it: https://codesandbox.io/s/react-dispatch-synthetic-middle-mouse-button-l0u4g

Feel free to open an issue on the react repo if you have a use case for dispatching synthetic middle mouse clicks.

However according to MDN docs, 0 is no buttons, 1 is left button, 2 is right button - there is a mismatch.

button is for the button that triggered that event. buttons is a bitmap of all the buttons pressed during that event:

Note: Do not confuse this property with the MouseEvent.button property. The MouseEvent.buttons property indicates the state of buttons pressed during any kind of mouse event, while the MouseEvent.button property only guarantees the correct value for mouse events caused by pressing or releasing one or multiple buttons.

-- https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons

[nareshbhatia]

@eps1lon, thanks for the detailed explanation. Never knew that something like auxclick existed!

If my new understanding is correct, then I believe that the docs should be corrected:

// <button>Submit</button>
const rightClick = { button: 2 }
fireEvent.click(getByText('Submit'), rightClick)
// default `button` property for click events is set to `0` which is a left click.

[eps1lon]

If my new understanding is correct, then I believe that the docs should be corrected:

definitely. I think the docs should rather document a change event. For clicks you have Element.prototype.click which has less interop issues. And we should also start with fireEvent[eventName]. fireEvent(event) is less common. I think I only ever used it for polyfills in older browsers.

[shermanhui]

@eps1lon, @nickmccurdy I'd like to help out with this issue, but I need some clarification.

I've read through the thread and it looks like the original issue was that it wasn't clear that middle (1) and right (2) mouse click events don't dispatch a click event. I'm a little confused about that since it looks like in the OP { button: 1 } did trigger an event?

So is it my understanding that this piece of the documentation is incorrect:

// <button>Submit</button>
const rightClick = { button: 2 }
fireEvent.click(getByText('Submit'), rightClick)
// default `button` property for click events is set to `0` which is a left click.

Would it suffice to remove this example since (AFAIK) it doesn't work?

Lastly, could I get some more clarification on what is meant by the "most common uses" of fireEvent? Also just to double-check - the intention is to add more of these common uses under the fireEvent[eventName] section?

Thanks!