karma-selenium-grid-launcher
A plugin for Karma that launches browsers on a remote Selenium Grid. Forked from karma-webdriver-launcher.
Uses the selenium-webdriver NPM module behind the scenes.
- Usage
- Launcher-Specific Configuration Keys
- Killing Tests Prematurely
- Browser Quirks and Workarounds
- Examples
Usage
$ npm install --save-dev karma-selenium-grid-launcher
In your karma.conf.js file define some custom launchers that inherit from
SeleniumGrid
, providing the URL of the Selenium Grid as gridUrl
.
module { ... config;
Other than the launcher-specific configuration keys described below, all keys are passed along to the grid as capabilities, giving you the flexibility to do anything the corresponding Selenium WebDriver supports (see the Selenium docs for more information).
Note that if you're trying to test on several browsers/platforms and you're
using the default Selenium matcher, you'll probably want to make use of the
undocumented applicationName
capability, as the only platforms that
Selenium will match are WINDOWS
, MAC
, and LINUX
.
You may also wish to use the browser constants exported by selenium-webdriver
to make sure you're using the browserName
expected by selenium.
Launcher-Specific Configuration Keys
The following keys provided as part of a customLauncher
block will not be
interpreted as a capability to send to the Grid; instead, they are processed
in some way by the launcher.
arguments
Array of arguments that should be used when launching the browser binary. Note
that only Chrome, Firefox, and IE accept this key; an error will be thrown if
another browserName
is used.
base
This is obviously only used by Karma to tell it from which base to extend, but
it's included here to make it clear that base
will not be passed along as a
capability.
closeBeforeQuit
Call driver.close()
before calling driver.quit()
. Set this to true
to
work around browsers/devices which don't implicitly close the active window
when testing finishes.
See the Browser Quirks and Workarounds section for which browsers/devices may require this for proper functionality.
delayLaunch
Time in ms to wait before launching a browser. Use this when a browser must end up as the foreground window for tests to pass, such as testing video playback on Safari.
extensions
Array of extension paths that should be installed on the remote browser. Note
that only Chrome and Firefox accept this key; an error will be thrown if
another browserName
is used.
firefoxPreferences
Object mapping Firefox preference keys to their desired value. If you wish to override one of the preferences passed to firefox by default, this will do the trick.
gridUrl
The URL of the Selenium Grid to use to launch browsers. If not provided, it
will default to http://localhost:4444/wd/hub
.
heartbeatInterval
Interval in ms to send a heartbeat to avoid the session being killed by
timeout. If not provided or set to 0
, no heartbeat will be performed.
options
Object mapping a method name for the appropriate Options
object of the
browser to the value with which it should be called. See the
selenium-webdriver API docs for more information.
promptOn (deprecated)
Send and then close a prompt when an element with the given id
is found in
the document.
This option is deprecated, and is probably not needed in any scenario.
resetBeforeQuit
Have the browser load about:blank
before calling driver.quit()
. Set this
to true
to work around browsers/devices which don't support closing the
active window when testing finishes.
See the Browser Quirks and Workarounds section for which browsers/devices may require this for proper functionality.
suppressWarning
A value of true
will suppress the internet explorer warning; any other value
will cause the warning to be displayed.
windowGeometry
Object to use for setting the geometry of the window. If any of the keys
width
, height
, x
, or y
are present in the object, they will be used to
modify just that aspect of the window geometry. Any other keys will be ignored.
x-ua-compatible
The value to use for an X-UA-Compatible
meta
tag. If not provided, Karma
will not add the meta
tag.
Killing Tests Prematurely
If you stop tests prematurely (e.g. by hitting Ctrl+c
) soon after launching
the tests, it may take some time for the browsers/devices to fully close. To
keep things simple(ish), there are a series of promises during
startup/initialization. When you stop the requests determines where in this
series there will be a call to driver.quit()
.
If the remote driver has returned a session, then you will have to wait for
the browser/device to load the karma page and perform its initialization
before driver.quit()
will be called.
If you're using mobile devices, also keep in mind that building/deploying the controller app and/or starting a simulator can take some time. Since the driver can only be used after this has finished, you must wait for this process to complete to ensure proper cleanup.
From the time you stop the tests until a particular browser has closed, the
message Waiting for ${browser} to quit... (${time}s)
will be output to the
console every 10s.
Browser Quirks and Workarounds
This is a list of known compatibility issues for certain browsers/devices, and how to work around those issues.
If you encounter any browser quirks not listed here, please open a PR that adds it, even if there is no known workaround.
Video Playback on macOS Safari
macOS Safari requires that it is the foreground window to play back video. Use
the delayLaunch
option to ensure that Safari launches after
any other browsers on the same machine.
Note also that the video element must have some portion within the viewport being displayed by the browser. In your tests, ensure this is done.
iOS 10 Safari
iOS 10 Safari does not implicitly close the current window when driver.quit()
is called, as specified by the WebDriver spec. This causes the browser to
connect twice during the next test run; the old window and the newly-launched
window. You should use the closeBeforeQuit
option to
ensure the window is closed at the end of each test run.
iOS 12 Safari
iOS 12 Safari does not support closing the current window either through
driver.close()
or driver.quit()
. This causes the old window to connect
to the next run, before being disconnected (the new test run reuses the old
window, so the page effectively refreshes). You should use the
resetBeforeQuit
option to ensure the window is set to
about:blank
at the end of each test run.
Examples
For a more detailed example, see the example file.