|
|
|
|
"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[46677],{94379:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>s,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>a,toc:()=>c});var i=t(85893),l=t(11151);const o={},r="Locators",a={id:"guides/locators",title:"Locators",description:"Locators is a new, experimental API that combines the functionalities of",source:"@site/versioned_docs/version-21.6.1/guides/locators.md",sourceDirName:"guides",slug:"/guides/locators",permalink:"/guides/locators",draft:!1,unlisted:!1,tags:[],version:"21.6.1",frontMatter:{},sidebar:"docs",previous:{title:"Query Selectors",permalink:"/guides/query-selectors"},next:{title:"Evaluate JavaScript",permalink:"/guides/evaluate-javascript"}},s={},c=[{value:"Use cases",id:"use-cases",level:2},{value:"Waiting for an element",id:"waiting-for-an-element",level:3},{value:"Waiting for a function",id:"waiting-for-a-function",level:3},{value:"Clicking an element",id:"clicking-an-element",level:3},{value:"Clicking an element matching a criteria",id:"clicking-an-element-matching-a-criteria",level:3},{value:"Filling out an input",id:"filling-out-an-input",level:3},{value:"Retrieving an element property",id:"retrieving-an-element-property",level:3},{value:"Hover over an element",id:"hover-over-an-element",level:3},{value:"Scroll an element",id:"scroll-an-element",level:3},{value:"Configuring locators",id:"configuring-locators",level:2},{value:"Getting locator events",id:"getting-locator-events",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",ul:"ul",...(0,l.a)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.h1,{id:"locators",children:"Locators"}),"\n",(0,i.jsx)(n.p,{children:"Locators is a new, experimental API that combines the functionalities of\nwaiting and actions. With additional precondition checks, it\nenables automatic retries for failed actions, resulting in more reliable and\nless flaky automation scripts."}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsx)(n.p,{children:"Locators API is experimental and we will not follow semver for breaking changes\nin the Locators API."})}),"\n",(0,i.jsx)(n.h2,{id:"use-cases",children:"Use cases"}),"\n",(0,i.jsx)(n.h3,{id:"waiting-for-an-element",children:"Waiting for an element"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page.locator('button').wait();\n"})}),"\n",(0,i.jsx)(n.p,{children:"The following preconditions are automatically checked:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Waits for the element to become\n",(0,i.jsx)(n.a,{href:"https://pptr.dev/api/puppeteer.elementhandle.isvisible/",children:"visible"})," or hidden."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"waiting-for-a-function",children:"Waiting for a function"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page\n .locator(() => {\n let resolve!: (node: HTMLCanvasElement) => void;\n const promise = new Promise(res => {\n return (resolve = res);\n });\n const observer = new MutationObserver(records => {\n for (const record of records) {\n if (record.target instanceof HTMLCanvasElement) {\n resolve(record.target);\n }\n }\n });\n observer.observe(document);\n return promise;\n })\n .wait();\n"})}),"\n",(0,i.jsx)(n.h3,{id:"clicking-an-element",children:"Clicking an element"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page.locator('button').click();\n"})}),"\n",(0,i.jsx)(n.p,{children:"The following preconditions are automatically checked:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Ensures the element is in the viewport."}),"\n",(0,i.jsxs)(n.li,{children:["Waits for the element to become\n",(0,i.jsx)(n.a,{href:"https://pptr.dev/api/puppeteer.elementhandle.isvisible/",children:"visible"})," or hidden."]}),"\n",(0,i.jsx)(n.li,{children:"Waits for the element to become enabled."}),"\n",(
|
