protractor-image-comparison - npm Package Compare versions

Comparing version 0.0.1 to 0.1.1

package.json

 {
   "name": "protractor-image-comparison",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "npm-module to compare images with protractor",
+  "main": "index.js",
+  "scripts": {
+    "changelog": "node ./test/changelog.js",
+    "test": "node ./test/cli image-comparison",
+    "wd-update": "node_modules/.bin/webdriver-manager update"
+  },
   "repository": {
@@ -15,3 +21,3 @@ "type": "git",
     "pix",
-    "blink",
+    "resemblejs",
     "image",
@@ -23,3 +29,29 @@ "diff",
   "author": "Wim Selles - wswebcreation",
-  "license": "ISC"
-}
+  "license": "ISC",
+  "dependencies": {
+    "assert": "^1.4.1",
+    "camel-case": "^3.0.0",
+    "mkdirp": "^0.5.1",
+    "png-image": "^1.0.1"
+  },
+  "devDependencies": {
+    "chalk": "^1.1.3",
+    "commander": "^2.9.0",
+    "conventional-changelog": "^1.1.0",
+    "ghooks": "^1.3.2",
+    "jasmine-spec-reporter": "^2.7.0",
+    "protractor": "^4.0.10",
+    "validate-commit-msg": "^2.8.2",
+    "wd": "^1.0.0",
+    "wd-bridge": "0.0.2"
+  },
+  "config": {
+    "ghooks": {
+      "commit-msg": "validate-commit-msg"
+    }
+  },
+  "engines": {
+    "npm": ">=3.0.0",
+    "node": ">=4.6.0"
+  }
+}

README.md

@@ -1,5 +0,184 @@
-image-comparison
+protractor-image-comparison
 ==========
 
-A lightweight npm-module for protractor to execute image comparison. 
+A lightweight protractor plugin for image comparison.
 
