callstack__react-native-testing-library/static/js/async/7340.0fd67f37f1.js

"use strict";(self.rspackChunkwebsite=self.rspackChunkwebsite||[]).push([["7340"],{1511(e,s,n){n.r(s),n.d(s,{default:()=>l});var r=n(4848),i=n(8453);function o(e){let s={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",span:"span",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(s.h1,{id:"async-events",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#async-events",children:"#"}),"Async Events"]}),"\n",(0,r.jsxs)(s.h2,{id:"summary",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#summary",children:"#"}),"Summary"]}),"\n",(0,r.jsxs)(s.p,{children:["In RNTL v14, all tests are async since ",(0,r.jsx)(s.code,{children:"render()"}),", ",(0,r.jsx)(s.code,{children:"fireEvent()"}),", and other core APIs return Promises. Beyond the basic async APIs, there are additional async utilities for handling events that complete over time:"]}),"\n",(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"Waiting for elements to appear"}),": Use ",(0,r.jsx)(s.code,{children:"findBy*"})," queries when elements appear after some delay (e.g., after data fetching)."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"Waiting for conditions"}),": Use ",(0,r.jsx)(s.code,{children:"waitFor()"})," to wait for arbitrary conditions to be met."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"Waiting for elements to disappear"}),": Use ",(0,r.jsx)(s.code,{children:"waitForElementToBeRemoved()"})," when elements should be removed after some action."]}),"\n"]}),"\n",(0,r.jsx)(s.p,{children:"These utilities help you write reliable tests that properly handle timing in your application."}),"\n",(0,r.jsxs)(s.h3,{id:"example",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#example",children:"#"}),"Example"]}),"\n",(0,r.jsx)(s.p,{children:"Consider a test for a user signing in with correct credentials:"}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"javascript",children:(0,r.jsxs)(s.code,{children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"test"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'User can sign in with correct credentials'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:" async"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" () "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"=>"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" {"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"  // Typical test setup"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"  const"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" user"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:" ="}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" userEvent"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".setup"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"();"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"  await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" render"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"(<"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"App"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" />);"})]}),"\n",(0,r.jsx)(s.span,{className:"line"}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"  // No need to use async here, components are already rendered"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expect"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".getByRole"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'header'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" { name"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'Sign in to Hello World App!'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" }))"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".toBeOnTheScreen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"();"})]}),"\n",(0,r.jsx)(s.span,{className:"line"}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"  // Using await as User Event requires it"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"  await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" user"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".type"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".getByLabelText"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'Username'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:")"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'admin'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:");"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"  await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" user"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".type"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".getByLabelText"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'Password'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:")"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'admin1'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:");"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"  await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" user"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".press"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".getByRole"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'button'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" { name"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'Sign In'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" }));"})]}),"\n",(0,r.jsx)(s.span,{className:"line"}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"  // Using await as sign in operation is asynchronous"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expect"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".findByRole"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'header'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" { name"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'Welcome admin!'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" }))"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".toBeOnTheScreen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"();"})]}),"\n",(0,r.jsx)(s.span,{className:"line"}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"  // Follow-up assertions do not need to be async, as we already waited for sign in operation to complete"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expect"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"    screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".queryByRole"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'header'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" { name"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'Sign in to Hello World App'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" })"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  )."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"not"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".toBeOnTheScreen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"();"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expect"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".queryByLabelText"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'Username'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"))."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"not"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".toBeOnTheScreen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"();"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expect"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".queryByLabelText"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'Password'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"))."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"not"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".toBeOnTheScreen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"();"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"});"})})]})})}),"\n",(0,r.jsxs)(s.h2,{id:"async-utilities",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#async-utilities",children:"#"}),"Async utilities"]}),"\n",(0,r.jsx)(s.p,{children:"There are several asynchronous utilities you might use in your tests."}),"\n",(0,r.jsxs)(s.h3,{id:"findby-queries",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#findby-queries",children:"#"}),(0,r.jsx)(s.code,{children:"findBy*"})," queries"]}),"\n",(0,r.jsxs)(s.p,{children:["The most common are the ",(0,r.jsxs)(s.a,{href:"/docs/api/queries.html#find-by",children:[(0,r.jsx)(s.code,{children:"findBy*"})," queries"]}),". These are useful when waiting for a matching element to appear. They can be understood as a ",(0,r.jsxs)(s.a,{href:"/docs/api/queries.html#get-by",children:[(0,r.jsx)(s.code,{children:"getBy*"})," queries"]})," used in conjunction with a ",(0,r.jsxs)(s.a,{href:"/docs/api/misc/async.html#waitfor",children:[(0,r.jsx)(s.code,{children:"waitFor"})," function"]}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["They accept the same predicates as ",(0,r.jsx)(s.code,{children:"getBy*"})," queries like ",(0,r.jsx)(s.code,{children:"findByRole"}),", ",(0,r.jsx)(s.code,{children:"findByTest"}),", etc. They also have a multiple elements variant called ",(0,r.jsx)(s.a,{href:"/docs/api/queries.html#find-all-by",children:(0,r.jsx)(s.code,{children:"findAllBy*"})}),"."]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsxs)(s.code,{children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"function"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" findByRole"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:": ("})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  role"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" TextMatch"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  queryOptions"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"?:"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" {"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"    // Query specific options"})}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  }"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  waitForOptions"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"?:"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" {"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"    timeout"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"?:"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" number"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:";"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"    interval"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"?:"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" number"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:";"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"    // .."})}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  }"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:")"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" Promise"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"<"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"TestInstance"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:">;"})]})]})})}),"\n",(0,r.jsxs)(s.p,{children:["Each query has a default ",(0,r.jsx)(s.code,{children:"timeout"})," value of 1000 ms and a default ",(0,r.jsx)(s.code,{children:"interval"})," of 50 ms. Custom timeout and check intervals can be specified if needed, as shown below:"]}),"\n",(0,r.jsxs)(s.h4,{id:"example-1",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#example-1",children:"#"}),"Example"]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsxs)(s.code,{children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"const"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" button"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:" ="}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:" await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" screen"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".findByRole"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"  'button'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  { name"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:" 'Start'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" }"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  { timeout"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" 1000"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" interval"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" 50"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" }"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:");"})})]})})}),"\n",(0,r.jsxs)(s.p,{children:["Alternatively, a default global ",(0,r.jsx)(s.code,{children:"timeout"})," value can be set using the ",(0,r.jsxs)(s.a,{href:"/docs/api/misc/config.html#configure",children:[(0,r.jsx)(s.code,{children:"configure"})," function"]}),":"]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsx)(s.code,{children:(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"configure"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"({ asyncUtilTimeout"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" timeout });"})]})})})}),"\n",(0,r.jsxs)(s.h3,{id:"waitfor-function",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#waitfor-function",children:"#"}),(0,r.jsx)(s.code,{children:"waitFor"})," function"]}),"\n",(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"waitFor"})," function is another option, serving as a lower-level utility in more advanced cases."]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsxs)(s.code,{children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"function"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" waitFor"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"<"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"T"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:">("})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expectation"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" () "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"=>"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" T"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  options"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"?:"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" {"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"    timeout"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" number"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:";"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"    interval"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" number"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:";"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  }"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:")"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" Promise"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"<"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"T"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:">;"})]})]})})}),"\n",(0,r.jsxs)(s.p,{children:["It accepts an ",(0,r.jsx)(s.code,{children:"expectation"})," to be validated and repeats the check every defined interval until it no longer throws an error. Similarly to ",(0,r.jsx)(s.code,{children:"findBy*"})," queries they accept ",(0,r.jsx)(s.code,{children:"timeout"})," and ",(0,r.jsx)(s.code,{children:"interval"})," options and have the same default values of 1000ms for timeout, and a checking interval of 50 ms."]}),"\n",(0,r.jsxs)(s.h4,{id:"example-2",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#example-2",children:"#"}),"Example"]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsx)(s.code,{children:(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" waitFor"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"(() "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"=>"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" expect"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"(mockAPI)"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".toHaveBeenCalledTimes"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"1"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"));"})]})})})}),"\n",(0,r.jsxs)(s.p,{children:["If you want to use it with ",(0,r.jsx)(s.code,{children:"getBy*"})," queries, use the ",(0,r.jsx)(s.code,{children:"findBy*"})," queries instead, as they essentially do the same, but offer better developer experience."]}),"\n",(0,r.jsxs)(s.h3,{id:"waitforelementtoberemoved-function",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#waitforelementtoberemoved-function",children:"#"}),(0,r.jsx)(s.code,{children:"waitForElementToBeRemoved"})," function"]}),"\n",(0,r.jsxs)(s.p,{children:["A specialized function, ",(0,r.jsx)(s.a,{href:"/docs/api/misc/async.html#waitforelementtoberemoved",children:(0,r.jsx)(s.code,{children:"waitForElementToBeRemoved"})}),", is used to verify that a matching element was present but has since been removed."]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsxs)(s.code,{children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"function"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" waitForElementToBeRemoved"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"<"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"T"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:">("})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"  expectation"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" () "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"=>"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" T"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  options"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"?:"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:" {"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"    timeout"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" number"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:";"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"    interval"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:" number"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:";"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"  }"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:")"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" Promise"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"<"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"T"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"> {}"})]})]})})}),"\n",(0,r.jsxs)(s.p,{children:["This function is, in a way, the negation of ",(0,r.jsx)(s.code,{children:"waitFor"})," as it expects the initial expectation to be true (not throw an error), only to turn invalid (start throwing errors) on subsequent runs. It operates using the same ",(0,r.jsx)(s.code,{children:"timeout"})," and ",(0,r.jsx)(s.code,{children:"interval"})," parameters as ",(0,r.jsx)(s.code,{children:"findBy*"})," queries and ",(0,r.jsx)(s.code,{children:"waitFor"}),"."]}),"\n",(0,r.jsxs)(s.h4,{id:"example-3",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#example-3",children:"#"}),"Example"]}),"\n",(0,r.jsx)(r.Fragment,{children:(0,r.jsx)(s.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"typescript",children:(0,r.jsx)(s.code,{children:(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"await"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" waitForElementToBeRemoved"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"(() "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"=>"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:" getByText"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'Hello World'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-foreground)"},children:"));"})]})})})}),"\n",(0,r.jsxs)(s.h2,{id:"fake-timers",children:[(0,r.jsx)(s.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#fake-timers",children:"#"}),"Fake Timers"]}),"\n",(0,r.jsxs)(s.p,{children:["Asynchronous tests can take long to execute due to the delays introduced by asynchronous operations. To mitigate this, fake timers can be used. These are particularly useful when delays are mere waits, such as the 130 milliseconds wait introduced by the UserEvent ",(0,r.jsx)(s.code,{children:"press()"})," event due to React Native runtime behavior or simulated 1000 wait in a API call mock. Fake timers allow for precise fast-forwarding through these wait periods."]}),"\n",(0,r.jsxs)(s.p,{children:["Here are the basics of using ",(0,r.jsx)(s.a,{href:"https://jestjs.io/docs/timer-mocks",rel:"noopener noreferrer",target:"_blank",children:"Jest fake timers"}),":"]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["Enable fake timers with: ",(0,r.jsx)(s.code,{children:"jest.useFakeTimers()"})]}),"\n",(0,r.jsxs)(s.li,{children:["Disable fake timers with: ",(0,r.jsx)(s.code,{children:"jest.useRealTimers()"})]}),"\n",(0,r.jsxs)(s.li,{children:["Advance fake timers forward with: ",(0,r.jsx)(s.code,{children:"jest.advanceTimersByTime(interval)"})]}),"\n",(0,r.jsxs)(s.li,{children:["Run ",(0,r.jsx)(s.strong,{children:"all timers"})," to completion with: ",(0,r.jsx)(s.code,{children:"jest.runAllTimers()"})]}),"\n",(0,r.jsxs)(s.li,{children:["Run ",(0,r.jsx)(s.strong,{children:"currently pending timers"})," to completion with: ",(0,r.jsx)(s.code,{children:"jest.runOnlyPendingTimers()"})]}),"\n"]}),"\n",(0,r.jsxs)(s.p,{children:["Be cautious when running all timers to completion as it might create an infinite loop if these timers schedule follow-up timers. In such cases, it's safer to use ",(0,r.jsx)(s.code,{children:"jest.runOnlyPendingTimers()"})," to avoid ending up in an infinite loop of scheduled tasks."]}),"\n",(0,r.jsxs)(s.p,{children:["You can use both built-in Jest fake timers, as well as ",(0,r.jsx)(s.a,{href:"https://sinonjs.org/releases/latest/fake-timers/",rel:"noopener noreferrer",target:"_blank",children:"Sinon.JS fake timers"}),"."]}),"\n",(0,r.jsx)(s.p,{children:"Note: you do not need to advance timers by hand when using User Event API, as it's automatically."})]})}function l(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},{wrapper:s}={...(0,i.R)(),...e.components};return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(o,{...e})}):o(e)}l.__RSPRESS_PAGE_META={},l.__RSPRESS_PAGE_META["14.x%2Fcookbook%2Fbasics%2Fasync-events.md"]={toc:[{id:"summary",text:"Summary",depth:2},{id:"example",text:"Example",depth:3},{id:"async-utilities",text:"Async utilities",depth:2},{id:"findby-queries",text:"`findBy*` queries",depth:3},{id:"example-1",text:"Example",depth:4},{id:"waitfor-function",text:"`waitFor` function",depth:3},{id:"example-2",text:"Example",depth:4},{id:"waitforelementtoberemoved-function",text:"`waitForElementToBeRemoved` function",depth:3},{id:"example-3",text:"Example",depth:4},{id:"fake-timers",text:"Fake Timers",depth:2}],title:"Async Events",headingTitle:"Async Events",frontmatter:{}}}}]);