2024-04-11 12:01:20 +00:00
<!doctype html>
< html lang = "en" dir = "ltr" class = "docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-guides/page-interactions" data-has-hydrated = "false" >
< head >
< meta charset = "UTF-8" >
2024-06-04 08:22:15 +00:00
< meta name = "generator" content = "Docusaurus v3.4.0" >
2024-04-11 12:01:20 +00:00
< title data-rh = "true" > Page interactions | Puppeteer< / title > < meta data-rh = "true" name = "viewport" content = "width=device-width,initial-scale=1" > < meta data-rh = "true" name = "twitter:card" content = "summary_large_image" > < meta data-rh = "true" property = "og:url" content = "https://pptr.dev/next/guides/page-interactions" > < meta data-rh = "true" property = "og:locale" content = "en" > < meta data-rh = "true" name = "docsearch:language" content = "en" > < meta data-rh = "true" name = "docsearch:counter" content = "3" > < meta data-rh = "true" property = "og:title" content = "Page interactions | Puppeteer" > < meta data-rh = "true" name = "description" content = "Puppeteer allows you interact with the pages in various ways." > < meta data-rh = "true" property = "og:description" content = "Puppeteer allows you interact with the pages in various ways." > < link data-rh = "true" rel = "icon" href = "/img/favicon.ico" > < link data-rh = "true" rel = "canonical" href = "https://pptr.dev/next/guides/page-interactions" > < link data-rh = "true" rel = "alternate" href = "https://pptr.dev/next/guides/page-interactions" hreflang = "en" > < link data-rh = "true" rel = "alternate" href = "https://pptr.dev/next/guides/page-interactions" hreflang = "x-default" > < link data-rh = "true" rel = "preconnect" href = "https://DVKY664LG7-dsn.algolia.net" crossorigin = "anonymous" > < link rel = "search" type = "application/opensearchdescription+xml" title = "Puppeteer" href = "/opensearch.xml" >
2024-05-06 08:01:08 +00:00
< script src = "/fix-location.js" > < / script > < link rel = "stylesheet" href = "/assets/css/styles.67634aff.css" >
2024-06-11 09:40:10 +00:00
< script src = "/assets/js/runtime~main.ab796bf4.js" defer = "defer" > < / script >
< script src = "/assets/js/main.7b3e7a47.js" defer = "defer" > < / script >
2024-04-11 12:01:20 +00:00
< / head >
< body class = "navigation-with-keyboard" >
2024-06-04 08:22:15 +00:00
< script > ! function ( ) { function t ( t ) { document . documentElement . setAttribute ( "data-theme" , t ) } var e = function ( ) { try { return new URLSearchParams ( window . location . search ) . get ( "docusaurus-theme" ) } catch ( t ) { } } ( ) || function ( ) { try { return window . localStorage . getItem ( "theme" ) } catch ( t ) { } } ( ) ; t ( null !== e ? e : "light" ) } ( ) , function ( ) { try { const n = new URLSearchParams ( window . location . search ) . entries ( ) ; for ( var [ t , e ] of n ) if ( t . startsWith ( "docusaurus-data-" ) ) { var a = t . replace ( "docusaurus-data-" , "data-" ) ; document . documentElement . setAttribute ( a , e ) } } catch ( t ) { } } ( ) < / script > < div id = "__docusaurus" > < div role = "region" aria-label = "Skip to main content" > < a class = "skipToContent_gu5v" href = "#__docusaurus_skipToContent_fallback" > Skip to main content< / a > < / div > < nav aria-label = "Main" class = "navbar navbar--fixed-top" > < div class = "navbar__inner" > < div class = "navbar__items" > < button aria-label = "Toggle navigation bar" aria-expanded = "false" class = "navbar__toggle clean-btn" type = "button" > < svg width = "30" height = "30" viewBox = "0 0 30 30" aria-hidden = "true" > < path stroke = "currentColor" stroke-linecap = "round" stroke-miterlimit = "10" stroke-width = "2" d = "M4 7h22M4 15h22M4 23h22" > < / path > < / svg > < / button > < a class = "navbar__brand" href = "/" > < div class = "navbar__logo" > < img src = "https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" alt = "Puppeteer Logo" class = "themedComponent_mlkZ themedComponent--light_NVdE" > < img src = "https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" alt = "Puppeteer Logo" class = "themedComponent_mlkZ themedComponent--dark_xIcU" > < / div > < b class = "navbar__title text--truncate" > Puppeteer< / b > < / a > < a aria-current = "page" class = "navbar__item navbar__link navbar__link--active" href = "/next/category/introduction" > Docs< / a > < a class = "navbar__item navbar__link" href = "/next/api/puppeteer.puppeteernode" > Puppeteer API< / a > < a class = "navbar__item navbar__link" href = "/next/browsers-api/" > @puppeteer/browsers API< / a > < / div > < div class = "navbar__items navbar__items--right" > < div class = "navbar__item dropdown dropdown--hoverable dropdown--right" > < a class = "navbar__link" aria-haspopup = "true" aria-expanded = "false" role = "button" href = "/next/" > Next< / a > < ul class = "dropdown__menu" > < li > < a aria-current = "page" class = "dropdown__link dropdown__link--active" href = "/next/guides/page-interactions" > Next< / a > < / li > < li > < a class = "dropdown__link" href = "/guides/page-interactions" > 22.10.0< / a > < / li > < li > < hr class = "dropdown-separator" > < / li > < li class = "dropdown-archived-versions" > < b > Archived versions< / b > < / li > < li > < a href = "https://github.com/puppeteer/puppeteer/blob/puppeteer-v22.9.0/docs/api/index.md" target = "_blank" rel = "noopener noreferrer" class = "dropdown__link" > 22.9.0< svg width = "12" height = "12" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" > < / path > < / svg > < / a > < / li > < li > < a href = "https://github.com/puppeteer/puppeteer/blob/puppeteer-v22.8.2/docs/api/index.md" target = "_blank" rel = "noopener noreferrer" class = "dropdown__link" > 22.8.2< svg width = "12" height = "12" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" > < / path > < / svg > < / a > < / li > < li > < a href = "https://github.com/puppeteer/puppeteer/blob/puppeteer-v22.8.1/docs/api/index.md" target = "_blank" rel = "noopener noreferrer" class = "dropdown__link" > 22.8.1< svg width = "12" height = "12" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" > < / path > < / svg > < / a > < / li > < li > < a href = "https://github.com/puppeteer/puppeteer/blob/puppeteer-v22.8.0/docs/api/index.md" target = "_blank" rel = "noopener noreferrer" class = "dropdown__link" > 22.8.0< svg width = "12" height = "12" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13
2024-04-11 12:01:20 +00:00
< p > Puppeteer allows you interact with the pages in various ways.< / p >
2024-06-04 08:22:15 +00:00
< h2 class = "anchor anchorWithStickyNavbar_FNw8" id = "locators" > Locators< a class = "hash-link" aria-label = "Direct link to Locators" title = "Direct link to Locators" href = "/next/guides/page-interactions#locators" > < / a > < / h2 >
2024-04-11 12:01:20 +00:00
< p > Locators is a new, experimental API that combines the functionalities of
waiting and actions. With additional precondition checks, it
enables automatic retries for failed actions, resulting in more reliable and
less flaky automation scripts.< / p >
2024-05-06 08:01:08 +00:00
< div class = "theme-admonition theme-admonition-note admonition_LMjb alert alert--secondary" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 14 16" > < path fill-rule = "evenodd" d = "M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z" > < / path > < / svg > < / span > note< / div > < div class = "admonitionContent_pGk6" > < p > Locators API is experimental and we will not follow semver for breaking changes
2024-04-11 12:01:20 +00:00
in the Locators API.< / p > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "use-cases" > Use cases< a class = "hash-link" aria-label = "Direct link to Use cases" title = "Direct link to Use cases" href = "/next/guides/page-interactions#use-cases" > < / a > < / h3 >
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "waiting-for-an-element" > Waiting for an element< a class = "hash-link" aria-label = "Direct link to Waiting for an element" title = "Direct link to Waiting for an element" href = "/next/guides/page-interactions#waiting-for-an-element" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' button' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > wait< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > The following preconditions are automatically checked:< / p >
< ul >
< li > Waits for the element to become
< a href = "https://pptr.dev/api/puppeteer.elementhandle.isvisible/" target = "_blank" rel = "noopener noreferrer" > visible< / a > or hidden.< / li >
< / ul >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "waiting-for-a-function" > Waiting for a function< a class = "hash-link" aria-label = "Direct link to Waiting for a function" title = "Direct link to Waiting for a function" href = "/next/guides/page-interactions#waiting-for-a-function" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > let< / span > < span class = "token plain" > resolve< / span > < span class = "token operator" style = "color:#393A34" > !< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > node< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > HTMLCanvasElement< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > void< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > promise < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > new< / span > < span class = "token plain" > < / span > < span class = "token class-name builtin" > Promise< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > res < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > return< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > resolve < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > res< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > }< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > observer < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > new< / span > < span class = "token plain" > < / span > < span class = "token class-name" > MutationObserver< / span > < span class = "token punctuation" style = "color:#393A3
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "clicking-an-element" > Clicking an element< a class = "hash-link" aria-label = "Direct link to Clicking an element" title = "Direct link to Clicking an element" href = "/next/guides/page-interactions#clicking-an-element" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' button' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > click< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > The following preconditions are automatically checked:< / p >
< ul >
< li > Ensures the element is in the viewport.< / li >
< li > Waits for the element to become
< a href = "https://pptr.dev/api/puppeteer.elementhandle.isvisible/" target = "_blank" rel = "noopener noreferrer" > visible< / a > or hidden.< / li >
< li > Waits for the element to become enabled.< / li >
< li > Waits for the element to have a stable bounding box over two consecutive
animation frames.< / li >
< / ul >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "clicking-an-element-matching-a-criteria" > Clicking an element matching a criteria< a class = "hash-link" aria-label = "Direct link to Clicking an element matching a criteria" title = "Direct link to Clicking an element matching a criteria" href = "/next/guides/page-interactions#clicking-an-element-matching-a-criteria" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' button' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > filter< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > button < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > !< / span > < span class = "token plain" > button< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > disabled< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > click< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > The following preconditions are automatically checked:< / p >
< ul >
< li > Ensures the element is in the viewport.< / li >
< li > Waits for the element to become
< a href = "https://pptr.dev/api/puppeteer.elementhandle.isvisible/" target = "_blank" rel = "noopener noreferrer" > visible< / a > or hidden.< / li >
< li > Waits for the element to become enabled.< / li >
< li > Waits for the element to have a stable bounding box over two consecutive
animation frames.< / li >
< / ul >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "filling-out-an-input" > Filling out an input< a class = "hash-link" aria-label = "Direct link to Filling out an input" title = "Direct link to Filling out an input" href = "/next/guides/page-interactions#filling-out-an-input" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' input' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > fill< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' value' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > Automatically detects the input type and choose an appropriate way to fill it out with the provided value.< / p >
< p > The following preconditions are automatically checked:< / p >
< ul >
< li > Ensures the element is in the viewport.< / li >
< li > Waits for the element to become
< a href = "https://pptr.dev/api/puppeteer.elementhandle.isvisible/" target = "_blank" rel = "noopener noreferrer" > visible< / a > or hidden.< / li >
< li > Waits for the element to become enabled.< / li >
< li > Waits for the element to have a stable bounding box over two consecutive
animation frames.< / li >
< / ul >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "retrieving-an-element-property" > Retrieving an element property< a class = "hash-link" aria-label = "Direct link to Retrieving an element property" title = "Direct link to Retrieving an element property" href = "/next/guides/page-interactions#retrieving-an-element-property" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > enabled < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' button' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > map< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > button < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > !< / span > < span class = "token plain" > button< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > disabled< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > wait< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "hover-over-an-element" > Hover over an element< a class = "hash-link" aria-label = "Direct link to Hover over an element" title = "Direct link to Hover over an element" href = "/next/guides/page-interactions#hover-over-an-element" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' div' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > hover< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > The following preconditions are automatically checked:< / p >
< ul >
< li > Ensures the element is in the viewport.< / li >
< li > Waits for the element to become
< a href = "https://pptr.dev/api/puppeteer.elementhandle.isvisible/" target = "_blank" rel = "noopener noreferrer" > visible< / a > or hidden.< / li >
< li > Waits for the element to have a stable bounding box over two consecutive
animation frames.< / li >
< / ul >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "scroll-an-element" > Scroll an element< a class = "hash-link" aria-label = "Direct link to Scroll an element" title = "Direct link to Scroll an element" href = "/next/guides/page-interactions#scroll-an-element" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' div' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > scroll< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > scrollLeft< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > < / span > < span class = "token number" style = "color:#36acaa" > 10< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > scrollTop< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > < / span > < span class = "token number" style = "color:#36acaa" > 20< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > }< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > The following preconditions are automatically checked:< / p >
< ul >
< li > Ensures the element is in the viewport.< / li >
< li > Waits for the element to become
< a href = "https://pptr.dev/api/puppeteer.elementhandle.isvisible/" target = "_blank" rel = "noopener noreferrer" > visible< / a > or hidden.< / li >
< li > Waits for the element to have a stable bounding box over two consecutive
animation frames.< / li >
< / ul >
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "configuring-locators" > Configuring locators< a class = "hash-link" aria-label = "Direct link to Configuring locators" title = "Direct link to Configuring locators" href = "/next/guides/page-interactions#configuring-locators" > < / a > < / h3 >
2024-04-11 12:01:20 +00:00
< p > Locators can be configured to tune configure the preconditions and other other options:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' button' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > setEnsureElementIsInTheViewport< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token boolean" style = "color:#36acaa" > false< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > setTimeout< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token number" style = "color:#36acaa" > 0< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > setVisibility< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token keyword" style = "color:#00009f" > null< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > setWaitForEnabled< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token boolean" style = "color:#36acaa" > false< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > setWaitForStableBoundingBox< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token boolean" style = "color:#36acaa" > false< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > click< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "getting-locator-events" > Getting locator events< a class = "hash-link" aria-label = "Direct link to Getting locator events" title = "Direct link to Getting locator events" href = "/next/guides/page-interactions#getting-locator-events" > < / a > < / h3 >
2024-04-11 12:01:20 +00:00
< p > Currently, locators support a single event that notifies you when the locator is about to perform the action:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > let< / span > < span class = "token plain" > willClick < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token boolean" style = "color:#36acaa" > false< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > locator< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' button' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > on< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > LocatorEvent< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > Action< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > willClick < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token boolean" style = "color:#36acaa" > true< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > }< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > click< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > This event can be used for logging/debugging or other purposes. The event might
fire multiple times if the locator retries the action.< / p >
2024-06-04 08:22:15 +00:00
< h2 class = "anchor anchorWithStickyNavbar_FNw8" id = "query-selectors" > Query Selectors< a class = "hash-link" aria-label = "Direct link to Query Selectors" title = "Direct link to Query Selectors" href = "/next/guides/page-interactions#query-selectors" > < / a > < / h2 >
2024-04-11 12:01:20 +00:00
< p > Queries are the primary mechanism for interacting with the DOM on your site. For example, a typical workflow goes like:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token comment" style = "color:#999988;font-style:italic" > // Import puppeteer< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > import< / span > < span class = "token plain" > puppeteer < / span > < span class = "token keyword" style = "color:#00009f" > from< / span > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' puppeteer' < / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token keyword" style = "color:#00009f" > async< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Launch the browser< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > browser < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > puppeteer< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > launch< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Create a page< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > page < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > browser< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > newPage< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Go to your site< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" sty
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "p-selectors" > < code > P< / code > Selectors< a class = "hash-link" aria-label = "Direct link to p-selectors" title = "Direct link to p-selectors" href = "/next/guides/page-interactions#p-selectors" > < / a > < / h3 >
2024-04-11 12:01:20 +00:00
< p > Puppeteer uses a superset of the CSS selector syntax for querying. We call this syntax < em > P selectors< / em > and it' s supercharged with extra capabilities such as deep combinators and text selection.< / p >
2024-05-06 08:01:08 +00:00
< div class = "theme-admonition theme-admonition-caution admonition_LMjb alert alert--warning" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 16 16" > < path fill-rule = "evenodd" d = "M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z" > < / path > < / svg > < / span > caution< / div > < div class = "admonitionContent_pGk6" > < p > Although P selectors look like real CSS selectors (we intentionally designed it this way), they should not be used for actually CSS styling. They are designed only for Puppeteer.< / p > < / div > < / div >
< div class = "theme-admonition theme-admonition-note admonition_LMjb alert alert--secondary" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 14 16" > < path fill-rule = "evenodd" d = "M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z" > < / path > < / svg > < / span > note< / div > < div class = "admonitionContent_pGk6" > < p > P selectors only work on the first " depth" of selectors; for example, < code > :is(div > > > a)< / code > will not work.< / p > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "-and--combinators" > < code > > > > < / code > and < code > > > > > < / code > combinators< a class = "hash-link" aria-label = "Direct link to -and--combinators" title = "Direct link to -and--combinators" href = "/next/guides/page-interactions#-and--combinators" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > The < code > > > > < / code > and < code > > > > > < / code > are called < em > deep descendent< / em > and < em > deep< / em > combinators respectively. Both combinators have the effect of going into shadow hosts with < code > > > > < / code > going into every shadow host under a node and < code > > > > > < / code > going into the immediate one (if the node is a shadow host; otherwise, it' s a no-op).< / p >
2024-05-06 08:01:08 +00:00
< div class = "theme-admonition theme-admonition-note admonition_LMjb alert alert--secondary" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 14 16" > < path fill-rule = "evenodd" d = "M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z" > < / path > < / svg > < / span > note< / div > < div class = "admonitionContent_pGk6" > < p > A common question is when should < code > > > > > < / code > be chosen over < code > > > > < / code > considering the flexibility of < code > > > > < / code > . A similar question can be asked about < code > > < / code > and a space; choose < code > > < / code > if you do not need to query all elements under a given node and a space otherwise. This answer extends to < code > > > > > < / code > (< code > > < / code > ) and < code > > > > < / code > (space) naturally.< / p > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "example" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > Suppose we have the markup< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-html codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-html codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > custom-element< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > template< / span > < span class = "token tag" style = "color:#00009f" > < / span > < span class = "token tag attr-name" style = "color:#00a4db" > shadowrootmode< / span > < span class = "token tag attr-value punctuation attr-equals" style = "color:#393A34" > =< / span > < span class = "token tag attr-value punctuation" style = "color:#393A34" > " < / span > < span class = "token tag attr-value" style = "color:#e3116c" > open< / span > < span class = "token tag attr-value punctuation" style = "color:#393A34" > " < / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > slot< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > slot< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > template< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > custom-element< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > template< / span > < span class = "token tag" style = "color:#00009f" > < / span > < span class = "token tag attr-name" style = "color:#00a4db" > shadowrootmode< / span > < span class = "token tag attr-value punctuation attr-equals" style = "color:#393A34" > =< / span > < span class = "token tag attr-value punctuation" style = "color:#393A34" > " < / span > < span class = "token tag attr-value" style = "color:#e3116c" > open< / span > < span class = "token tag attr-value punctuation" style = "color:#393A34" > " < / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > slot< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > slot< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > template< / span > < sp
2024-04-11 12:01:20 +00:00
< blockquote >
< p > Note: < code > < template shadowrootmode=" open" > < / code > is not supported on Firefox.
You can read more about it < a href = "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template#attributes" target = "_blank" rel = "noopener noreferrer" > here< / a > .< / p >
< / blockquote >
< p > Then < code > custom-element > > > h2< / code > will return < code > h2< / code > , but < code > custom-element > > > > h2< / code > will return nothing since the inner < code > h2< / code > is in a deeper shadow root.< / p >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "p-elements" > < code > P< / code > -elements< a class = "hash-link" aria-label = "Direct link to p-elements" title = "Direct link to p-elements" href = "/next/guides/page-interactions#p-elements" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > < code > P< / code > elements are < a href = "https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements" target = "_blank" rel = "noopener noreferrer" > pseudo-elements< / a > with a < code > -p< / code > vendor prefix. It allows you to enhance your selectors with Puppeteer-specific query engines such as XPath, text queries, and ARIA.< / p >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "text-selectors--p-text" > Text selectors (< code > -p-text< / code > )< a class = "hash-link" aria-label = "Direct link to text-selectors--p-text" title = "Direct link to text-selectors--p-text" href = "/next/guides/page-interactions#text-selectors--p-text" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > Text selectors will select " minimal" elements containing the given text, even within (open) shadow roots. Here, " minimum" means the deepest elements that contain a given text, but not their parents (which technically will also contain the given text).< / p >
2024-06-04 08:22:15 +00:00
< h6 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-1" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-1" > < / a > < / h6 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' div ::-p-text(My name is Jun)' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // You can also use escapes.< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' :scope > > > ::-p-text(My name is Jun \\(pronounced like " June" \\))' < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // or quotes< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' div > > > > ::-p-text(" My name is Jun (pronounced like \\" June\\" )" ):hover' < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "cu
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "xpath-selectors--p-xpath" > XPath selectors (< code > -p-xpath< / code > )< a class = "hash-link" aria-label = "Direct link to xpath-selectors--p-xpath" title = "Direct link to xpath-selectors--p-xpath" href = "/next/guides/page-interactions#xpath-selectors--p-xpath" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > XPath selectors will use the browser' s native < a href = "https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate" target = "_blank" rel = "noopener noreferrer" > < code > Document.evaluate< / code > < / a > to query for elements.< / p >
2024-06-04 08:22:15 +00:00
< h6 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-2" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-2" > < / a > < / h6 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' ::-p-xpath(h2)' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "aria-selectors--p-aria" > ARIA selectors (< code > -p-aria< / code > )< a class = "hash-link" aria-label = "Direct link to aria-selectors--p-aria" title = "Direct link to aria-selectors--p-aria" href = "/next/guides/page-interactions#aria-selectors--p-aria" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > ARIA selectors can be used to find elements with a given ARIA label. These labels are computed using Chrome' s internal representation.< / p >
2024-06-04 08:22:15 +00:00
< h6 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-3" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-3" > < / a > < / h6 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > node < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' ::-p-aria(Submit)' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > node < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' ::-p-aria([name=" Click me" ][role=" button" ])' < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "custom-selectors" > Custom selectors< a class = "hash-link" aria-label = "Direct link to Custom selectors" title = "Direct link to Custom selectors" href = "/next/guides/page-interactions#custom-selectors" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > Puppeteer provides users the ability to add their own query selectors to Puppeteer using < a href = "/next/api/puppeteer.registercustomqueryhandler" > Puppeteer.registerCustomQueryHandler< / a > . This is useful for creating custom selectors based on framework objects or other vendor-specific objects.< / p >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "custom-selectors-1" > Custom Selectors< a class = "hash-link" aria-label = "Direct link to Custom Selectors" title = "Direct link to Custom Selectors" href = "/next/guides/page-interactions#custom-selectors-1" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > You can register a custom query handler that allows you to create custom selectors. For example, define a query handler for < code > getById< / code > selectors:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > Puppeteer< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > registerCustomQueryHandler< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' getById' < / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token function-variable function" style = "color:#d73a49" > queryOne< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > elementOrDocument< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > selector< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > return< / span > < span class = "token plain" > elementOrDocument< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > querySelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token template-string template-punctuation string" style = "color:#e3116c" > `< / span > < span class = "token template-string string" style = "color:#e3116c" > [id=" < / span > < span class = "token template-string interpolation interpolation-punctuation punctuation" style = "color:#393A34" > ${< / span > < span class = "token template-string interpolation constant" style = "color:#36acaa" > CSS< / span > < span class = "token template-string interpolation punctuation" style = "color:#393A34" > .< / span > < span class = "token template-string interpolation function" style = "color:#d73a49" > escape< / span > < span class = "token template-string interpolation punctuation" style = "color:#393A34" > (< / span > < span class = "token template-string interpolation" > selector< / span > < span class = "token template-string interpolation punctuation" style = "color:#393A34" > )< / span > < span class = "token template-string interpolation interpolation-punctuation punctuation" style = "color:#393A34" > }< / span > < span class = "token template-string string" style = "color:#e3116c" > " ]< / span > < span class = "token template-string template-punctuation string" style = "color:#e3116c" > `< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > }< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Note: for demonstation perpose only `id` should be page unique< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token function-variable function" style = "color:#d73a49" > queryAll< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span cla
2024-04-11 12:01:20 +00:00
< p > You can now use it as following:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > node < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' ::-p-getById(elementId)' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // OR used in conjunction with other selectors< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > moreSpecificNode < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' .side-bar ::-p-getById(elementId)' < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "custom-framework-components-selector" > Custom framework components selector< a class = "hash-link" aria-label = "Direct link to Custom framework components selector" title = "Direct link to Custom framework components selector" href = "/next/guides/page-interactions#custom-framework-components-selector" > < / a > < / h5 >
2024-05-06 08:01:08 +00:00
< div class = "theme-admonition theme-admonition-caution admonition_LMjb alert alert--warning" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 16 16" > < path fill-rule = "evenodd" d = "M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z" > < / path > < / svg > < / span > caution< / div > < div class = "admonitionContent_pGk6" > < p > Be careful when relying on internal APIs of libraries or frameworks. They can change at any time.< / p > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > Find Vue components by name by using Vue internals for querying:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > Puppeteer< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > registerCustomQueryHandler< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' vue' < / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token function-variable function" style = "color:#d73a49" > queryOne< / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > element< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > name< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > walker < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > document< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > createTreeWalker< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > element< / span > < span class = "token punctuation" style = "color:#393A34" > ,< / span > < span class = "token plain" > NodeFilter< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token constant" style = "color:#36acaa" > SHOW_ELEMENT< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > do< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > currentNode < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > walker< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > currentNode< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > if< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > currentNode< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > __vnode< / span > < span class = "token operator" style = "color:#393A34" > ?.< / span > < span class = "token plain" > ctx< / span > < span class = "token operator" style = "color:#393A34" > ?.< / span > < span class = "token plain" > type< / span > < span class = "token operator" style = "color:
2024-04-11 12:01:20 +00:00
< p > Query the Vue component as following:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > $< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' ::-p-vue(MyComponent)' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "web-components" > Web Components< a class = "hash-link" aria-label = "Direct link to Web Components" title = "Direct link to Web Components" href = "/next/guides/page-interactions#web-components" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > Web Components create their own tag so you can query them by the tag name:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > $< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' my-web-component' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > Extend < code > HTMLElementTagNameMap< / code > to define types for custom tags. This allows Puppeteer to infer the return type for the ElementHandle:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > declare< / span > < span class = "token plain" > global < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > interface< / span > < span class = "token plain" > < / span > < span class = "token class-name" > HTMLElementTagNameMap< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token string-property property" style = "color:#36acaa" > ' my-web-component' < / span > < span class = "token operator" style = "color:#393A34" > :< / span > < span class = "token plain" > MyWebComponent< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > }< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > }< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h2 class = "anchor anchorWithStickyNavbar_FNw8" id = "query-selectors-legacy" > Query Selectors (legacy)< a class = "hash-link" aria-label = "Direct link to Query Selectors (legacy)" title = "Direct link to Query Selectors (legacy)" href = "/next/guides/page-interactions#query-selectors-legacy" > < / a > < / h2 >
2024-06-03 09:10:13 +00:00
< div class = "theme-admonition theme-admonition-caution admonition_LMjb alert alert--warning" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 16 16" > < path fill-rule = "evenodd" d = "M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z" > < / path > < / svg > < / span > caution< / div > < div class = "admonitionContent_pGk6" > < p > While we maintain prefixed selectors, the recommended way is to use the selector syntax documented above.< / p > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > Queries are the primary mechanism for interacting with the DOM on your site. For example, a typical workflow goes like:< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token comment" style = "color:#999988;font-style:italic" > // Import puppeteer< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > import< / span > < span class = "token plain" > puppeteer < / span > < span class = "token keyword" style = "color:#00009f" > from< / span > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' puppeteer' < / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token keyword" style = "color:#00009f" > async< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token operator" style = "color:#393A34" > => < / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > {< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Launch the browser< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > browser < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > puppeteer< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > launch< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Create a page< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > page < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > browser< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > newPage< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Go to your site< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" sty
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "css" > CSS< a class = "hash-link" aria-label = "Direct link to CSS" title = "Direct link to CSS" href = "/next/guides/page-interactions#css" > < / a > < / h3 >
2024-04-11 12:01:20 +00:00
< p > CSS selectors follow the CSS spec of the browser being automated. We provide some basic type deduction for CSS selectors (such as < code > HTMLInputElement< / code > for < code > input< / code > ), but any selector that contains no type information (such as < code > .class-name< / code > ) will need to be coerced manually using TypeScript' s < code > as< / code > coercion mechanism.< / p >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-4" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-4" > < / a > < / h4 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token comment" style = "color:#999988;font-style:italic" > // Automatic< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' div > input' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Manual< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token string" style = "color:#e3116c" > ' div > .class-name-for-input' < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > as< / span > < span class = "token plain" > HTMLInputElement< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "built-in-selectors" > Built-in selectors< a class = "hash-link" aria-label = "Direct link to Built-in selectors" title = "Direct link to Built-in selectors" href = "/next/guides/page-interactions#built-in-selectors" > < / a > < / h3 >
2024-04-11 12:01:20 +00:00
< p > Built-in selectors are Puppeteer' s own class of selectors for doing things CSS cannot. Every built-in selector starts with a prefix < code > .../< / code > to assist Puppeteer in distinguishing between CSS selectors and a built-in.< / p >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "text-selectors-text" > Text selectors (< code > text/< / code > )< a class = "hash-link" aria-label = "Direct link to text-selectors-text" title = "Direct link to text-selectors-text" href = "/next/guides/page-interactions#text-selectors-text" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > Text selectors will select " minimal" elements containing the given text, even within (open) shadow roots. Here, " minimum" means the deepest elements that contain a given text, but not their parents (which technically will also contain the given text).< / p >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-5" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-5" > < / a > < / h5 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token comment" style = "color:#999988;font-style:italic" > // Note we usually need type coercion since the type cannot be deduced, but for text selectors, `instanceof` checks may be better for runtime validation.< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > element < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' text/My name is Jun' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "xpath-selectors-xpath" > XPath selectors (< code > xpath/< / code > )< a class = "hash-link" aria-label = "Direct link to xpath-selectors-xpath" title = "Direct link to xpath-selectors-xpath" href = "/next/guides/page-interactions#xpath-selectors-xpath" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > XPath selectors will use the browser' s native < a href = "https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate" target = "_blank" rel = "noopener noreferrer" > < code > Document.evaluate< / code > < / a > to query for elements.< / p >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-6" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-6" > < / a > < / h5 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token comment" style = "color:#999988;font-style:italic" > // There is not type deduction for XPaths.< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > node < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' xpath/h2' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "aria-selectors-aria" > ARIA selectors (< code > aria/< / code > )< a class = "hash-link" aria-label = "Direct link to aria-selectors-aria" title = "Direct link to aria-selectors-aria" href = "/next/guides/page-interactions#aria-selectors-aria" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > ARIA selectors can be used to find elements with a given ARIA label. These labels are computed using Chrome' s internal representation.< / p >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-7" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-7" > < / a > < / h5 >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token keyword" style = "color:#00009f" > const< / span > < span class = "token plain" > node < / span > < span class = "token operator" style = "color:#393A34" > =< / span > < span class = "token plain" > < / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > waitForSelector< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' aria/Button name' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h4 class = "anchor anchorWithStickyNavbar_FNw8" id = "pierce-selectors-pierce" > Pierce selectors (< code > pierce/< / code > )< a class = "hash-link" aria-label = "Direct link to pierce-selectors-pierce" title = "Direct link to pierce-selectors-pierce" href = "/next/guides/page-interactions#pierce-selectors-pierce" > < / a > < / h4 >
2024-04-11 12:01:20 +00:00
< p > Pierce selectors will run the < code > querySelector*< / code > API on the document and all shadow roots to find an element.< / p >
2024-05-06 08:01:08 +00:00
< div class = "theme-admonition theme-admonition-danger admonition_LMjb alert alert--danger" > < div class = "admonitionHeading_GGQ4" > < span class = "admonitionIcon_ifdW" > < svg viewBox = "0 0 12 16" > < path fill-rule = "evenodd" d = "M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z" > < / path > < / svg > < / span > danger< / div > < div class = "admonitionContent_pGk6" > < p > Selectors will < strong > not< / strong > < em > partially< / em > pierce through shadow roots. See the examples below.< / p > < / div > < / div >
2024-06-04 08:22:15 +00:00
< h5 class = "anchor anchorWithStickyNavbar_FNw8" id = "example-8" > Example< a class = "hash-link" aria-label = "Direct link to Example" title = "Direct link to Example" href = "/next/guides/page-interactions#example-8" > < / a > < / h5 >
2024-04-11 12:01:20 +00:00
< p > Suppose the HTML is< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-html codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-html codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > div< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > custom-element< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < < / span > < span class = "token tag" style = "color:#00009f" > div< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > div< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > custom-element< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token tag punctuation" style = "color:#393A34" > < /< / span > < span class = "token tag" style = "color:#00009f" > div< / span > < span class = "token tag punctuation" style = "color:#393A34" > > < / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < / path > < / svg > < / span > < / button > < / div > < / div > < / div >
2024-04-11 12:01:20 +00:00
< p > Then< / p >
2024-05-06 08:01:08 +00:00
< div class = "language-ts codeBlockContainer_aalF theme-code-block" style = "--prism-color:#393A34;--prism-background-color:#f6f8fa" > < div class = "codeBlockContent_MHx8" > < pre tabindex = "0" class = "prism-code language-ts codeBlock_zHgq thin-scrollbar" style = "color:#393A34;background-color:#f6f8fa" > < code class = "codeBlockLines_RjmQ" > < span class = "token-line" style = "color:#393A34" > < span class = "token comment" style = "color:#999988;font-style:italic" > // This will be two elements because of the outer and inner div.< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token function" style = "color:#d73a49" > expect< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > $$< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' pierce/div' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > length< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > toBe< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token number" style = "color:#36acaa" > 2< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" style = "display:inline-block" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token comment" style = "color:#999988;font-style:italic" > // Partial piercing doesn' t work.< / span > < span class = "token plain" > < / span > < br > < / span > < span class = "token-line" style = "color:#393A34" > < span class = "token plain" > < / span > < span class = "token function" style = "color:#d73a49" > expect< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token keyword" style = "color:#00009f" > await< / span > < span class = "token plain" > page< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > $$< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token string" style = "color:#e3116c" > ' pierce/div div' < / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token plain" > length< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > .< / span > < span class = "token function" style = "color:#d73a49" > toBe< / span > < span class = "token punctuation" style = "color:#393A34" > (< / span > < span class = "token number" style = "color:#36acaa" > 0< / span > < span class = "token punctuation" style = "color:#393A34" > )< / span > < span class = "token punctuation" style = "color:#393A34" > ;< / span > < br > < / span > < / code > < / pre > < div class = "buttonGroup_Sd8_" > < button type = "button" aria-label = "Copy code to clipboard" title = "Copy" class = "clean-btn" > < span class = "copyButtonIcons_LnQD" aria-hidden = "true" > < svg viewBox = "0 0 24 24" class = "copyButtonIcon_t3l1" > < path fill = "currentColor" d = "M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z" > < / path > < / svg > < svg viewBox = "0 0 24 24" class = "copyButtonSuccessIcon_IiZV" > < path fill = "currentColor" d = "M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" > < /path
2024-06-04 08:22:15 +00:00
< h3 class = "anchor anchorWithStickyNavbar_FNw8" id = "custom-selectors-2" > Custom selectors< a class = "hash-link" aria-label = "Direct link to Custom selectors" title = "Direct link to Custom selectors" href = "/next/guides/page-interactions#custom-selectors-2" > < / a > < / h3 >
< p > Puppeteer provides users the ability to add their own query selectors to Puppeteer using < a href = "/next/api/puppeteer.registercustomqueryhandler" > Puppeteer.registerCustomQueryHandler< / a > . This is useful for creating custom selectors based on framework objects or other vendor-specific objects.< / p > < / div > < / article > < nav class = "pagination-nav docusaurus-mt-lg" aria-label = "Docs pages" > < a class = "pagination-nav__link pagination-nav__link--prev" href = "/next/guides/browser-management" > < div class = "pagination-nav__sublabel" > Previous< / div > < div class = "pagination-nav__label" > Browser management< / div > < / a > < a class = "pagination-nav__link pagination-nav__link--next" href = "/next/guides/javascript-execution" > < div class = "pagination-nav__sublabel" > Next< / div > < div class = "pagination-nav__label" > JavaScript execution< / div > < / a > < / nav > < / div > < / div > < div class = "col col--3" > < div class = "tableOfContents_IS5x thin-scrollbar theme-doc-toc-desktop" > < ul class = "table-of-contents table-of-contents__left-border" > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#locators" > Locators< / a > < ul > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#use-cases" > Use cases< / a > < / li > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#configuring-locators" > Configuring locators< / a > < / li > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#getting-locator-events" > Getting locator events< / a > < / li > < / ul > < / li > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#query-selectors" > Query Selectors< / a > < ul > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#p-selectors" > < code > P< / code > Selectors< / a > < / li > < / ul > < / li > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#query-selectors-legacy" > Query Selectors (legacy)< / a > < ul > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#css" > CSS< / a > < / li > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#built-in-selectors" > Built-in selectors< / a > < / li > < li > < a class = "table-of-contents__link toc-highlight" href = "/next/guides/page-interactions#custom-selectors-2" > Custom selectors< / a > < / li > < / ul > < / li > < / ul > < / div > < / div > < / div > < / div > < / main > < / div > < / div > < / div > < footer class = "footer footer--dark" > < div class = "container container-fluid" > < div class = "row footer__links" > < div class = "col footer__col" > < div class = "footer__title" > Community< / div > < ul class = "footer__items clean-list" > < li class = "footer__item" > < a href = "https://stackoverflow.com/questions/tagged/puppeteer" target = "_blank" rel = "noopener noreferrer" class = "footer__link-item" > Stack Overflow< svg width = "13.5" height = "13.5" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" > < / path > < / svg > < / a > < / li > < li class = "footer__item" > < a href = "https://twitter.com/chromedevtools" target = "_blank" rel = "noopener noreferrer" class = "footer__link-item" > Twitter< svg width = "13.5" height = "13.5" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" > < / path > < / svg > < / a > < / li > < li class = "footer__item" > < a href = "https://goo.gle/devtools-youtube" target = "_blank" rel = "noopener noreferrer" class = "footer__link-item" > YouTube< svg width = "13.5" height = "13.5" aria-hidden = "true" viewBox = "0 0 24 24" class = "iconExternalLink_T11m" > < path fill = "currentColor" d = "M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" > < / path > < / svg > < / a > < / li > < / ul > < / div > < / div > < div class = "footer__bottom text--center" > < div class = "footer__copyright" > Copyright © 2024 Google, Inc.< / div > < / div > < / div > < / footer > < / div >
2024-04-11 12:01:20 +00:00
< / body >
< / html >