+[![dependencies Status](https://david-dm.org/wswebcreation/protractor-image-comparison/status.svg)](https://david-dm.org/wswebcreation/protractor-image-comparison) [![Build Status](https://travis-ci.org/wswebcreation/protractor-image-comparison.svg?branch=master)](https://travis-ci.org/wswebcreation/protractor-image-comparison) [![Sauce Test Status](https://saucelabs.com/buildstatus/wswebcreation-nl)](https://saucelabs.com/u/wswebcreation-nl)
+
+[![NPM](https://nodei.co/npm/protractor-image-comparison.png)](https://nodei.co/npm/protractor-image-comparison/)
+
+[![Sauce Test Status](https://saucelabs.com/browser-matrix/wswebcreation-nl.svg)](https://saucelabs.com/u/wswebcreation-nl)
+
+##Installation
+Install this module locally with the following command:
+```shell
+npm install protractor-image-comparison
+```
+
+Save to dependencies or dev-dependencies:
+```shell
+npm install --save protractor-image-comparison
+npm install --save-dev protractor-image-comparison
+```
+
+##Usage
+protractor-image-comparison can be used for:
+
+- desktop browsers (Chrome / Firefox / Safari / Internet Explorer 11 / Microsoft Edge)
+- mobile / tablet browsers (Chrome / Safari on emulators / real devices) based on Appium
+
+For more information about mobile testing see the [Appium](./docs/appium.md) documentation. 
+
+*protractor-image-comparison* provides:
+
+- two comparison methods `checkScreen` and `checkElement`.
+- two helper methods `saveScreen` and `saveElement` for saving images.
+
+The comparison methods return a result in percentages like `0` or `3.94`.
+*protractor-image-comparison* can work with Jasmine and Cucumber.js. See [Examples](./docs/examples.md) for the Jasmine and CucumberJS implementation.
+
+###saveScreen or checkScreen 
+The methods `saveScreen` and `checkScreen` create a screenshot of the visible viewport. Be aware that there are different webdriver implementations in creating complete screenshots.
+For example:
+
+- **screenshot of visible viewport:**
+    - Chrome
+    - Safari
+    - Firefox when geckodriver is used (as of version 48 and higher)
+    - Microsoft Edge
+- **screenshots of complete page**
+    - Firefox when firefoxdriver is used (verion 47 and lower)
+    - Internet Explorer (11 and lower)
+
+###saveElement or checkElement 
+Images are cropped from the complete screenshot by using the `saveElement` or `checkElement` function. 
+The method will calculate the correct dimensions based upon the webdriver element selector.
+
+###protractor-image-comparison Parameters:
+
+* `baselineFolder` Defines the path to the reference images that are to be compared.
+* `screenshotPath` Defines the path to where the "actual" captured images need to be saved.
+* `formatString` Naming format for images (default: `{tag}-{browserName}-{width}x{height}`), see **Conventions: image naming** for more info
+* `nativeWebScreenshot` *protractor-image-comparison* needs to calculate element position based on a native device screenshot(default: false), see the [Appium docs](./docs/appium.md) for more info.
+* `blockOutStatusBar` *protractor-image-comparison* can blockout the statusbar of a device by default when comparion screens. This means that for example the time in the statusbar won't cause a failure (default:false)
+* `androidOffsets` An object that will hold the pixels of the `statusBar`, `addressBar` and or the `toolBar`. The values are used to calculate the position of an element on a screen (for `saveElement` or `checkElement`). They are defaulted, but can be overridden. These values can be different per Android version. Look up the docs for developing for Android to see the values. If not provided the defaults will be used.
+* `iosOffsets` An object that will hold the pixels of the `statusBar` and or the `addressBar`. The values are used to calculate the position of an element on a screen (for `saveElement` or `checkElement`). They are defaulted, but can be overridden. These values can be different per iOS version. Look up the docs for developing for iOS to see the values. If not provided the defaults will be used.
+
+**For example:**
+
+`````
+browser.protractorImageComparison = new protractorImageComparison({
+	baselineFolder: './baseline/',
+	screenshotPath: './.tmp/',
+	nativeWebScreenshot: true,
+	blockOutStatusBar: true,
+	androidOffsets: {
+		statusBar: 50,
+		addressBar: 100,
+		toolBar: 60
+	},
+   iosOffsets: {
+		statusBar: 40,
+		addressBar: 100
+	}
+});
+`````
+
+###Method options:
+#### blockOut
+Sometimes, it is necessary to block-out some specific areas in an image that should be ignored for comparisons. For example, this can be IDs or even time-labels that change with the time. Adding block-outs to images may decrease false positives and therefore stabilizes these comparisons (see the [examples](./docs/examples.md)). 
+It can be used for `checkElement` and `checkScreen` and is an object or list of objects with coordinates that should be blocked before comparing. (default: none).
+
+**Keep in mind that the devicepixelratio on a browser / device influences the coordinates needed to create the blockout. Calculate the blockouts based on a screenshot (of an element) that already has been created, use for example Photoshop for this.** 
+
+#### resizeDimensions
+Sometimes it is needed that the cut of an image should be bigger then the element itself. Take for example the hover state. A kind of a box / halo can be presented around the element that is not placed within but outside the element. With `resizeDimensions` the size of the cut of the element image can be made bigger. `resizeDimensions` accepts an integer and the value need to represent pixels. Calculation against the devicepixelratio will be done by `protractor-image-comparison`
+For example:
+
+`````
+expect(browser.imageComparson.saveElement(element(by.css('#id')), 'tagName', {resizeDimensions: 15})).toEqual(0);
+// or
+expect(browser.imageComparson.checkElement(element(by.css('#id')), 'tagName', {resizeDimensions: 15})).toEqual(0);
+`````
+
+
+## Conventions
+There are directory and naming conventions that must be met.
+
+###Directory structure**
+```text
+path
+└── to
+    └── screenshots
+        ├── diff
+        │   └── examplePage-chrome-1280x1024.png
+        ├── examplePage-chrome-800x600.png
+        ├── examplePage-chrome-1280x1024.png
+        ├── examplePageTitle-chrome-800x600.png
+        └── examplePageTitle-chrome-1280x1024.png
+```
+The `baselineFolder` directory must contain all the *approved* images. You may create subdirectories for better organisation, but the relative path should then be given in the test spec method. Failed comparisons generate a diff image under the **diff** folder.
+
+### image naming
+Images should obey the following default format:
+
+`````
+{descriptionInCamelCase}-{browserName}-{browserWidth}x{browserHeight}.png
+`````
+
+The naming convention can be customized by passing the parameter `formatString` with a format string like:
+
+`````
+{browserName}_{tag}__{width}-{height}
+`````
+
+The following variables can be passed to format the string
+* `browserName` The browser name property from the capabilities
+* `deviceName` The deviceName from capabilities
+* `dpr` The device pixel ratio
+* `logName` The logName from capabilities
+* `mobile` This will add `_app`, of `browserName` after the deviceName to distingues app screenshots from browser screenshots
+* `name` The name from capabilities
+
+Images specified via name in the spec method will be selected according to the browsers current resolution. That is to say that multiple images can share the same name differentated by resolution.
+
+##Tests
+There are several test that need to be executed to be able to test the module:
+
+### Local
+- `npm t` or `npm t -- -e local`: Run all tests on a local machine on Chrome and Firefox (job uses direct connect, first run `npm run wd-update` to update the webdriver. This needs to be done once after install)
+
+### local on Appium
+**First make sure Appium v 1.5.3 or higher is installed**
+
+- `npm t -- -e android.adb`: Run all tests with Appium on an Android emulator with the ADB driver on Chrome (`appium --port 4728 --avd AVD_for_Nexus_5_by_Google`)
+- `npm t -- -e android.chromedriver`: Run all tests with Appium on an Android emulator with the ChromeDriver on Chrome (`appium --port 4727 --avd AVD_for_Nexus_5_by_Google`)
+- `npm t -- -e ios.simulator`: Run all tests with Appium on Apple iOS simulator on Safari (`appium --port 4726`)
+
+### Travis-ci with Sauce Labs
+- `npm t -- -e saucelabs`: This command is used to test the build through [Travis-ci](https://travis-ci.org/wswebcreation/protractor-image-comparison/). It will test against a lot of configurations that can be found [here](./test/conf/protractor.saucelabs.conf.js)
+
+### Perfecto (cloud services for real devices)
+**Make sure you have an account and create a `perfecto.config.json` file in the root of this project with a `user`, a `password`- and a `seleniumAddress` key! like this:**
+
+`````
+{
+  "password": "password",
+  "user": "username",
+  "seleniumAddress": "https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub/"
+}
+`````
+
+- `npm t -- -e perfecto.android`: Run all tests on a real Android device on Chrome in the cloud (credentials are needed to be able to test this)
+- `npm t -- -e perfecto.ios`: Run all tests on a real Apple iOS device on Safari in the cloud (credentials are needed to be able to test this)
+
+## Credits
+- Basic logic of `index.js` based on [PixDiff](https://github.com/koola/pix-diff)
+- Comparison core of `./lib/resemble.js` [node-resemble](https://github.com/lksv/node-resemble.js) + [ResembleJS](https://github.com/Huddle/Resemble.js)
+
+## TODO
+* Update documentation for Mobile and different webdriver implementation
+* Update tests
+* New (mobile friendly) testpage
+* Add `debug` method
+* Add `clean` method to clean the given `screenshotPath` before running

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 5 instances in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

6936416

increased by1102668.84%

Number of package files

122

increased by3966.67%

Lines of code

1784

increased byInfinity%

Number of lines in readme file

184

increased by2966.67%

Worsened metrics

Dependency count

4

increased byInfinity%

Dev dependency count

9

increased byInfinity%

Number of low supply chain risk alerts

29

increased byInfinity%

Number of medium supply chain risk alerts

2

increased by100%

Dependency changes

• + Addedassert@^1.4.1

• + Addedcamel-case@^3.0.0

• + Addedmkdirp@^0.5.1

• + Addedpng-image@^1.0.1

• + Addedasap@1.0.0(transitive)

• + Addedassert@1.5.1(transitive)

• + Addedcall-bind@1.0.8(transitive)

• + Addedcall-bind-apply-helpers@1.0.1(transitive)

• + Addedcall-bound@1.0.3(transitive)

• + Addedcamel-case@3.0.0(transitive)

• + Addeddefine-data-property@1.1.4(transitive)

• + Addeddefine-properties@1.2.1(transitive)

• + Addeddunder-proto@1.0.1(transitive)

• + Addedes-define-property@1.0.1(transitive)

• + Addedes-errors@1.3.0(transitive)

• + Addedes-object-atoms@1.1.1(transitive)

• + Addedfunction-bind@1.1.2(transitive)

• + Addedget-intrinsic@1.2.7(transitive)

• + Addedget-proto@1.0.1(transitive)

• + Addedgopd@1.2.0(transitive)

• + Addedhas-property-descriptors@1.0.2(transitive)

• + Addedhas-symbols@1.1.0(transitive)

• + Addedhasown@2.0.2(transitive)

• + Addedinherits@2.0.3(transitive)

• + Addedlower-case@1.1.4(transitive)

• + Addedmath-intrinsics@1.1.0(transitive)

• + Addedminimist@1.2.8(transitive)

• + Addedmkdirp@0.5.6(transitive)

• + Addedno-case@2.3.2(transitive)

• + Addedobject-keys@1.1.1(transitive)

• + Addedobject.assign@4.1.7(transitive)

• + Addedpng-image@1.2.0(transitive)

• + Addedpngjs@3.4.0(transitive)

• + Addedpromise@6.1.0(transitive)

• + Addedset-function-length@1.2.2(transitive)

• + Addedupper-case@1.1.3(transitive)

• + Addedutil@0.10.4(transitive)