mocha-webdriver-runner
Run Mocha tests in browsers using Selenium WebDriver.
Inspired by mocha-chrome, but with following
features implemented from start:
- drives browser using Selenium WebDriver, so you can run tests on everything that selenium WebDriver supports. Hint: it supports everything (tm).
- runs reporters locally, in node environment so most of reporters (which are designed to work in node environment) should work out-of-box:
- tested mocha builtins: spec, xunit, tap, etc ...
- support for
mochawesome
(including usage of addContext
)
That's it, have fun.
Install
$ npm install mocha-webdriver-runner
(Also ensure that you've got proper drivers or Selenium Grid available, see Browser Driver section below).
Usage
Prepare your tests to run in browser as described on Mocha website.
Add mocha-webdriver-runner
browser side client just after normal mocha.js
<script>
tag:
<script src="../node_modules/mocha/mocha.js"></script
+ <script src="../node_modules/mocha-webdriver-runner/dist/mocha-webdriver-client.js"></script>
Run the test suite against local browser:
SELENIUM_BROWSER=chrome npx mocha-webdriver-runner test/index.html
SELENIUM_BROWSER=firefox npx mocha-webdriver-runner test/index.html --reporter=tap
(assuming your tests are in test/index.html).
The HTML test page works in two environments:
- normal browser window - HTML report is generated in browser window as usual
- when ran through
mocha-webdriver-runner
, report is forwarded to reporter running in node
(default is spec
)
See package.json
scripts and test/sample-suite/index-headless.html
for reference.
Browser capabilities
Use -C key[=value]
(or --capability
) options to set requested browser capabilities.
Value may be plain string, or JSON value, examples:
-C browserName=firefox
-C moz:firefoxOptions.args='["-headless"]'
-C browserName=chrome
-C chromeOptions.args='["--headless", "--window-size=300,300"]'
Convenience shortcuts:
Shortcut option | Resolves to |
---|
--headless-chrome | -C browserName=chrome -C chromeOptions.args='["--headless"]' |
--chrome | -C browserName=chrome |
--headless-firefox | -C browserName=firefox -C moz:firefoxOptions.args='["-headless"]' |
--firefox | -C browserName=firefox |
--edge | -C browserName=MicrosoftEdge |
--safari | -C browserName=safari |
Useful links:
Selenium WebDriverJS accepts capabilities passed by environment variables as below:
SELENIUM_BROWSER=chrome
SELENIUM_BROWSER=firefox:52
SELENIUM_REMOTE_URL=http://my-selenium-grid:4444/wd/hub
See WebDriverJS Builder
Browser Drivers
Testing against browser that runs on your desktop requires that proper drivers are installed in your environment.
- Chrome - requires
chromedriver
- Firefox - requires
geckdriver
- Safari - requires
safaridriver
For mocha-webdriver-runner
to work, particular webdriver must be installed somwehere in PATH
.
Note, convenience NPM packages -chromedriver
and geckdriver
- install them it to ./node_modules/.bin
, so if you run your tests via npm drivers are found automagically.
API
Node.Js
From Node.js you can start tests using runMochaWebDriverTest
.
import { runMochaWebDriverTest } from "mocha-webdriver-runner";
const webDriverCapabilities = {
browserName: "firefox"
};
runMochaWebDriverTest(webDriverCapabilities, "https://localhost:8080/test/index.html")
.then(result => {
console.log("test result", result ? ":)" : ":(");
})
.catch(error => {
});
Browser general API
Browser module export global object MochaWebdriverClient
.
Import examples:
<script src="https://unpkg.com/mocha-webdriver-runner/dist/mocha-webdriver-client.js"></script>
<script src="../node_modules/mocha-webdriver-runner/dist/mocha-webdriver-client.js"></script>
MochaWebdriverClient
API
-
addMochaSource(mocha)
- instruments mocha
instance to send runner events back to
mocha-selenium-runner
process.
Example:
mocha.setup({ ui: "bdd" });
MochaWebdriverClient.install(mocha);
mocha.run();
-
addWorkerSource(worker: Worker)
- forwards all mocha-selenium-runner
related events from
worker
back to mocha-selenium-runner
process (requires properly initialized mocha
in
worker
context
Example:
const worker = new Worker("some-test-worker.js");
MochaWebdriverClient.addWorkerSource(worker);
Examples:
Contribute
PRs accepted.
License
MIT © Zbigniew Zagórski