Sign in or start for free
Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

### [ember-percy on GitHub](🔗)

[![Package Status](https://img.shields.io/npm/v/ember-percy.svg)](🔗) [![Build Status](https://travis-ci.org/percy/ember-percy.svg?branch=master)](🔗)

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.

  1. `ember install ember-percy`

For Ember version >= 3.x

  1. `ember install ember-percy`

  2. `import { percySnapshot } from 'ember-percy';` in any acceptance or integration test.

  3. `await percySnapshot(name, options)`

For Ember version < 3.x

  1. `ember install ember-percy`

  2. Add `import './percy/register-helpers';` to `tests/helpers/start-app.js`. This registers the Percy test helpers for all acceptance tests.

  3. Add `"globals": {"percySnapshot": true}` to `tests/.eslintrc` to avoid "percySnapshot is not defined" errors.

# Usage



`options` is an optional hash that can include:
  • `scope`: A CSS selector or element to snapshot. Defaults to the full page.
Examples:


## Autogenerated name for Mocha tests
You can pass `this.test` to autogenerate the snapshot name, for example:

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:

This will automatically name the snapshot from the test title, like _"Acceptance | Marketing pages | can visit /about"_.
## Acceptance test example

## Component integration test example

# 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:

Run your `ember test` command with the `EMBER_ENV` variable set to test:

# 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`:

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:

# 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.
  • [GitHub](🔗) 
  • [GitHub Enterprise](🔗) 
  • [GitLab](🔗) 
  • [GitLab self-managed](🔗) 
  • [Bitbucket](🔗) 
# 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

  1. Fork it ( <https://github.com/percy/ember-percy/fork> )
  2. Create your feature branch (`git checkout -b my-new-feature`)
  3. Commit your changes (`git commit -am 'Add some feature'`)
  4. Push to the branch (`git push origin my-new-feature`)
  5. Create a new pull request
[Throw a ★ on it!](🔗)