Capium

A tool to get screenshots of web pages so easily and automatically works with Selenium3.0 for NodeJS and easy to use BrowserStack and SauceLabs.

Installation

$3

``sh
yarn add capium
`
or
`sh
npm i capium --save-dev
`

$3

#### Mac OS X with Homebrew
`bash
brew install graphicsmagick
`
#### Windows
Download and Install from http://www.graphicsmagick.org/download.html

Basic Usage (Only get screenshots)

pages and caps are able to be specified multiply with Array.
If single, it does'nt need to specify as Array.

index.js
`js
const Capium = require('capium');
const capium = new Capium({
pages: [
"http://localhost/login.html",
"http://localhost/register.html",
],
caps: [
{"browserName": "chrome"},
{"browserName": "firefox"}
]
});
capium.run();
`

just run the file as node
`sh
node index.js
`

$3


If finished the process, Then you can see screenshots(png) in the ${you project root}/capium_output directory.

#### if git project
./capium_output/${git revision}/${url replaced / to _}

#### if timestamp option is true
./capium_output/${timestamp}/${url replaced / to _}

#### if git project and timestamp option is true
./capium_output/${git revision}/${timestamp}/${url replaced / to _}

ex)
`sh
./capium_output/562184b/1487045916823/www_google_com.png
`

Advanced Usage (With Webdriver Code)

Not only getting screenshots, WebDriver Code is also available.
To run WebDriver Code on the page, set wd property as function.
Basically the screenshots will be gotten after running WebDriver Code.

`js
const Capium = require('capium');
const capium = new Capium({
pages: [
{
url: "http://www.google.com/ncr",

//Write here to execute webdriver api (Plain Webdriver Syntax)
//This will executed before getting screenshot.
wd: function (driver, webdriver) {
driver.findElement(webdriver.By.name('q')).sendKeys('webdriver');
driver.findElement(webdriver.By.name('btnG')).click();
driver.wait(webdriver.until.titleIs('webdriver - Google Search'), 1000);
}
}
],
caps: [
{"browserName": "chrome"},
{"browserName": "firefox"}
]
});
capium.run();
`

Config

$3

- url is target url to transition
- wd(webdriver) is function to execute WebDriver API when page of url is loaded.
- A parameter driver is built browser instance for API e.g. driver.wait and driver.executeScript etc.
- A parameter webdriver is from require('selenium-webdriver') for API e.g. webdriver.By and webdriver.until.

$3

- Native browserName could be specified as chrome/firefox/safari/MicrosoftEdge/internet explorer
- Available as same as native capability of Selenium Webdriver. (See native capabilities of WebDriver)

$3

#### Set account capabilities
- Account capabilities for BrowserStack.
- Account capabilities for SauceLabs.

#### Set browser capabilities

To specify easily, use Capability Generator published by BrowserStack and SauceLabs.

- BrowserStack's Generator
- SauceLabs's Generator

To see all of capability, go to the each service site.
- BrowserStack's Capabilities
- SauceLabs's Capabilities

#### Examples (safari on iOS on iPhone6)

##### BrowserStack Capabilities

`js
const Capium = require('capium');
const capium = new Capium({
pages: [
"http://localhost/login.html",
"http://localhost/register.html",
],
caps: [
{
"browserName": "iPhone",
"platform": "MAC",
"device": "iPhone 6",
"browserstack.user": "",
"browserstack.key": ""
}
]
});
capium.run();
`

##### SauceLabs Capabilities
`js
const Capium = require('capium');
const capium = new Capium({
pages: [
"http://localhost/login.html",
"http://localhost/register.html",
],
caps: [
{
"browserName": "Safari",
"appiumVersion": "1.5.3",
"deviceName": "iPhone 6s Device",
"deviceOrientation": "portrait",
"platformVersion": "9.3",
"platformName": "iOS",
"username": "*",
"accessKey": "**"
}
]
});
capium.run();
`

Some better API than native Webdriver API

$3

because they are should to be passed as string like below.

`js
const capium = new Capium({
pages: [
{
url: "http://www.google.com/ncr",
wd: function (driver, webdriver) {
driver.executeScript('var allElements = document.querySelector("*"); for(var i = 0, len = allElements.length; i < len; i++) { allElements[i].hidden = true; } return "any value to want to pass";')
}
}
]
});
`

#### this.executeScript

`js
const capium = new Capium({
pages: [
{
url: "http://www.google.com/ncr",
wd: function (driver, webdriver) {
this.executeScript(function(arg1, arg2, arg3, arg4, arg5) {
var allElements = document.querySelector("*");
for(var i = 0, len = allElements.length; i < len; i++) {
allElements[i].hidden = true;
}
return 'any value to want to pass';
});
}
}
]
});
`

#### this.executeAsyncScript

`js
const capium = new Capium({
pages: [
{
url: "http://www.google.com/ncr",
wd: function (driver, webdriver) {
this.executeAsyncScript(function() {
var callback = arguments[arguments.length = 1];
setTimeout(function() {
callback('any value to want to pass')
}, 10000);
});
}
}
]
});
`

#### Passing arguments

Here is how to pass arguments from process of NodeJS into JavaScript in the Browser.

`js
const capium = new Capium({
pages: [
{
url: "http://www.google.com/ncr",
wd: function (driver, webdriver) {
this.executeScript(function(Arguments, are, available, at, here) {

var msg = [Arguments, are, available, at, here].join(' ');
console.log(msg);//Arguments are available at here

return 'any value to want to pass';
}, 'Arguments', 'are', 'available', 'at', 'here');
}
}
]
});
`

And also executeAsyncScript is same usage as above executeScript.

Browser Supports

| | chrome | firefox | edge | ie11 | safari | iphone safari | android chrome |
| ------------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| Mac (local) | ✓ | ✓ | | | ✓ | | |
| Windows (local) | ✓ | ✓ | ✓ | ✓ | | | |
| Browser Stack (remote)| ✓ | ✓ | ✓ | ✓| ✓ | ✓ | ✓ |
| Sauce Labs (remote) | ✓| ✓| ✓ | ✓| ✓ | ▵ | ▵ |




Range of Screenshot

| chrome | firefox | edge | ie11 | safari | ios safari | android chrome |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| Full Page ∗1 | Full Page ∗1 | Full Page | Full Page ∗1 | Full Page ∗2 | Full Page ∗1 | Above the Fold |

- ∗1. As native, above the fold but it's emulated with window scrolling.
- ∗2. In case of Safari10~ & Selenium3~. Otherwise Above the fold

$3

See a document.

TIPS

$3

1. Get driver from http://www.seleniumhq.org/download/
2. Enable the binary to be run from anywhere

$3

Safari > Develop > Allow Remote Automation.

$3

Include Username and Password into the URL.

`js
module.exports = [
{
url: "http://username:password@example.com"
}
];
`

!!!! Take care to not make published the secret information. !!!!

$3

#### BrowserStack

Just add "browserstack.local": "true"

`json
{
"browserName": "iPhone",
"platform": "MAC",
"device": "iPhone 6",
"browserstack.user": "",
"browserstack.key": "",
"browserstack.local": "true"
}
`

More information is here

#### SauceLabs

Download & use Sauce Connect from Sauce Labs.

##### Basic Usage
It works after launching SauceConnect server.
`bash
./sc-4.3.6-osx/bin/sc- u ${username} -k ${accesskey}
`

##### In the case of Basic Authenticated URL:
`bash
./sc-4.3.6-osx/bin/sc -u ${saucelabs_username} -k ${saucelabs_accesskey} -a ${host}:${port}:${basicauth_username}:${basicauth_password}
`

-a options is possible to be specified multiple time.

More information is here


##### Experimental capability to run without running above command

Otherwise, you are able to use Sauce Connect as just add only "sauceConnect": true parameter.

`json
{
"browserName": "chrome",
"os": "windows",
"username": "xxxxxxxxxxx",
"accessKey": "xxxxxxxxxxxxx",
"sauceConnect": true
}
`

Testing


`sh
npm test
`

Changed log

###### v0.6.0
- Possible to get screenshot of web pages as just write only a little config.
- Not only screenshot, and also you can start to Selenium so easily as just write as just install this module.
- Writable selenium code as just write wd property as function by page.
- By default, chrome and firefox and safari is runnable as it is. their drivers will be installed automatically.(safari10's driver is already installed natively.)
- Support for full screenshot except for android.
- SauceLabs and BrowserStack can be used with easy config.
- Local testing is also available with above remote testing services(e.g. localhost site.)
- Writable more flexible config.

###### v0.7.0
- Set color console message
- Possible to get full screenshot even if the page has contents loaded when scrolled.
- Possible to use BrowserStackLocal as just set browserstack.local: 'true'
- Add mocha as test framework.
- Possible to test with command npm test.
- Possible to install from yarn`.

Roadmap

###### v0.8.0
- Save screenshot by version or revision number

###### v0.9.0
- Runnable on windows OS also correctly.
- Catching JavaScript error.
- Detection error more finely.

###### v1.0.0
- Generate screenshot's diff image between a version and a version

###### v1.1.0
- Connect to local Appium server
- Run on Real Devices on BrowserStack

Dependencies

- Node.js v6.4.0~
- JRE 1.8~
- Selenium Webdriver for NodeJS
- Selenium Standalone
- Graphics Magick

Remote Selenium Services used by Capium.

They are awesome cloud testing services using real browsers and devices.