Capturing responsive DOM snapshots

👍

Covered in this doc

• What responsive DOM snapshots are
• How Percy's SDKs work at a high level
• Examples in various testing frameworks

Overview

If your application changes the DOM state based on viewport size, you can configure Percy’s SDKs to account for that. To understand why this might be needed, you have to know Percy snapshots work. At a high level, Percy works by capturing a snapshot of the DOM in the test browser. Percy will serialize any in memory DOM state at that moment. For more information, see the Debugging SDKs document.

Given that, if your application changes anything in the DOM between screen sizes, you will need to resize your test browsers viewport and capture a snapshot at that width.

Examples

📘

This feature requires v1.11.0+ of Percy CLI to work

Snapshot names must be unique and normally an error is thrown when attempting to take multiple snapshots with the same name. This is because snapshots begin processing as soon as they're uploaded to Percy. To allow taking multiple DOM snapshots with the same name at varying widths, you will need to tell Percy's SDKs to defer snapshot uploads. This can be done in the Percy config file. For example, as a .percy.yml file:

version: 2
percy:
  defer-uploads: true

This option tells the SDK to defer uploading snapshots until the very end of the test suite. This allows many snapshots with the same name AND different widths to be merged together. All that's needed now is to update your tests to resize your test browsers viewport and capture multiple snapshots across those varying widths.

🚧

Since snapshots of the same name will be merged, taking multiple snapshots with the same name and same width(s) will result in only the last one being uploaded.

Cypress

it('example test', function() {
  // ...
  // https://docs.cypress.io/api/commands/viewport.html#Syntax
  cy
	  .viewport(768, 1024)
	  .percySnapshot('Home page', { width: 768 })
	  .viewport(1280, 1024)
	  .percySnapshot('Home page', { width: 1280 });
  // ...
});

Playwright or Puppeteer

it('example test', async () => {
  // ...
  await page.setViewport({ width: 768, height: 1024 }); 
  await percySnapshot(page, 'Home Page', { width: 768 });

  await page.setViewport({ width: 1280, height: 1024 });
  await percySnapshot(page, 'Home Page', { width: 1280 });
  // ...
});

Selenium (JavaScript)

it('example test', async () => {
  // ...
  await driver.manage().window().setSize(768, 1024);
  await percySnapshot(driver, 'Home Page', { width: 768 });

  await driver.manage().window().setSize(1280, 1024);
  await percySnapshot(driver, 'Home Page', { width: 1280 });
  // ...
});

Selenium (Ruby)

it 'example test' do
  # ...
  driver.manage.window.resize_to(768, 1024)
  percy_snapshot(driver, 'Home Page', { width: 768 })

  driver.manage.window.resize_to(1280, 1024)
  percy_snapshot(driver, 'Home Page', { width: 1280 })
  # ...
end