ember-percy on GitHub

Ember addon for visual testing with Percy.

Installation

📘
Make sure you have completed Setup of your CI service first. You can also test Percy in your local development environment.

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

ember install ember-percy

For Ember version >= 3.x

ember install ember-percy
import { percySnapshot } from 'ember-percy'; in any acceptance or integration test.
await percySnapshot(name, options)

For Ember version < 3.x

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

Usage

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:

percySnapshot('homepage');

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

Autogenerated name for Mocha tests

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

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:

percySnapshot(assert);

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() {
    visit('/about');
    percySnapshot('about page');

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

Component integration test example

import { percySnapshot } from 'ember-percy';

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

Freezing time and dynamic data

As you start to introduce visual testing into your workflow, you might find that the passing of time or generated data from tools like faker can cause visual diffs.

It's fairly easy to stabilize these diffs. Tools like faker often allow you to provide a seed to ensure that the same data is generated each time faker is run. Libraries like ember-mockdate-shim allow you to override the current date, eliminating variations due to the screenshots being taking at a different date and time. If you use Math.random, you can seed it with seedrandom.

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 email your Ember Exam configuration to [email protected], and we will advise how to get Percy running.

Responsive visual diff setup

You can use Percy responsive visual diffs to test at different CSS breakpoints.

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']});

Source code integration

Percy automatically integrates with your source code so you can do visual reviews with each commit or pull request. See our source code integration docs for more info.

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.

Other resources

EmberSF meetup video: Continuous Visual Integration for Ember by Mike Fotinakis
EmberScreencasts video: Introduction to Visual Regression Testing

Contributing

Fork it ( https://github.com/percy/ember-percy/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new pull request

Throw a ★ on it!