mantoniMinimal WebDriver
Pipe scripts to browsers using the Selenium WebDriver protocol.
- SauceLabs support
- Appium support for mobile testing
- Selenium Server 2 support
- Concurrent test runs
- No web server required
Install
npm install min-wd
Usage
Put a config file name .min-wd in your project directory:
{
"hostname": "localhost",
"port": 4444,
"browsers": [{
"name": "internet explorer",
"version": "10"
}, {
"name": "chrome"
}]
}
You can also have the .min-wd file be loaded as a module:
var hostname = true ? "localhost" : "otherhost";
module.exports = {
"hostname": hostname,
"port": 4444,
"browsers": [{
"name": "internet explorer",
"version": "10"
}, {
"name": "chrome"
}]
}
Alternatively, add a webdriver property with the configs to your
package.json file.
Assuming my-script.js contains this:
console.log('Hello %s!', 'browser');
process.exit(0);
Use with browserify:
$ browserify -p min-wd my-script.js
# internet explorer 9:
Hello browser!
# chrome *:
Hello browser!
Additional Selenium capabilities and browser-specific capabilities can be
specified with the capabilities property:
{
"hostname": "localhost",
"port": 4444,
"browsers": [{
"name": "chrome",
"capabilities": {
"chromeOptions": {
"args": ["--headless", "--disable-gpu"]
}
}
}]
}
Shareable configuration package
Inspired by ESLint's shareable configuration package,
there is the possibility of storing selenium and browser-specific capabilities
in a separate npm package. This way one config can be shared amongst many npm
packages instead of them each having their own .min-wd file.
Usage
Create a npm package and name it using the prefix min-wd-config-
(eg. min-wd-config-myapp).
The shareable config must contain a js file that exports
an object with the configuration or a .min-wd file.
Example: index.js
module.exports = {
"hostname": "localhost",
"port": 4444,
"browsers": [{
"name": "chrome"
}]
}
In the shareable config's package.json you will need to reference the file containing the config:
{
"name": "min-wd-config-myapp",
"version": "^1.0.0",
"webdriver": {
"extends": "./index.js"
}
}
In the shareable config's dependent, that is the package that consumes the
shareable config, the config name without the min-wd-config- prefix needs to
be specified:
{
"name": "myapp",
"webdriver": {
"extends": "myapp"
},
"devDependencies": {
"min-wd-config-myapp": "^1.0.0"
}
}
When using a shareable config and a .min-wd file, the latter will take
precedence.
SauceLabs
Export your SauceLabs credentials:
export SAUCE_USERNAME="your-user-name"
export SAUCE_ACCESS_KEY="your-access-key"
Enable SauceLabs in your .min-wd file:
{
"sauceLabs": true,
"browsers": [...]
}
See "Supported options" for additional SauceLabs specific options and "SauceLabs on Travis" on how to run min-webdriver tests on Travis.
Appium
Note: This has only be tested on Mac OS X High Sierra with the iOS Simulator so far. If you have successfully tested with other configurations, please file an issue so that we can extend the docs.
Setup for iOS Simulator on Mac OS X:
npm install -g appiumbrew install carthage- Configure your
.min-wdfile like this:
{
"hostname": "localhost",
"port": 4723,
"browsers": [{
"name": "Safari",
"platformName": "iOS",
"platformVersion": "11.2",
"deviceName": "iPhone Simulator"
}]
}
- Run
appiumwhich should start a server on port 4723 - Run your tests
BrowserStack
Export your BrowserStack credentials:
export BROWSERSTACK_USERNAME="your-user-name"
export BROWSERSTACK_ACCESS_KEY="your-access-key"
Example .min-wd file:
module.exports = {
"hostname": "hub-cloud.browserstack.com",
"port": 80,
"browsers": [{
"name": "chrome",
"capabilities": {
"browser": "Chrome",
"browserstack.user": process.env.BROWSERSTACK_USERNAME,
"browserstack.key": process.env.BROWSERSTACK_ACCESS_KEY
}
}]
}
Loading a web page
By default, min-webdriver will fork a new browser and inject the given script
straight away without loading any web page. If you want to run your test cases
in the context of a web page, you can configure the start page in the .min-wd
file:
{
"url": "http://my-test-page"
}
Mocha Support
Testing with Mocha requires mocaccino:
$ browserify -p mocaccino -p min-wd my-test.js
If this is your use case, make sure to give Mochify a try.
Timeouts
The default timeout for the log polling script is 10 seconds. If you have long
running test cases that don't print anything for more than 10 seconds, you can
increase the timeout by adding a timeout property to your config:
"timeout": 20000
Notice: This option is not used if explicitly setting the asyncPolling
option to false.
API
Use min-wd programatically with browserify like this:
var browserify = require('browserify');
var minWd = require('min-wd');
var b = browserify();
b.plugin(minWd, { timeout : 0 });
Supported options
wdFilespecify the location of the.min-wdconfig file. Defaults to.min-wd.sauceLabswhether to run tests withsaucelabs. Defaults tofalse.hostnamethe host to connect to. Defaults tolocalhost. IfsauceLabsistrue,ondemand.saucelabs.comis used.portthe port to connect to. Defaults to4444. IfsauceLabsistrue,80is used.asyncPollingwhether to use async polling when looking for test results. Defaults totrue.timeoutif a script does not respond to log polling calls for this amount of milliseconds, the test run is aborted. Defaults to 10 seconds.urlthe URL to open in each browser. Defaults to no URL.closeOnSuccesswhether to close browsers on success. Defaults totrue.closeOnErrorwhether to close browsers on error. Defaults totrue.browsersan array of browser config objects, each with these properties:namethe name of the browser to launch, e.g.chrome,firefoxorinternet explorerversionthe browser version to launch. Use*for any.urlan optional URL to launch for this browsercapabilitiesadditional Selenium capabilities and browser-specific capabilities
Some options are only considered depending on the asyncPolling value:
pollingIntervalsets the time interval between test log checks. Only apply ifasyncPollingisfalse. Defaults to 1000 milliseconds.timeoutoption won't apply ifasyncPollingis set tofalsebecause the test log is checked manually respectingpollingInterval.
SauceLabs specific options that only apply if sauceLabs is set to true:
sauceJobNamesets a custom name for the SauceLabs job. If apackage.jsonfile exists in the current directory, this defaults to the package name.BUILD_VARsets the environment variable name that contains a build number to set, e.g.TRAVIS_BUILD_NUMBER.
SauceLabs on Travis
Assuming you have your linter and headless tests in an npm "test" script and
the SauceLabs tests in a script called "wd", then the SauceLabs builds can be
used by configuring your .travis.yml like this:
language: node_js
node_js:
- "0.12"
- "4.2"
env:
global:
- SAUCE_USERNAME=mantoni
- secure: "your-secured-access-key"
script:
- 'npm test'
- 'if [ "x$TRAVIS_NODE_VERSION" = "x4.2" ]; then npm run wd; fi'
This will run npm test on Node 0.12 and 4.2 while running the "wd" script
only in the node 4.2 build. See the Travis documentation for encryption
keys for details about the secure config.
Known issues and solutions
min-webdriver injects your script directly into the default page launched by
the Selenium driver. In some cases browsers behave strangely in this context.
Work around this by specifying a URL to a simple web page that is loaded before
running the tests:
{
"browsers": [{
"name": "Internet Explorer",
"version": "9",
"url": "http://my-server/doctype.html"
}]
}
With this content in the doctype.html:
<!DOCTYPE html><html><head><meta encoding="utf-8"></head><body></body></html>
You can also specify a "url" for all browser on the root level.
Loading a page before injecting the scripts is solving these issues:
- IE 9 reporting it can't find
JSONbecause the Selenium default page makes IE switch to quirks mode - Error:
SECURITY_ERR: DOM Exception 18because setting cookies is not allowed forfile://URLs - Error:
access to the Indexed Database API is denied in this context - localStorage being inaccessible.
- iOS Simulator does not report anything: Set
asyncPolling: false
Usage with Microsoft Edge browser
To configure edge use { "name": "microsoftedge" }. For the time being, MS
Edge doesn't support asyncPolling set to true. If you want to test with
that browser you must set asyncPolling to false.
Compatibility
- Node 0.10, 0.12, 4.x, 5.x
- Selenium Server 2.39 or later
License
MIT