How to pierce nested iframes and native Shadow DOM using Puppeteer text selectors?

02:17 29 May 2026

I am building an automated integration testing tool in Node.js using Puppeteer to interact with a third-party dashboard. The platform relies heavily on nested </code> structures, and inside those iframes, the components are encapsulated within native open Shadow DOMs.</p> <p>The problem is that I need to query and click a specific action button based solely on its visible text content because its class names and IDs are dynamically randomized on every session layout render (standard utility-first framework / Tailwind mess).</p> <p>According to the modern Puppeteer docs, the native text search engine (<code>::-p-text</code>) or ARIA selectors should handle deep queries. However, when trying to chain them across an iframe boundary and into a shadow root, the selector engine continuously returns null or throws a timeout exception.</p> <p>Here is the minimal reproducible version of my script layout:</p> <p>JavaScript</p> <pre><code>const puppeteer = require('puppeteer'); async function run() { const browser = await puppeteer.launch({ headless: true }); const page = await browser.newPage(); // URL anonymized for client privacy, but it's a standard internal corporate SPA dashboard await page.goto('https://internal-client-dashboard.local/analytics', { waitUntil: 'domcontentloaded' }); try { // 1. Locate and get the iframe handle const iframeElement = await page.waitForSelector('iframe#sub-dashboard'); const frame = await iframeElement.contentFrame(); // 2. Attempt to penetrate the Shadow DOM inside that frame using text selectors // This fails consistently with a TimeoutError const targetButton = await frame.waitForSelector('div >>> ::-p-text(Confirm Settings)'); await targetButton.click(); console.log('Button clicked successfully'); } catch (err) { console.error('Execution failed:', err.message); } finally { await browser.close(); } } run(); </code></pre> <p>What I have tried so far:</p> <ul> <li><p>Chaining the deep combinator directly like <code>iframe#sub-dashboard >>> div >>> ::-p-text(...)</code> from the root page context, but Puppeteer doesn't seem to resolve cross-frame boundaries automatically this way.</p> </li> <li><p>Executing an internal <code>page.evaluate()</code> running standard native <code>shadowRoot.querySelector()</code>. This works but it completely bypasses Puppeteer's native driver-level abstraction and <code>waitForSelector</code> auto-waiting benefits, making the execution extremely flaky.</p> </li> </ul> <p>What is the standard syntax in modern Puppeteer to pierce through an iframe context down into a nested Shadow DOM component using semantic text engines? I want to avoid resorting to messy un-awaited query selector loops inside an execution context evaluation if possible. Any ideas?</p> </div> </div> <div class="tags"> <span class="tag">javascript</span> <span class="tag">node.js</span> <span class="tag">iframe</span> <span class="tag">puppeteer</span> <span class="tag">shadow-dom</span>   </div> </div>  <div id="addAnswerSection" class="add-answer" style="display: none;"> <h4>Your Answer</h4> <form> <div class="mdl-textfield mdl-js-textfield"> <textarea class="mdl-textfield__input" rows="4" id="answer" ></textarea> <label class="mdl-textfield__label" for="answer">Write your answer...</label> </div> <button type="submit" class="mdl-button mdl-js-button mdl-button--raised submit-btn" > Submit Answer </button> </form> </div>  <div id="loginPrompt" class="login-prompt" style="display: none;"> <i class="material-icons" style="font-size:40px;color:#3f51b5;">lock_outline</i> <p>You need to log in to submit an answer.</p> <button class="mdl-button mdl-js-button mdl-button--raised mdl-button--colored"> Log In </button> </div> </div>  </div> <style> code{ background-color: #000; color:#0FF; border-radius:8px; } .o-q-answer{ background-color:#eee; padding:48px; border-radius:24px; margin:24px; } .o-q-question{ background-color:#ddd; padding:48px; border-radius:24px; margin:24px; } </style>  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script> <script> // Highlight all <pre><code> blocks automatically document.addEventListener("DOMContentLoaded", () => { document.querySelectorAll('pre code, code').forEach(block => { hljs.highlightElement(block); // highlight.js detects language automatically }); }); </script> <script> // Simulated login flag const isLoggedIn = false; // change to true to simulate logged-in state const addAnswerSection = document.getElementById("addAnswerSection"); const loginPrompt = document.getElementById("loginPrompt"); if (isLoggedIn) { addAnswerSection.style.display = "block"; } else { loginPrompt.style.display = "block"; } </script> </main> <aside class="sidebar"> <div class="card"> <h4>Newsletter</h4> <p class="muted">Subscribe for updates</p> <form style="display:flex; gap:8px; margin-top:8px; flex-wrap:wrap;" onsubmit="event.preventDefault(); alert('Subscribed!');"> <input type="email" placeholder="you@company.com" required style="flex:1; padding:10px; border-radius:8px; border:1px solid #e6e9ef;"> <button class="btn-primary" type="submit">Subscribe</button> </form> </div> <div style="height:20px"></div> <div class="card"> <h4>Advertisement</h4> <div class="ad"> <style> .prct-ad { width:250px; height:250px; font-family:'Inter',Arial,sans-serif; background:linear-gradient(180deg,#ffffff 0%,#f3f7fb 100%); border:1px solid #e0e0e0; border-radius:10px; box-shadow:0 3px 8px rgba(0,0,0,0.05); overflow:hidden; display:flex; flex-direction:column; justify-content:space-between; padding:14px; box-sizing:border-box; text-decoration:none; color:#222; } .prct-header { color:#1976d2; font-weight:700; font-size:18px; margin-bottom:4px; text-align:center; } .prct-title { font-size:15px; font-weight:600; color:#0b2540; margin-bottom:6px; text-align:center; line-height:1.2; } .prct-text { font-size:12px; color:#555; line-height:1.4; margin-bottom:8px; text-align:center; } .prct-list { list-style:none; padding:0; margin:0 0 10px 0; } .prct-list li { font-size:12px; color:#2f3c48; position:relative; padding-left:14px; margin-bottom:4px; } .prct-list li::before { content:''; position:absolute; left:0; top:6px; width:6px; height:6px; background:#1976d2; border-radius:50%; } .prct-cta { display:block; width:100%; text-align:center; background:#1976d2; color:#fff; text-decoration:none; font-weight:600; font-size:13px; padding:8px 0; border-radius:6px; box-shadow:0 3px 8px rgba(25,118,210,0.2); transition:background 0.2s ease,transform 0.2s ease; margin-top:6px; } .prct-cta:hover { background:#1565c0; transform:translateY(-1px); } .prct-footer { font-size:11px; color:#555; display:flex; justify-content:space-between; align-items:center; margin-top:10px; } .prct-url { font-weight:600; color:#0b2540; font-size:11px; } </style> <a class="prct-ad" href="https://play.google.com/store/apps/details?id=com.offlinew.android" target="_blank" rel="noopener noreferrer"> <div> <div class="prct-header">OffLine</div> <div class="prct-title">Watch Videos — No Internet</div> <div class="prct-text">Enjoy trending videos, watch offline anytime. Create, share & stay entertained — even when you’re offline.</div> <ul class="prct-list"> <li>Watch without internet connection</li> <li>Create & share your videos</li> <li>Fast, smooth & high-quality</li> </ul> <span class="prct-cta">Download Now</span> </div> <div class="prct-footer"> <span>No signup needed</span> <span class="prct-url">offlinew.com</span> </div> </a></div> </div> </aside> </div> <footer class="site-footer"> <div class="links"> <a href="https://offlinew.com/p/terms_of_use">Terms</a> <a href="https://offlinew.com/p/privacy_policy">Privacy</a> <a href="https://offlinew.com/practica/contact_us.php">Support</a> </div> <div style="margin-top:10px; font-size:0.9rem; opacity:0.85;">© 2025 OffLinew — All rights reserved</div> </footer> </div> <div id="gdpr-consent"> <h3>Privacy & Cookie Consent</h3> <p>We use cookies to ensure the best experience on our website. This includes analytics, personalization, and marketing purposes. Some cookies are essential for the website to function properly.</p> <p>By clicking "Accept", you consent to our use of cookies. You can read more about how we use cookies and how you can change your preferences in our <a href="https://offlinew.com/privacy-policy.html">Privacy Policy</a>.</p> <div class="buttons"> <button class="decline">Decline</button> <button class="accept">Accept</button> </div> </div> <script> const consentBox = document.getElementById('gdpr-consent'); const acceptBtn = consentBox.querySelector('.accept'); const declineBtn = consentBox.querySelector('.decline'); // Check if consent is already given if (localStorage.getItem('gdpr-consent') == 'accepted') { consentBox.style.display = 'none'; } acceptBtn.addEventListener('click', () => { localStorage.setItem('gdpr-consent', 'accepted'); consentBox.style.display = 'none'; // Here you can initialize analytics or other cookie-dependent scripts }); declineBtn.addEventListener('click', () => { localStorage.setItem('gdpr-consent', 'declined'); consentBox.style.display = 'none'; // Optionally, prevent non-essential cookies from being set }); </script> </body> </html>