Ember v2

👍

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

@percy/ember on GitHub

Setup

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

📘

These docs apply to version 2.x. Other versions of @percy/ember are incompatible with what is described in this document.

Requires Node >= 10.0.0. Requires ember-cli >= 2.4.0

1. yarn add -D @percy/ember (or npm i -D @percy/ember)
2. Import percySnapshot in a test file: import percySnapshot from '@percy/ember';
3. Use percySnapshot: await percySnapshot('Home page');
4. Wrap your ember test command with percy exec: npx percy exec -- ember test

await percySnapshot(name);
await percySnapshot(name, options);

options is an optional hash that can include:

• widths: An array of integers representing the browser widths at which you want to take snapshots.

• minHeight: An integer specifying the minimum height of the resulting snapshot, in pixels. Defaults to 1024px.

• percyCSS: A string containing Percy specific CSS that will be applied to this snapshot.

• requestHeaders: An object containing HTTP headers to be sent for each request made during asset discovery for this snapshot.

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

For example:

await percySnapshot('Homepage test');
await percySnapshot('Homepage responsive test', { widths: [768, 992, 1200] });
await percySnapshot('Percy CSS', { percyCSS: ".example-selector { color: blue }" });

Global configuration

You can also configure Percy to use the same options over all snapshots. To see supported configuration including widths read our global SDK configuration docs

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 '@percy/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 '@percy/ember';

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

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.

Upgrading from V1

The 2.x version of the Ember SDK doesn't change the percySnapshot function signature, but as with any major version bump, it carries breaking changes.

v2.x is a complete rewrite to bring it inline with how all other Percy SDKs function now (by utilizing @percy/agent for the heavy lifting)

Breaking changes

• Import API changes: percySnapshot is now the packages default export (import { percySnapshot } 'ember-percy' becomes import percySnapshot from '@percy/ember';).
• Related to the above, the package name has changed to @percy/ember.
• You need to prepend the ember test command with percy exec -- now (percy exec -- ember test)
• You must use await with percySnapshot (or ensure the promise resolves, to make sure your snapshots are as stable as possible)
• breakpointsConfig is no longer going to work -- we're not hooking into the Ember build pipeline to gather config objects. Use a Percy config file instead.
• PERCY_PARALLEL_TOTAL might need to be adjusted if you're using Ember Exam. Now most exam builds will only create one Percy build (since we wrap the test command with percy exec now)
• The scope option no longer accepts an element object, only a string of the selector.