1"use strict";(self.webpackChunkreact_testing_library_docs=self.webpackChunkreact_testing_library_docs||[]).push([[6668],{3905:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>m});var r=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?o(Object(n),!0).forEach((function(t){i(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):o(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function s(e,t){if(null==e)return{};var n,r,i=function(e,t){if(null==e)return{};var n,r,i={},o=Object.keys(e);for(r=0;r<o.length;r++)n=o[r],t.indexOf(n)>=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r<o.length;r++)n=o[r],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=r.createContext({}),c=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},u=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),d=c(n),m=i,f=d["".concat(l,".").concat(m)]||d[m]||p[m]||o;return n?r.createElement(f,a(a({ref:t},u),{},{components:n})):r.createElement(f,a({ref:t},u))}));function m(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,a=new Array(o);a[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,a[1]=s;for(var c=2;c<o;c++)a[c]=n[c];return r.createElement.apply(null,a)}return r.createElement.apply(null,n)}d.displayName="MDXCreateElement"},5059:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>u,contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>c,toc:()=>p});var r=n(7462),i=n(3366),o=(n(7294),n(3905)),a=["components"],s={id:"guide-events",title:"Considerations for fireEvent"},l=void 0,c={unversionedId:"guide-events",id:"guide-events",title:"Considerations for fireEvent",description:"Interactions vs. events",source:"@site/docs/guide-events.mdx",sourceDirName:".",slug:"/guide-events",permalink:"/docs/guide-events",draft:!1,editUrl:"https://github.com/testing-library/testing-library-docs/edit/main/docs/guide-events.mdx",tags:[],version:"current",lastUpdatedBy:"Philipp Fritsche",lastUpdatedAt:1648540280,formattedLastUpdatedAt:"Mar 29, 2022",frontMatter:{id:"guide-events",title:"Considerations for fireEvent"},sidebar:"docs",previous:{title:"Appearance and Disappearance",permalink:"/docs/guide-disappearance"},next:{title:"Using Fake Timers",permalink:"/docs/using-fake-timers"}},u={},p=[{value:"Interactions vs. events",id:"interactions-vs-events",level:2},{value:"Alternatives",id:"alternatives",level:2},{value:"Keydown",id:"keydown",level:3},{value:"Focus/Blur",id:"focusblur",level:3}],d={toc:p};function m(e){var t=e.components,n=(0,i.Z)(e,a);return(0,o.kt)("wrapper",(0,r.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h2",{id:"interactions-vs-events"},"Interactions vs. events"),(0,o.kt)("p",null,"Based on ",(0,o.kt)("a",{parentName:"p",href:"/docs/guiding-principles"},"the Guiding Principles"),", your test should\nresemble how users interact with your code (component, page, etc.) as much as\npossible. With this in mind, you should know that ",(0,o.kt)("inlineCode",{parentName:"p"},"fireEvent")," isn't ",(0,o.kt)("em",{parentName:"p"},"exactly"),"\nhow the user interacts with your application, but it's close enough for most\nscenarios."),(0,o.kt)("p",null,"Consider ",(0,o.kt)("inlineCode",{parentName:"p"},"fireEvent.click"),", which creates a click event and dispatches that\nevent on the given DOM node. This works properly for most situations when you\nsimply want to test what happens when your element is clicked, but when the\n",(0,o.kt)("em",{parentName:"p"},"user")," actually clicks your element, these are the events that are typically\nfired (in order):"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"fireEvent.mouseOver(element)"),(0,o.kt)("li",{parentName:"ul"},"fireEvent.mouseMove(element)"),(0,o.kt)("li",{parentName:"ul"},"fireEvent.mouseDown(element)"),(0,o.kt)("li",{parentName:"ul"},"element.focus() (if that element is focusable)"),(0,o.kt)("li",{parentName:"ul"},"fireEvent.mouseUp(element)"),(0,o.kt)("li",{parentName:"ul"},"fireEvent.click(element)")),(0,o.kt)("p",null,"And then, if that element happens to be a child of a ",(0,o.kt)("inlineCode",{parentName:"p"},"label"),", then it will also\nmove focus to the form control that the label is labeling. So even though all\nyou really are trying to test is the click handler, by simply using\n",(0,o.kt)("inlineCode",{parentName:"p"},"fireEvent.click")," you're missing out on several other potentially important\nevents the user is firing along the way."),(0,o.kt)("p",null,"Again, most of the time this isn't critical for your tests and the trade-off of\nsimply using ",(0,o.kt)("inlineCode",{parentName:"p"},"fireEvent.click")," is worth it."),(0,o.kt)("h2",{id:"alternatives"},"Alternatives"),(0,o.kt)("p",null,"We will describe a couple of simple adju
1stments to your tests that will increase\nyour confidence in the interactive behavior of your components. For other\ninteractions you may want to either consider using\n",(0,o.kt)("a",{parentName:"p",href:"/docs/user-event/intro"},(0,o.kt)("inlineCode",{parentName:"a"},"user-event"))," or testing your components in a real\nenvironment (e.g. manually, automatic with cypress, etc.)."),(0,o.kt)("h3",{id:"keydown"},"Keydown"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://w3c.github.io/uievents/#events-keyboard-event-order"},"A keydown is dispatched on the currently focused element, the body element or the document element"),".\nFollowing this you should prefer"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-diff"},"- fireEvent.keyDown(getByText('click me'));\n+ getByText('click me').focus();\n+ fireEvent.keyDown(document.activeElement || document.body);\n")),(0,o.kt)("p",null,"This will also test that the element in question can even receive keyboard\nevents."),(0,o.kt)("h3",{id:"focusblur"},"Focus/Blur"),(0,o.kt)("p",null,"If an element is focused, a focus event is dispatched, the active element in the\ndocument changes, and the previously focused element is blurred. To simulate\nthis behavior you can simply replace ",(0,o.kt)("inlineCode",{parentName:"p"},"fireEvent")," with imperative focus:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-diff"},"- fireEvent.focus(getByText('focus me'));\n+ getByText('focus me').focus();\n")),(0,o.kt)("p",null,"A nice side-effect of this approach is that any assertion on fired focus events\nwill fail if the element is not focusable. This is especially important if you\nfollow-up with a keydown event."))}m.isMDXComponent=!0}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.