/*! For license information please see 1236ce82.3587be35.js.LICENSE.txt */
"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",(0,i.jsx)(n.li,{children:"Waits for the element to have a stable bounding box over two consecutive\nanimation frames."}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"clicking-an-element-matching-a-criteria",children:"Clicking an element matching a criteria"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page\n  .locator('button')\n  .filter(button => !button.disabled)\n  .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",(0,i.jsx)(n.li,{children:"Waits for the element to have a stable bounding box over two consecutive\nanimation frames."}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"filling-out-an-input",children:"Filling out an input"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page.locator('input').fill('value');\n"})}),"\n",(0,i.jsx)(n.p,{children:"Automatically detects the input type and choose an approritate way to fill it out with the provided value."}),"\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",(0,i.jsx)(n.li,{children:"Waits for the element to have a stable bounding box over two consecutive\nanimation frames."}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"retrieving-an-element-property",children:"Retrieving an element property"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"const enabled = await page\n  .locator('button')\n  .map(button => !button.disabled)\n  .wait();\n"})}),"\n",(0,i.jsx)(n.h3,{id:"hover-over-an-element",children:"Hover over an element"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page.locator('div').hover();\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 have a stable bounding box over two consecutive\nanimation frames."}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"scroll-an-element",children:"Scroll an element"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page.locator('div').scroll({\n  scrollLeft: 10,\n  scrollTop: 20,\n});\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 have a stable bounding box over two consecutive\nanimation frames."}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"configuring-locators",children:"Configuring locators"}),"\n",(0,i.jsx)(n.p,{children:"Locators can be configured to tune configure the preconditions and other other options:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"await page\n  .locator('button')\n  .setEnsureElementIsInTheViewport(false)\n  .setTimeout(0)\n  .setVisibility(null)\n  .setWaitForEnabled(false)\n  .setWaitForStableBoundingBox(false)\n  .click();\n"})}),"\n",(0,i.jsx)(n.h2,{id:"getting-locator-events",children:"Getting locator events"}),"\n",(0,i.jsx)(n.p,{children:"Currently, locators support a single event that notifies you when the locator is about to perform the action:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"let willClick = false;\nawait page\n  .locator('button')\n  .on(LocatorEmittedEvents.Action, () => {\n    willClick = true;\n  })\n  .click();\n"})}),"\n",(0,i.jsx)(n.p,{children:"This event can be used for logging/debugging or other purposes. The event might\nfire multiple times if the locator retries the action."})]})}function h(e={}){const{wrapper:n}={...(0,l.a)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},75251:(e,n,t)=>{var i=t(67294),l=Symbol.for("react.element"),o=Symbol.for("react.fragment"),r=Object.prototype.hasOwnProperty,a=i.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,s={key:!0,ref:!0,__self:!0,__source:!0};function c(e,n,t){var i,o={},c=null,d=null;for(i in void 0!==t&&(c=""+t),void 0!==n.key&&(c=""+n.key),void 0!==n.ref&&(d=n.ref),n)r.call(n,i)&&!s.hasOwnProperty(i)&&(o[i]=n[i]);if(e&&e.defaultProps)for(i in n=e.defaultProps)void 0===o[i]&&(o[i]=n[i]);return{$$typeof:l,type:e,key:c,ref:d,props:o,_owner:a.current}}n.Fragment=o,n.jsx=c,n.jsxs=c},85893:(e,n,t)=>{e.exports=t(75251)},11151:(e,n,t)=>{t.d(n,{Z:()=>a,a:()=>r});var i=t(67294);const l={},o=i.createContext(l);function r(e){const n=i.useContext(o);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:r(e.components),i.createElement(o.Provider,{value:n},e.children)}}}]);