Ember
Visual testing for Ember applications
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';
totests/helpers/start-app.js
. This registers the Percy test helpers for all acceptance tests. - Add
"globals": {"percySnapshot": true}
totests/.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 mainindex.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
Updated almost 4 years ago