✨ Support multi-dom snapshots

[wwilsman]

What is this?

This PR adds support for snapshots that may have differing DOM for different widths. In order to take advantage of this new feature, snapshot uploads must be deferred using the new defer-uploads config option. This is because all snapshot resources, including multiple root resources, must be discovered before the snapshot is sent to our infrastructure to be rendered for screenshots.

Changes

To facilitate multiple root resources, each root resource is identified by their associated widths using a new for-widths attribute for snapshot resources. When uploads are deferred, new snapshots of the same name will be merged with existing snapshots. While merging, previously discovered resources are discarded if they are no longer associated with any widths. This allows retries to work with multiple DOM snapshots when the same width snapshot is taken more than once.

For the percy snapshot command, the resource capture function was adjusted to take multi DOM snapshots between resizes by keeping track of the last width before the resize took place. When additional snapshots are defined, the page is resized back to it's initial size before each additional snapshot is iterated over.

For snapshots taken by SDKs using a domSnapshot option, they can now supply a singular width option instead of an array consisting of a single width. This should allow custom snapshot functions to more easily supply the width when iterating over snapshot sizes.

Examples

Required .percy.yml config:

version: 2
percy:
  defer-uploads: true

Puppeteer example:

await page.setViewport({ ...page.viewport(), width: 600 })
await percySnapshot(page, 'Response page', { width: 600 })
await page.setViewport({ ...page.viewport(), width: 1200 })
await percySnapshot(page, 'Response page', { width: 1200 })

Cypress example:

cy
  .viewport(600)
  .percySnapshot('Responsive page', { width: 600 })
  .viewport(1200)
  .percySnapshot('Responsive page', { width: 1200 })

[Robdel12]

🏁 hell yeah. Pending passing tests of course

[djones]

🎉🎉🎉