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!

Covered in this doc

Installing Percy's Ember addon
Add Percy snapshots to your Ember app for visual testing
Configure your snapshots and test set up to meet your needs

ember-percy on GitHub

Package Status Build Status


If you're not ready to integrate Percy, check out our 2-minute Ember tutorial and example app with Percy already added.

Requires Node >= 0.12.0. Requires ember-cli >= 1.13.13, preferably >= 2.4.0.

  1. ember install ember-percy
  2. Add import './percy/register-helpers'; to tests/helpers/start-app.js. This registers the Percy test helpers for all acceptance tests.
  3. Add "globals": {"percySnapshot": true} to tests/.eslintrc to avoid "percySnapshot is not defined" errors.
percySnapshot(name, options);

options is an optional hash that can include:

  • scope: A CSS selector or element to snapshot. Defaults to the full page.


percySnapshot('homepage', {scope: '#header'});


Autogenerated name for Mocha tests

You can pass this.test to autogenerate the snapshot name, for example:


This will automatically name the snapshot from the test title, like "Acceptance: Marketing pages can visit /about".

Autogenerated name for QUnit tests

You can pass the assert object to autogenerate the snapshot name, for example:


This will automatically name the snapshot from the test title, like "Acceptance | Marketing pages | can visit /about".

Acceptance test example

describe('Acceptance: Marketing pages', function() {
  it('can visit /about', function() {
    percySnapshot('about page');

    percySnapshot('about page (person details)');

Component integration test example

import { percySnapshot } from 'ember-percy';

  'Integration: MeterBarComponent',
    integration: true
  function() {
    it('renders', function() {
      this.set('count', 0);
      this.render(hbs`{{meter-bar count=count total=100}}`);
      percySnapshot('meter bar zero');

      this.set('count', 50);
      percySnapshot('meter bar half');

      this.set('count', 100);
      percySnapshot('meter bar full');

Responsive snapshot configuration

You can use Percy's responsive visual testing to test at different breakpoint widths.

In your app's config/environment.js:

if (environment === 'test') {
  // ...
  ENV.percy = {
    breakpointsConfig: {
      mobile: 375,
      tablet: 768,
      desktop: 1280
    defaultBreakpoints: ['mobile', 'desktop']

With the above configuration, all snapshots will render at both the mobile and desktop breakpoints by default.

You can override this on a per-snapshot basis by passing the breakpoints option to percySnapshot(). For example:

// Desktop-only snapshot:
percySnapshot('meter bar full', {breakpoints: ['desktop']});


Separate build and test steps

If you're running your ember tests with the --path flag to test an app pre-built with ember build -o, you may need to modify your commands to ensure the test environment is setup correctly.

In your ember build command, use the --environment=test flag:

ember build --environment=test -o dist

Run your ember test command with the EMBER_ENV variable set to test:

EMBER_ENV=test ember test --path=dist

Ember Exam

If you use Ember Exam (ember-exam) your Percy setup may require custom adjustments. Please reach out to support with your Ember Exam configuration and we will advise you how to get Percy running.


  • Missing fonts in Percy? Make sure that your tests/index.html mirrors your main index.html file. You should include any fonts or external stylesheets in both places.

What's next

Once you've installed Percy for Ember and added snapshots to your tests, the next step is to add Percy to your CI service.

CI service overview


Suggested Edits are limited on API Reference Pages

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