Ask the Community
Screenshot a single element with scope
Capture a percy snapshot of a specific element using the percySnapshot or percyScreenshot method.
Use the scope snapshot option to capture a single element instead of the full page. This approach helps you focus on specific regions and avoid dynamic sections of the page.
Percy supports scoping a single element on both Percy Web and Percy on Automate projects. Based on your created project, refer to the appropriate section:
Pass the scope option as a per-snapshot configuration, and Percy will capture only the scoped element at the given widths. The scope selector accepts any valid selector you can pass to document querySelector.
If there are multiple matching selectors on the page, Percy will select the first matching element.
Screenshot a single element using selector
Screenshot a single element using xpath
Screenshot a scrollable single element
Use cases
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:
Instead of using just .underline to select the element, you can use either specify the element type (h1 / p) or by using CSS tree-structural pseudo-classes like :last-of-type or :nth-child.
Likewise,
-
p.underlinescope selects the ‘first’ paragraph -
p.underline:last-of-typescope selects last paragraph
Selector for elements serialized by Percy
It may happen that your single-element screenshots are not working correctly with canvas/video elements.
During DOM serialization, Percy converts <canvas> and <video> elements to <img> elements. Check canvas elements in Percy’s SDK Workflow. This can cause the selector to not match, and an incorrect screenshot.
To work around this, you can use CSS tree structural pseudo-classes as suggested in the previous section.
- Instead of using
canvasorvideo, change the element toimg. - If there is only a single canvas/video tag inside
div, you can directly use.selectoras the scope.
Likewise,
-
.selector img:nth-of-type(2)scope selects the ‘second’ canvas -
.selector img:last-of-typescope selects the ‘last’ video
Usage when having Selenium's WebElement
When dealing with Web elements, you may use the below utility function that returns CSS selector i.e scope in our case, that could be easily passed to the percySnapshot function.
Make sure script eval is allowed in the test browser, Please check ref on how to verify.
Related Topics
Pass the scope option as a per-screenshot configuration, and Percy captures only the scoped element at the given widths. The scope selector accepts any valid selector you can pass to document querySelector.
- Use Percy CLI version 1.31.7 or later.
- If there are multiple matching selectors on the page, Percy selects the first matching element.
Screenshot a single element using selector
Screenshot a single element using xpath
Use cases
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:
Instead of using just .underline to select the element, you can use either specify the element type (h1 / p) or by using CSS tree-structural pseudo-classes like :last-of-type or :nth-child.
Likewise,
-
p.underlinescope selects the ‘first’ paragraph -
p.underline:last-of-typescope selects the last paragraph
Selector for elements serialized by Percy
It may happen that your single-element screenshots are not working correctly with canvas/video elements.
During DOM serialization, Percy converts <canvas> and <video> elements to <img> elements. Check canvas elements in Percy’s SDK Workflow. This can cause the selector to not match, and result in an incorrect screenshot.
To work around this, you can use CSS tree structural pseudo-classes as suggested in the previous section.
- Instead of using
canvasorvideo, change the element toimg. - If there is only a single canvas/video tag inside
div, you can directly use.selectoras the scope.
Likewise,
-
.selector img:nth-of-type(2)scope selects the ‘second’ canvas -
.selector img:last-of-typescope selects the ‘last’ video
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!