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

Setup


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);
percySnapshot(name, options);

options is an optional hash that can include:

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

Examples:

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

Configuration


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';

describeComponent(
  'meter-bar',
  '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']});

Advanced


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.

Troubleshooting


  • 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

Ember


Suggested Edits are limited on API Reference Pages

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