Ember

👍

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 3.0.0 or later. Previous versions of @percy/ember are incompatible with what is described in this document. v2 docs can be found here

Install @percy/cli and @percy/ember

$ npm install --save-dev @percy/cli @percy/ember

Usage

This is an example using the percySnapshot function.

import percySnapshot from '@percy/ember';

describe('My ppp', () => {
  // ...app setup

  it('about page should look good', () => {
    await visit('/about');
    await percySnapshot('My Snapshot');
  });
});

Running the test above directly will result in the following logs:

$ ember test
...
[percy] Percy is not running, disabling snapshots
...

When running with percy exec, and your project's PERCY_TOKEN, a new Percy build will be created and snapshots will be uploaded to your project.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- ember test
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Running "ember test"
...
[percy] Snapshot taken "My Snapshot"
...
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Configuration

percySnapshot(name[, options])

• name (required) - The snapshot name; must be unique to each snapshot
• options - See per-snapshot configuration options

Automatic snapshot names

The name argument can optionally be provided as QUnit.assert or an instance of Mocha.Test which will automatically generate a snapshot name based on the full test name.

❗️

Important: Snapshot names must be unique. If you have multiple tests with the same title, or call percySnapshot multiple times inside a single test, you must provide a unique name.

QUnit

describe('Acceptance: My app', () => {
  // ...app setup

  describe('About page', () => {
    test('should look good', () => {
      await visit('/about');
      await percySnapshot(assert);
      // => Snapshot taken: "Acceptance: My app | About page | should look good"
    });
  });
});

Mocha

describe('Acceptance: My app', () => {
  // ...app setup

  describe('about page', () => {
    it('should look good', () => {
      await visit('/about');
      await percySnapshot(assert);
      // => Snapshot taken: "Acceptance: My app about page should look good"
    });
  });
});

Global configuration

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

Troubleshooting

Content inserted outside of #ember-testing

Percy's SDKs work by cloning the DOM of the application. Since Ember's test harness renders the application in the same DOM as the test result UI, the Percy Ember SDK has to do a little work to remove the test UI from the DOM. Without doing this, the test result UI would be the screenshot.

Due to this DOM modification, you will need to make sure any external assets or content is included inside of the #ember-testing div (the root of the Ember application).

Upgrading

Automatically with @percy/migrate

We built a tool to help automate migrating to the new CLI toolchain! Migrating can be done by running the following commands and following the prompts:

$ npx @percy/migrate
? Are you currently using @percy/ember? Yes
? Install @percy/cli (required to run percy)? Yes
? Migrate Percy config file? Yes
? Upgrade SDK to @percy/[email protected]? Yes

This will automatically run the changes described below for you.

Manually

Installing @percy/cli

If you're coming from a pre-3.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

$ npm install --save-dev @percy/cli

Migrating Config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate

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.