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
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
yarn add -D @percy/ember
(ornpm i -D @percy/ember
)- Import
percySnapshot
in a test file:import percySnapshot from '@percy/ember';
- Use
percySnapshot
:await percySnapshot('Home page');
- 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 mainindex.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'
becomesimport percySnapshot from '@percy/ember';
). - Related to the above, the package name has changed to
@percy/ember
. - You need to prepend the
ember test
command withpercy exec --
now (percy exec -- ember test
) - You must use
await
withpercySnapshot
(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 withpercy exec
now)- The
scope
option no longer accepts an element object, only a string of the selector.
Updated about 1 year ago