Shadow DOM


Covered in this doc

  • How to configure Percy to capture Shadow DOM


Percy now supports capturing Shadow DOM. It's a technology for creating scoped DOM (Document Object Model) trees in web browsers. It enables developers to create a separate DOM tree for a web component, which is then attached to the main DOM tree as a shadow root. This shadow root acts as an encapsulation boundary for the component's internal DOM structure and style, hiding it from the rest of the page. Shadow DOM allows developers to build reusable and modular components for the web.


Shadow root needs to be open, closed shadow root cannot be captured.



  • Requires @percy/cli v1.19.2+
  • Test Browser needs to be chromium v90+

How to install Percy CLI specific version?

npm install @percy/[email protected]
  • Make sure you are using Percy CLI v1.15+ version before upgrading to Percy CLI v1.19.2+.
  • If you are using the older Percy Agent, then it's recommended to upgrade to the latest CLI before trying the alpha release. Refer Percy CLI migration doc to migrate to latest Percy CLI.

How to configure chromium as your test browser?


You can learn more about how to set chromium browsers in Cypress config.

cypress run --browser chromium


// ...
let browser = await chromium.launch();
let page = await browser.newPage();
await page.goto('', { waitUntil: 'networkidle' });
await percySnapshot(page, 'Example Snapshot');

await browser.close();
// ...

Selenium (Java)

// ...
ChromeOptions options = new ChromeOptions();
driver = new ChromeDriver(options);
percy = new Percy(driver);

percy.snapshot("Example snapshot");
// ...

Selenium (JavaScript)

// ...
let driver = new Builder()
     .setChromeOptions(new chrome.Options().headless())

await driver.get("")
await percySnapshot(driver, 'Example snapshot');
// ...