1"use strict";(self.webpackChunkplaywright_dev=self.webpackChunkplaywright_dev||[]).push([["2547"],{82400(e,t,s){s.r(t),s.d(t,{metadata:()=>r,default:()=>h,frontMatter:()=>l,contentTitle:()=>a,toc:()=>o,assets:()=>c});var r=JSON.parse('{"id":"api/class-selectors","title":"Selectors","description":"Selectors can be used to install custom selector engines. See extensibility for more information.","source":"@site/docs/api/class-selectors.mdx","sourceDirName":"api","slug":"/api/class-selectors","permalink":"/docs/next/api/class-selectors","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"id":"class-selectors","title":"Selectors"},"sidebar":"api","previous":{"title":"Screencast","permalink":"/docs/next/api/class-screencast"},"next":{"title":"TimeoutError","permalink":"/docs/next/api/class-timeouterror"}}'),n=s(74848),i=s(28453);s(13554),s(41647),s(83137);let l={id:"class-selectors",title:"Selectors"},a,c={},o=[{value:"Methods",id:"methods",level:2},{value:"register",id:"selectors-register",level:3},{value:"setTestIdAttribute",id:"selectors-set-test-id-attribute",level:3}];function d(e){let t={a:"a",code:"code",em:"em",h2:"h2",h3:"h3",hr:"hr",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,n.jsxs)(n.Fragment,{children:[(0,n.jsxs)(t.p,{children:["Selectors can be used to install custom selector engines. See ",(0,n.jsx)(t.a,{href:"/docs/next/extensibility",children:"extensibility"})," for more information."]}),"\n",(0,n.jsx)(t.hr,{}),"\n",(0,n.jsx)(t.h2,{id:"methods",children:"Methods"}),"\n",(0,n.jsx)(t.h3,{id:"selectors-register",children:"register"}),"\n",(0,n.jsx)("font",{size:"2",style:{position:"relative",top:"-20px"},children:"Added before v1.9"}),"\n",(0,n.jsx)("x-search",{children:"selectors.register"}),"\n",(0,n.jsx)(t.p,{children:"Selectors must be registered before creating the page."}),"\n",(0,n.jsx)(t.p,{children:(0,n.jsx)(t.strong,{children:"Usage"})}),"\n",(0,n.jsx)(t.p,{children:"An example of registering selector engine that queries elements based on a tag name:"}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-js",children:"const { selectors, firefox } = require('@playwright/test'); // Or 'chromium' or 'webkit'.\n\n(async () => {\n // Must be a function that evaluates to a selector engine instance.\n const createTagNameEngine = () => ({\n // Returns the first element matching given selector in the root's subtree.\n query(root, selector) {\n return root.querySelector(selector);\n },\n\n // Returns all elements matching given selector in the root's subtree.\n queryAll(root, selector) {\n return Array.from(root.querySelectorAll(selector));\n }\n });\n\n // Register the engine. Selectors will be prefixed with \"tag=\".\n await selectors.register('tag', createTagNameEngine);\n\n const browser = await firefox.launch();\n const page = await browser.newPage();\n await page.setContent(`<div><button>Click me</button></div>`);\n\n // Use the selector prefixed with its name.\n const button = page.locator('tag=button');\n // We can combine it with built-in locators.\n await page.locator('tag=div').getByText('Click me').click();\n // Can use it in any methods supporting selectors.\n const buttonCount = await page.locator('tag=button').count();\n\n await browser.close();\n})();\n"})}),"\n",(0,n.jsx)(t.p,{children:(0,n.jsx)(t.strong,{children:"Arguments"})}),"\n",(0,n.jsxs)(t.ul,{children:["\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"name"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type",title:"string",children:"string"}),(0,n.jsx)("a",{"aria-hidden":"true",tabIndex:"-1",class:"list-anchor-link",id:"selectors-register-option-name"}),(0,n.jsx)("a",{href:"#selectors-register-option-name",class:"list-anchor",children:"#"})]}),"\n",(0,n.jsxs)(t.p,{children:["Name that is used in selectors as a prefix, e.g. ",(0,n.jsx)(t.code,{children:"{name: 'foo'}"})," enables ",(0,n.jsx)(t.code,{children:"foo=myselectorbody"})," selectors. May only contain ",(0,n.jsx)(t.code,{children:"[a-zA-Z0-9_]"})," characters."]}),"\n"]}),"\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"script"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function",title:"Function",children:"function"})," | ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type",title:"string",children:"string"})," | ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object",title:"Object",children:"Object"}),(0,n.jsx)("a",{"aria-hidden":"true",tabIndex:"-1",class:"list-anchor-link",id:"selectors-register-option-script"}),(0,n.jsx)("a",{href:"#selectors-register-option-script",class:"list-anchor",children:"#"})]}),"\n",(0,n.jsxs)(t.ul,{children:["\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"path"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type",title:"string",children:"string"})," ",(0,n.jsx)(t.em,{children:"(optional)"})]}),"\n",(0,n.jsxs)(t.p,{children:["Path to the JavaScript file. If ",(0,n.jsx)(t.code,{children:"path"})," is a relative path, then it is resolved relative to the current working directory. Optional."]}),"\n"]}),"\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"content"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type",title:"string",children:"string"})," ",(0,n.jsx)(t.em,{children:"(optional)"})]}),"\n",(0,n.jsx)(t.p,{children:"Raw script content. Optional."}),"\n"]}),"\n"]}),"\n",(0,n.jsx)(t.p,{children:"Script that evaluates to a selector engine instance. The script is evaluated in the page context."}),"\n"]}),"\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"options"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object",title:"Object",children:"Object"})," ",(0,n.jsx)(t.em,{children:"(optional)"})]}),"\n",(0,n.jsxs)(t.ul,{children:["\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"contentScript"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type",title:"Boolean",children:"boolean"})," ",(0,n.jsx)(t.em,{children:"(optional)"}),(0,n.jsx)("a",{"aria-hidden":"true",tabIndex:"-1",class:"list-anchor-link",id:"selectors-register-option-content-script"}),(0,n.jsx)("a",{href:"#selectors-register-option-content-script",class:"list-anchor",children:"#"})]}),"\n",(0,n.jsxs)(t.p,{children:["Whether to run this selector engine in isolated JavaScript environment. This environment has access to the same DOM, but not any JavaScript objects from the frame's scripts. Defaults to ",(0,n.jsx)(t.code,{children:"false"}),". Note that running as a content script is not guaranteed when this engine is used together with other registered engines."]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,n.jsx)(t.p,{children:(0,n.jsx)(t.strong,{children:"Returns"})}),"\n",(0,n.jsxs)(t.ul,{children:["\n",(0,n.jsxs)(t.li,{children:[(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise",title:"Promise",children:"Promise"}),"<",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined",title:"void",children:"void"}),">",(0,n.jsx)("a",{"aria-hidden":"true",tabIndex:"-1",class:"list-anchor-link",id:"selectors-register-return"}),(0,n.jsx)("a",{href:"#selectors-register-return",class:"list-anchor",children:"#"})]}),"\n"]}),"\n",(0,n.jsx)(t.hr,{}),"\n",(0,n.jsx)(t.h3,{id:"selectors-set-test-id-attribute",children:"setTestIdAttribute"}),"\n",(0,n.jsx)("font",{size:"2",style:{position:"relative",top:"-20px"},children:"Added in: v1.27"}),"\n",(0,n.jsx)("x-search",{children:"selectors.setTestIdAttribute"}),"\n",(0,n.jsxs)(t.p,{children:["Defines custom attribute name to be used in ",(0,n.jsx)(t.a,{href:"/docs/next/api/class-page#page-get-by-test-id",children:"page.getByTestId()"}),". ",(0,n.jsx)(t.code,{children:"data-testid"})," is used by default."]}),"\n",(0,n.jsx)(t.p,{children:(0,n.jsx)(t.strong,{children:"Usage"})}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-js",children:"selectors.setTestIdAttribute(attributeName);\n"})}),"\n",(0,n.jsx)(t.p,{children:(0,n.jsx)(t.strong,{children:"Arguments"})}),"\n",(0,n.jsxs)(t.ul,{children:["\n",(0,n.jsxs)(t.li,{children:["\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.code,{children:"attributeName"})," ",(0,n.jsx)(t.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type",title:"string",children:"string"}),(0,n.jsx)("a",{"aria-hidden":"true",tabIndex:"-1",class:"list-anchor-link",id:"selectors-set-test-id-attribute-option-attribute-name"}),(0,n.jsx)("a",{href:"#selectors-set-test-id-attribute-option-attribute-name",class:"list-anchor",children:"#"})]}),"\n",(0,n.jsxs)(t.p,{children:["Test id attribute name. To match elements with any of several attributes, pass them as a comma-separated list, e.g. ",(0,n.jsx)(t.code,{children:'"data-pw,data-ti"'}),"."]}),"\n"]}),"\n"]})]})}function h(e={}){let{wrapper:t}={...(0,i.R)(),...e.components};return t?(0,n.jsx)(t,{...e,children:(0,n.jsx)(d,{...e})}):d(e)}}}]);
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.