https://testing-library.com/assets/js/351e6773.c1780094.js

1"use strict";(self.webpackChunkreact_testing_library_docs=self.webpackChunkreact_testing_library_docs||[]).push([[9182],{3905:(t,e,n)=>{n.d(e,{Zo:()=>m,kt:()=>k});var a=n(7294);function r(t,e,n){return e in t?Object.defineProperty(t,e,{value:n,enumerable:!0,configurable:!0,writable:!0}):t[e]=n,t}function l(t,e){var n=Object.keys(t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(t);e&&(a=a.filter((function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable}))),n.push.apply(n,a)}return n}function i(t){for(var e=1;e<arguments.length;e++){var n=null!=arguments[e]?arguments[e]:{};e%2?l(Object(n),!0).forEach((function(e){r(t,e,n[e])})):Object.getOwnPropertyDescriptors?Object.defineProperties(t,Object.getOwnPropertyDescriptors(n)):l(Object(n)).forEach((function(e){Object.defineProperty(t,e,Object.getOwnPropertyDescriptor(n,e))}))}return t}function o(t,e){if(null==t)return{};var n,a,r=function(t,e){if(null==t)return{};var n,a,r={},l=Object.keys(t);for(a=0;a<l.length;a++)n=l[a],e.indexOf(n)>=0||(r[n]=t[n]);return r}(t,e);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(t);for(a=0;a<l.length;a++)n=l[a],e.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(t,n)&&(r[n]=t[n])}return r}var p=a.createContext({}),u=function(t){var e=a.useContext(p),n=e;return t&&(n="function"==typeof t?t(e):i(i({},e),t)),n},m=function(t){var e=u(t.components);return a.createElement(p.Provider,{value:e},t.children)},d={inlineCode:"code",wrapper:function(t){var e=t.children;return a.createElement(a.Fragment,{},e)}},s=a.forwardRef((function(t,e){var n=t.components,r=t.mdxType,l=t.originalType,p=t.parentName,m=o(t,["components","mdxType","originalType","parentName"]),s=u(n),k=r,g=s["".concat(p,".").concat(k)]||s[k]||d[k]||l;return n?a.createElement(g,i(i({ref:e},m),{},{components:n})):a.createElement(g,i({ref:e},m))}));function k(t,e){var n=arguments,r=e&&e.mdxType;if("string"==typeof t||r){var l=n.length,i=new Array(l);i[0]=s;var o={};for(var p in e)hasOwnProperty.call(e,p)&&(o[p]=e[p]);o.originalType=t,o.mdxType="string"==typeof t?t:r,i[1]=o;for(var u=2;u<l;u++)i[u]=n[u];return a.createElement.apply(null,i)}return a.createElement.apply(null,n)}s.displayName="MDXCreateElement"},610:(t,e,n)=>{n.r(e),n.d(e,{assets:()=>m,contentTitle:()=>p,default:()=>k,frontMatter:()=>o,metadata:()=>u,toc:()=>d});var a=n(7462),r=n(3366),l=(n(7294),n(3905)),i=["components"],o={id:"cheatsheet",title:"Cheatsheet"},p=void 0,u={unversionedId:"vue-testing-library/cheatsheet",id:"vue-testing-library/cheatsheet",title:"Cheatsheet",description:"A short guide to all the exported functions in Vue Testing Library.",source:"@site/docs/vue-testing-library/cheatsheet.mdx",sourceDirName:"vue-testing-library",slug:"/vue-testing-library/cheatsheet",permalink:"/docs/vue-testing-library/cheatsheet",draft:!1,editUrl:"https://github.com/testing-library/testing-library-docs/edit/main/docs/vue-testing-library/cheatsheet.mdx",tags:[],version:"current",lastUpdatedBy:"Nick McCurdy",lastUpdatedAt:1626907098,formattedLastUpdatedAt:"Jul 21, 2021",frontMatter:{id:"cheatsheet",title:"Cheatsheet"},sidebar:"docs",previous:{title:"FAQ",permalink:"/docs/vue-testing-library/faq"},next:{title:"Introduction",permalink:"/docs/angular-testing-library/intro"}},m={},d=[{value:"Queries",id:"queries",level:2},{value:"Search variants",id:"search-variants",level:3},{value:"Search types",id:"search-types",level:3},{value:"An example",id:"an-example",level:3},{value:"Async utilities",id:"async-utilities",level:2},{value:"Firing events",id:"firing-events",level:2},{value:"Other",id:"other",level:2},{value:"Text Match Options",id:"text-match-options",level:2}],s={toc:d};function k(t){var e=t.components,n=(0,r.Z)(t,i);return(0,l.kt)("wrapper",(0,a.Z)({},s,n,{components:e,mdxType:"MDXLayout"}),(0,l.kt)("p",null,"A short guide to all the exported functions in ",(0,l.kt)("inlineCode",{parentName:"p"},"Vue Testing Library"),"."),(0,l.kt)("h2",{id:"queries"},"Queries"),(0,l.kt)("blockquote",null,(0,l.kt)("p",{parentName:"blockquote"},(0,l.kt)("strong",{parentName:"p"},"Difference from DOM Testing Library")),(0,l.kt)("p",{parentName:"blockquote"},"The queries returned from ",(0,l.kt)("inlineCode",{parentName:"p"},"render")," in ",(0,l.kt)("inlineCode",{parentName:"p"},"Vue Testing Library")," are the same as\n",(0,l.kt)("inlineCode",{parentName:"p"},"DOM Testing Library"),". Yet, they have the first argument bound to the\ndocument, so instead of ",(0,l.kt)("inlineCode",{parentName:"p"},"getByText(node, 'text')")," you write\n",(0,l.kt)("inlineCode",{parentName:"p"},"getByText('text')"),".")),(0,l.kt)("h3",{id:"search-variants"},"Search variants"),(0,l.kt)("table",null,(0,l.kt)("thead",{parentName:"table"},(0,l.kt)("tr",{parentName:"thead"},(0,l.kt)("th",{parentName:"tr",align:null}),(0,l.kt)("th",{parentName:"tr",align:null},"Return if no match"),(0,l.kt)("th",{parentName:"tr",align:null},"Return if 1 match"),(0,l.kt)("th",{parentName:"tr",align:null},"Return if 1+ match"),(0,l.kt)("th",{parentName:"tr",align:null},"Await?"))),(0,l.kt)("tbody",{parentName:"table"},(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"getBy...")),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"return"),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"No")),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"findBy...")),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"return"),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"Yes")),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"queryBy...")),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},"null")),(0,l.kt)("td",{parentName:"tr",align:null},"return"),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"No")),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"getAllBy...")),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"array"),(0,l.kt)("td",{parentName:"tr",align:null},"array"),(0,l.kt)("td",{parentName:"tr",align:null},"No")),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"findAllBy...")),(0,l.kt)("td",{parentName:"tr",align:null},"throw"),(0,l.kt)("td",{parentName:"tr",align:null},"array"),(0,l.kt)("td",{parentName:"tr",align:null},"array"),(0,l.kt)("td",{parentName:"tr",align:null},"Yes")),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"queryAllBy...")),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},"[]")),(0,l.kt)("td",{parentName:"tr",align:null},"array"),(0,l.kt)("td",{parentName:"tr",align:null},"array"),(0,l.kt)("td",{parentName:"tr",align:null},"No")))),(0,l.kt)("h3",{id:"search-types"},"Search types"),(0,l.kt)("table",null,(0,l.kt)("thead",{parentName:"table"},(0,l.kt)("tr",{parentName:"thead"},(0,l.kt)("th",{parentName:"tr",align:null}),(0,l.kt)("th",{parentName:"tr",align:null},"finds by..."),(0,l.kt)("th",{parentName:"tr",align:null},"DOM example"))),(0,l.kt)("tbody",{parentName:"table"},(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByLabelText")),(0,l.kt)("td",{parentName:"tr",align:null},"label or aria-label content"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},'<label for="element" />'))),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByPlaceholderText")),(0,l.kt)("td",{parentName:"tr",align:null},"input placeholder value"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},'<input placeholder="name" />'))),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByText")),(0,l.kt)("td",{parentName:"tr",align:null},"element text content"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},"<p>Lorem ipsum</p>"))),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByDisplayValue")),(0,l.kt)("td",{parentName:"tr",align:null},"form element current value"),(0,l.kt)("td",{parentName:"tr",align:null},"Current value of input element")),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByAltText")),(0,l.kt)("td",{parentName:"tr",align:null},"img alt attribute"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},'<img alt="movie poster" />'))),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByTitle")),(0,l.kt)("td",{parentName:"tr",align:null}

1,"title attribute or svg title tag"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},'<span title="Add" />')," or ",(0,l.kt)("inlineCode",{parentName:"td"},"<title />"))),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByRole")),(0,l.kt)("td",{parentName:"tr",align:null},"ARIA role"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},'<div role="dialog" />'))),(0,l.kt)("tr",{parentName:"tbody"},(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("strong",{parentName:"td"},"...ByTestId")),(0,l.kt)("td",{parentName:"tr",align:null},"data-testid attribute"),(0,l.kt)("td",{parentName:"tr",align:null},(0,l.kt)("inlineCode",{parentName:"td"},'<div data-testid="some-message" />'))))),(0,l.kt)("blockquote",null,(0,l.kt)("p",{parentName:"blockquote"},"You can write any combination of Search variants and Search types.")),(0,l.kt)("h3",{id:"an-example"},"An example"),(0,l.kt)("p",null,(0,l.kt)("inlineCode",{parentName:"p"},"getByLabelText('Username')")," will search for a ",(0,l.kt)("inlineCode",{parentName:"p"},"<label>"),' element that contains\nthe string "Username", and will return the associated ',(0,l.kt)("inlineCode",{parentName:"p"},"input"),". In case of not\nfinding any, or finding more than one, it will throw an error."),(0,l.kt)("p",null,(0,l.kt)("inlineCode",{parentName:"p"},"queryAllByRole('nav')")," will synchronously look for all elements with a\n",(0,l.kt)("inlineCode",{parentName:"p"},'role="nav"')," attribute, and return an array with the results (or an empty array\nif no results were found)."),(0,l.kt)("p",null,"For more information, see\n",(0,l.kt)("a",{parentName:"p",href:"/docs/queries/about#priority"},"Which query should I use?"),"."),(0,l.kt)("h2",{id:"async-utilities"},"Async utilities"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"waitFor")," (Promise) retry function within until it stops throwing or times\nout."),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"waitForElement")," (Promise) retry function or array of functions and return\nthe result."),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"findBy")," and ",(0,l.kt)("inlineCode",{parentName:"li"},"findAllBy")," queries are async and retry until either a timeout or\nif the query returns successfully; they wrap ",(0,l.kt)("inlineCode",{parentName:"li"},"waitForElement"),".")),(0,l.kt)("p",null,"For more information, see\n",(0,l.kt)("a",{parentName:"p",href:"/docs/dom-testing-library/api-async"},"DOM Testing Library Async API"),"."),(0,l.kt)("blockquote",null,(0,l.kt)("p",{parentName:"blockquote"},"Remember to ",(0,l.kt)("inlineCode",{parentName:"p"},"await")," or ",(0,l.kt)("inlineCode",{parentName:"p"},".then()")," the result of async functions in your tests!")),(0,l.kt)("h2",{id:"firing-events"},"Firing events"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"fireEvent()")," trigger DOM event: ",(0,l.kt)("inlineCode",{parentName:"li"},"fireEvent(node, event)")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"fireEvent.","*")," helpers for default event types",(0,l.kt)("ul",{parentName:"li"},(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"click")," ",(0,l.kt)("inlineCode",{parentName:"li"},"fireEvent.click(node)")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"input")," ",(0,l.kt)("inlineCode",{parentName:"li"},"fireEvent.input(node, event)")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("a",{parentName:"li",href:"https://github.com/testing-library/dom-testing-library/blob/master/src/event-map.js"},"See all supported events"))))),(0,l.kt)("p",null,"For more information, see ",(0,l.kt)("a",{parentName:"p",href:"/docs/dom-testing-library/api-events"},"Events API")),(0,l.kt)("blockquote",null,(0,l.kt)("p",{parentName:"blockquote"},(0,l.kt)("strong",{parentName:"p"},"Difference from DOM Testing Library")),(0,l.kt)("p",{parentName:"blockquote"},"The events returned from ",(0,l.kt)("inlineCode",{parentName:"p"},"Vue Testing Library")," are all async, so you should\n",(0,l.kt)("inlineCode",{parentName:"p"},"await")," or ",(0,l.kt)("inlineCode",{parentName:"p"},"then()")," the result."),(0,l.kt)("p",{parentName:"blockquote"},"VTL also exposes ",(0,l.kt)("inlineCode",{parentName:"p"},"fireEvent.update(node, value)")," event to deal with ",(0,l.kt)("inlineCode",{parentName:"p"},"v-model"),".\nSee ",(0,l.kt)("a",{parentName:"p",href:"/docs/vue-testing-library/api#updateelem-value"},"the API")," for more details.")),(0,l.kt)("h2",{id:"other"},"Other"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"within(node)")," takes a node and returns an object with all the queries bound\nto it: ",(0,l.kt)("inlineCode",{parentName:"li"},'within(getByTestId("global-header")).getByText("hello")'),"."),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("strong",{parentName:"li"},"configure(config)")," change global options:\n",(0,l.kt)("inlineCode",{parentName:"li"},"configure({testIdAttribute: 'my-test-id'})"),".")),(0,l.kt)("p",null,"For more information, see\n",(0,l.kt)("a",{parentName:"p",href:"/docs/dom-testing-library/api-within"},"Querying Within Elements")," and\n",(0,l.kt)("a",{parentName:"p",href:"/docs/dom-testing-library/api-configuration"},"Config API"),"."),(0,l.kt)("h2",{id:"text-match-options"},"Text Match Options"),(0,l.kt)("p",null,"Given the following HTML:"),(0,l.kt)("pre",null,(0,l.kt)("c

1ode",{parentName:"pre",className:"language-html"},"<div>Hello World</div>\n")),(0,l.kt)("p",null,"All these matchers ",(0,l.kt)("strong",{parentName:"p"},"will find the element:")),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-javascript"},"// Matching a string:\ngetByText('Hello World') // full string match\ngetByText('llo Worl', {exact: false}) // substring match\ngetByText('hello world', {exact: false}) // ignore case\n\n// Matching a regex:\ngetByText(/World/) // substring match\ngetByText(/world/i) // substring match, ignore case\ngetByText(/^hello world$/i) // full string match, ignore case\ngetByText(/Hello W?oRlD/i) // advanced regex\n\n// Matching with a custom function:\ngetByText((content, element) => content.startsWith('Hello'))\n")))}k.isMDXComponent=!0}}]);