Screenshot a single element

👍

Covered in this doc

  • How to scope a screenshot to a single element

📘

Requires @percy/cli v1.3.0+

Sometimes capturing a full-page screenshot isn't necessary. For example, if there are dynamic parts of the page that you don't need to test or are only interested in a very specific region to test. For these cases, you can pass a scope snapshot option and Percy will only capture the scoped element on the given widths. This can be passed as a global snapshot option or as a per-snapshot option.

The scope selector accepts any valid selector you would be able to pass to document.querySelector.

🚧

If there are multiple matching selectors on the page, Percy will select the first matching element.

Global example:

version: 2
snapshot:
    scope: '.selector'

The specific syntax used for this will vary based on your SDK, but the same concept applies. Per-snapshot example:

percySnapshot('name', { scope: '.selector' });
percySnapshot(driver, 'name', { scope: '.selector' });
Percy.snapshot(driver, 'name', { scope: '.selector' })
percy_snapshot(driver=driver, name='name', scope='.selector');

Multiple elements with the same selector


If you would like to scope a screenshot to a specific element that has the same matching selector as other elements on the page you'll have to get more specific with your selector. This can be done by either adding another unique selector to that element or by using standard CSS selectors to get more specific. This is the same way you would write CSS -- Percy doesn't add anything to this process.

For example, given the below DOM:

<html>
  <head>
    <title>Example</title>
  </head>
  <body>
    <h1 class="underline">My example</h1>
    <p class="underline">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas tristique convallis sem, vitae sodales risus accumsan in</p>
    <p class="underline">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas tristique convallis sem, vitae sodales risus accumsan in</p>
  </body>
</html>

Instead of using just .underline to select the element, you would want to either specify the element type (h1 / p) or by using CSS tree-structural pseudo-classes like :last-of-type or :nth-child.

percySnapshot(driver, 'name', { scope: 'h1.underline' }); // selects the h1
percySnapshot(driver, 'name', { scope: 'p.underline' }); // selects the first paragraph
percySnapshot(driver, 'name', { scope: 'p.underline:last-of-type' }); // selects last paragraph