[ci-img]: https://travis-ci.org/ciena-blueplanet/ember-cli-visual-acceptance.svg?branch=master "Travis CI Build Status"
[ci-url]: https://travis-ci.org/ciena-frost/ember-cli-visual-acceptance
[cov-img]: https://img.shields.io/coveralls/ciena-frost/ember-cli-visual-acceptance.svg "Coveralls Code Coverage"
[cov-url]: https://coveralls.io/github/ciena-frost/ember-cli-visual-acceptance
[npm-img]: https://img.shields.io/npm/v/ember-cli-visual-acceptance.svg "NPM Version"
[npm-url]: https://www.npmjs.com/package/ember-cli-visual-acceptance
[observer-img]: https://emberobserver.com/badges/ember-cli-visual-acceptance.svg "Ember Observer Score"
[observer-url]: https://emberobserver.com/addons/ember-cli-visual-acceptance
[![Observer][observer-img]][observer-url] [![Travis][ci-img]][ci-url] [![NPM][npm-img]][npm-url]

ember-cli-visual-acceptance

Create baseline images and test for CSS regression during standard Ember tests using html2Canvas and ResembleJS

Installation

ember install ember-cli-visual-acceptance

$3

#### Custom Image upload
There are many cases where you don't want to use Imgur (such as repo's on Github enterprise). So in your ember-cli-build.js you have the ability to utilize your own upload function.
``javascript
upload: function (image, index, req, options) {
let result = 'foobar-image-url'
console.log('We using me for images w/ result: ', result)
return result
}
`
The return value should be the url where the image is hosted.
The parameters are as follows:
* image: The base64 string of the image to upload
* index: The index of the current image that relates to (Diff, Current, Baseline)
* req: the request object from the middleware
* options: the visualAcceptanceOptions in ember-cli-build.js
#### Location of saved images

You can specify the location where the saved images will be stored (do not store under tests directory). Include the following in your ember-cli-build.js:


`javascript
visualAcceptanceOptions: {
imageDirectory: ''
}
`

$3

#### NightmareJS(Electron)

NightmareJS is a new addition to ember-cli-visual-acceptance. NightmareJS is run on top of Electron, using Electron to take the capture. This capture should provide the most accurate representation of your app.

##### Notes

* If the image capture is an empty file or distorted image you should try extending the viewport in vendor/nightmarejs-launcher.js the viewport currently set to .viewport(3000, 4000) which should be ample room (but the more tests you have the longer the page will grow). The distortion/emptiness of the image is caused by the captured area not being visible on Electron.

#### PhantomJS - SlimerJS

PhantomJS and SlimerJS can both be used with this tool to capture images.

Personally I prefer SlimerJS. As PhantomJS's webkit version is behind the latest Safari's webkit. While SlimerJS uses the same version of Gecko as the latest Firefox.

##### Warning

With certain repositories I've had trouble with SlimerJS having segmentation faults on both Linux and Mac. I've yet to resolve this issue. So I have re-included html2Canvas work.

#### Html2Canvas

Html2Canvas is used when a browser does not have the function window.callPhantom (Only PhantomJS and SlimerJS have this defined). Html2Canvas is still in beta and as result you will see some issues.
Html2Canvas relies on Canvas drawing support. I find Chrome has the best Canvas drawing support (miles ahead of their competitors), while Firefox has the second best Canvas drawing support.

##### SVGs

Html2Canvas has difficulties rendering SVGs (more so in Firefox than in Chrome). As a result I have added a new expermental functionality that attempts to render the svgs better.
You can use this experimental feature by setting experimentalSvgs to true (Example: capture('svg-experimental', null, null, null, true))

#### Target browser and OS version

You can specify the exact version of the browser as well as the OS the test will be run against.

- install ember-cli-visual-acceptance
- run ember test -s (this will launch a browser)
- open the console and type window.ui


To target specific versions, you can edit ember-cli-build.js as follows:

`javascript
visualAcceptanceOptions: {
targetBrowsers: [{
browser: "Chrome",
os: "Mac OS X",
osversion: "10.11.2",
version: "49.0.2623.112"
}]
}
`

Also, rather then specifying exact version for the browser and the OS versions ,you can append >= as follows:

`javascript
visualAcceptanceOptions: {
targetBrowsers: [{
browser: "Chrome",
os: "Mac OS X",
osversion: ">=10.11.2",
version: ">=49.0.2623.112"
}]
}
`
You can also omit the osversion and version if not needed.

API

`javascript
capture (imageName, options)
`


| Name | Type | Default | Description |
|--------------------------|--------|---------------------|---------------------------------------|
| imageName | string | required | Name of the image you wish to save |
| options | object | {} | Object that holds all the options for the capture |
| options.width | number | null | Define the width of the canvas in pixels. If null, renders with full width of the targetElement. |
| options.height | number | null | Define the height of the canvas in pixels. If null, renders with full height of the targetElement. |
| options.misMatchPercentageMargin | float | 0.00 | The maximum percentage ResembleJs is allowed to misMatch. |
| options.targetElement | HTMLElement | ember-testing-container | DOM element to capture (Most likely want to set height and width to null, so we don't overwrite the element's height and width )|
| options.experimentalSvgs | boolean | false | Set to true in order try experimental rendering of svgs using html2canvas.|
| options.assert | object | undefined | Only use to pass in Qunit assert object.|




Usage

* Configure the systems and browsers that will capture images in your ember-cli-build.js as described above in the Configuration section.
* Different systems and browsers produce different images
* To prevent false positives images are only captured against specific targets
* The results of each target are stored in separate directories and are only compared against the same target

* Create your tests (ex: tests/integration/components/frost-button-test.js)

`javascript
it ('primary small button', function(done) {
this.render(hbs
{{frost-button
priority='primary'
size='small'
text='Text'
}})
capture('primary-small-button', done)
})
`

* Run ember test -s

$3

* The first capture will automatically become the baseline image.
* To create a new baseline, run the following:

ember new-baseline




$3


From ember test:
`
Integration: FrostSelectComponent selects the hovered item when enter is pressed
✘ Image is above mismatch threshold.: expected false to be true
AssertionError: Image is above mismatch threshold.: expected false to be true
`

Then a new -fail.png will show up in your visual-acceptance directory.
Visual differences are shown in pink.
More info about visual diffs can be found here.
ember-cli-visual-acceptance only uses the .scaleToSameSize() option for ResembleJS

$3

#### Without done() callback
`javascript
it('supports placeholder', function () {
const $input = this.$('.frost-select input')
expect($input.attr('placeholder')).to.eql('Select something already')
return capture('placeholder')
})
`

#### With done() callback
`javascript
it('selects the hovered item when enter is pressed', function (done) {
keyUp(dropDown, 40)
keyUp(dropDown, 13)

Ember.run.later(() => {
let dropDownInput = this.$('.frost-select input')
let value = dropDownInput.val()
expect(value).to.eql(props.data[0].label)
capture('Boston', done, { width: 1920, height: 1080, misMatchPercentageMargin: 5.00})
})
})
`


Working with Mirage


ember-cli-visual-acceptance makes api calls to it's own testem middleware. So in order for the tests to work you must have this.passthrough(), or list the paths explicitly in this.passthrough('/image','/passed','/fail','/report','/istargetbrowser','/should-assert') in your mirage config.js.

Svg4everybody and tags


Currently there is no canvas support for svg tags. As a result visual acceptance will produce a blank canvas in the place of those svgs.

$3

If your svgs are coming from ember-frost-core you can utilize the inline svg rendering config option in your tests/dummy/config/environment.js. If using visual acceptance in an integration test you must import the svg-use-polyfill instance initializer and run it beforeEach test. You can import the intializer via import {initialize as initializeSvgUse} from 'ember-frost-core/instance-initializers/svg-use-polyfill' and make use of it in the beforeEach hook by doing

`javascript
beforeEach(function () {
initializeSvgUse()
})
`




Setting up Travis

The details to setup Travis can be found here. Once complete visual-acceptance will be able to attach reports to your Pull Requests.

Linting

#### ESLint
Add the below line to the top of your test file:
`javascript
/ global capture /
`
as seen in the sample integration test.

#### JSHint
Add the below line to the top of your test file:
`javascript
/ globals capture /
``