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 >= 8.2.0. Requires ember-cli >= 1.13.13, preferably >= 2.4.0.

  1. ember install ember-percy
  2. Import percySnapshot in a test file: import { percySnapshot } from 'ember-percy';
  3. Use percySnapshot: await percySnapshot('Home page');
percySnapshot(name, options);

options is an optional hash that can include:

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


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


Autogenerated name for Mocha tests

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

await percySnapshot(this.test);

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:

await percySnapshot(assert);

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

Acceptance test example

import { percySnapshot } from 'ember-percy';
import { click, visit } from '@ember/test-helpers';

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

    await click('#person1');
    await percySnapshot('about page (person details)');

Component integration test example

import { percySnapshot } from 'ember-percy';

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

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

      this.set('count', 100);
      await 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 adjustments. Be sure to read through how to setup Parallel test suites with Percy.


  • 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.

Updated about a month ago

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.