Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Percy specific CSS

ūüĎć

Covered in this doc

How to apply Percy-specific CSS to ignore areas from being rendered by Percy
Percy-specific CSS for Storybook

Percy provides a powerful way to take control of rendering to do whatever you want -- ignore regions, stabilize dynamic elements, etc.

Percy's way to do this is something we call "Percy-specific CSS", which is only applied in the Percy rendering environment. You can use any CSS and it'll only be rendered in Percy's rendering environment. This can be very helpful for ignoring regions, hiding areas that produce false-positive visual diffs, or when you'd like more specific control over the state of UI elements like visualizations and animations.

Percy-specific CSS


You can apply Percy specific CSS in most SDKs without editing your site or applications CSS files. This can be done by passing a percyCSS option via the options object. For example:

await percySnapshot('Home page', { 
  percyCSS: `iframe { display: none; }` 
});

You can also configure global Percy CSS via the .percy.yml file:

version: 1
snapshot:
  percy-css: | 
    iframe { 
      display: none; 
    }

This requires @percy/agent v0.13.0+ to work. You can check which version of @percy/agent you have by running npm ls @percy/agent in your project.

Hiding regions with Percy-specific CSS


You can do so using the @media only percy CSS media query. CSS that is nested under this media query will only apply in Percy and will not affect your normal pages outside of Percy.

For example, you might have an element that renders differently each time and you want Percy to ignore that element. You can use Percy specific styles to achieve this.

Let's say you want to apply a hide-in-percy class to elements you want hidden in Percy. Here's how you can do that:

@media only percy {
  .hide-in-percy {
    visibility: hidden;
  }
}

And your page would have HTML like this:

<div class="hide-in-percy">an element we know we want to ignore in visual tests</div>

The class names don't have to be Percy specific, you can put any normal CSS selectors and rules that you want in the media query and they will only be applied when rendering in Percy.

Percy-specific CSS for Storybook


When using Storybook, you can use a similar, but slightly modified approach. Percy uses a content-type -based system to apply styles to HTML and CSS files, and CSS-in-JS breaks this paradigm.

In order to render Percy-specific styles for Storybook snapshots, you need to modify the Storybook's preview-head.html file to serve static CSS overrides. See the storybook documentation for how to add custom head tags to your project. Here's an example of a preview-head.html file that includes a default stylesheet, and adds a .hide-in-percy class styling:

<link rel="stylesheet" type="text/css" href="default.css">

<style>
@media only percy {
  .hide-in-percy {
    visibility: hidden;
  }
}
</style>

You would then add a percy-specific className attribute to your component the example show className as per React syntax:

<div className="hide-in-percy">
  <img src="https://i.giphy.com/bcKmIWkUMCjVm.gif" alt="Bom dia"/>
</div>

You can see a complete example of this technique in this pull request.

Debugging Percy-Specific CSS

It may be helpful to render your storybook project to a static build in order to debug any changes. See the Storybook documentation for details on how to do this. Once you have generated a static version of your app, you can remove the surrounding @media only percy block in the markup to preview your Percy-specific styles in your browser.

Updated 10 months ago

Percy specific CSS


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.