attester-launcher
v0.4.0
Published
Browser launcher for attester
Downloads
28
Readme
attester-launcher
attester-launcher is a command line tool to automatically start and stop browsers for an attester campaign.
attester-launcher only works with attester version 2.4 and later.
Usage
attester-launcher is already included in attester. Once attester is installed, attester-launcher can be used directly from attester with the --launcher-config
option, by specifying the configuration file to use. For example:
attester myCampaignConfig.yml --launcher-config launcherConfig.yml
attester-launcher can also be started separately to connect to an already running attester server. To use it that way, it is needed to install it from the npm repository:
npm install -g attester-launcher
Then it can be started with:
attester-launcher launcherConfig.yml --server http://127.0.0.1:7777
It is possible to specify multiple configuration files. In that case, configurations are merged, and values from the last configuration files specified in the command line can override values from previous configuration files.
Parameters from the configuration file can be overridden in the command line, for example: --server http://127.0.0.1:7777
, or --maxInstances.Browser_Firefox 0
.
Configuration file format
attester-launcher expects one or more configuration files, which specify which browsers to start and how.
Configuration files can be either in the JSON or the YAML format.
The format of a configuration file is recognized by the extension of the file. If it is .yml
or .yaml
, the file is parsed with the YAML parser, otherwise it is parsed with the JSON one.
For the value of any configuration parameter, it is possible to use the <%= env.ENVIRONMENT_VARIABLE_NAME %>
syntax to include the value of an environment variable. It is also possible to refer to any other configuration value, for example: <%= maxInstances.Browser_Firefox %>
or <%= server %>
.
Here is a sample configuration file, in the YAML format:
# The launchers section defines named launchers, which can be used in the browsers section.
# It is mostly useful to define common properties for multiple browsers.
launchers:
MySauceLabsConfig:
# Launchers can inherit from one another.
# The parent launcher is defined in the $launcher property.
# The names of built-in launchers start with a $ (such as $saucelabs).
# Properties prefixed with a $ are generic properties (no matter which launcher is used).
# Properties without the $ prefix are processed by the specified launcher.
$launcher: '$saucelabs'
$connectingTimeout: 300000
$maxInstances: 5
capabilities:
tunnelIdentifier: <%= env.TRAVIS_JOB_NUMBER %>
recordVideo: false
# The browsers section defines how to start each browser defined in the campaign configuration.
# Each key in the map (here: IE, Firefox, Chrome and PhantomJS), must match the name of a browser
# in the campaign configuration (otherwise, it will be ignored).
browsers:
IE:
# This configuration extends MySauceLabsConfig, which is defined in the launchers section
$launcher: 'MySauceLabsConfig'
capabilities:
browserName: internet explorer
platform: Windows 7
version: 11.0
Firefox:
# 2 different configurations for Firefox: a remote one from SauceLabs and a local one
# with $webdriver:
- $launcher: 'MySauceLabsConfig'
capabilities:
browserName: firefox
platform: Linux
- $launcher: '$webdriver'
$tags:
- LocalBrowser
capabilities:
browserName: firefox
Chrome:
- $launcher: 'MySauceLabsConfig'
capabilities:
browserName: chrome
platform: Linux
- $launcher: '$webdriver'
$tags:
- LocalBrowser
capabilities:
browserName: chrome
PhantomJS:
$launcher: '$phantomjs'
$maxInstances: 8
maxInstances:
Launcher_MySauceLabsConfig: 5
Browser_Firefox: 5
Tag_LocalBrowser: 1
Global properties
server
Address of the attester server to connect to. Defaults tohttp://127.0.0.1:7777
. If attester-launcher is started from attester, this value is automatically set by attester in the command line (which overrides any value defined in a configuration file).launchers
Map defining named launchers with their configuration. Each key in the map is the name of a launcher which can then be used as the value of the$launcher
property of a launcher configuration. Each value in the map is a launcher configuration, as described in the Launchers properties section.browsers
Map defining which launchers to use for each browser defined in the attester campaign. Each key in the map must match the name of a browser in the campaign configuration (otherwise, it will be ignored). Each value in the map is either a launcher configuration, or an array of launcher configurations.minTasksPerBrowser
Minimum number of tasks per browser instance. It is used as a limit to never start more browsers than the number of remaining tasks divided by this number. It is used at the time new browser instances are started, it is not used to stop already started browser instances.maxInstances
Map defining the maximum number of concurrent browser instances for different kinds of browsers. Each value in the map is a number. Each key in the map is a string which must use one of the following prefix:Launcher_
: each key prefixed withLauncher_
defines the maximum number of concurrent browser instances for the corresponding launcher name (that launcher name should be a built-in launcher or should correspond to a key inside thelaunchers
map). All descendant launchers are included in the count.Browser_
: each key prefixed withBrowser_
defines the maximum number of concurrent browser instances for the corresponding browser name (that browser name should correspond to a key inside thebrowsers
map, and the name of a browser in the campaign configuration).Tag_
: each key prefixed withTag_
defines the maximum number of concurrent browser instances for launchers whose configuration contains the corresponding tag in the$tags
property.Any
: theAny
key defines the total maximum number of concurrent browser instances.
Launchers properties
Launchers can be configured through different properties. Properties prefixed with a $
are generic properties, common to all launchers. Properties without the $
prefix are processed by the specified launcher.
Common properties
$launcher
Name of a parent launcher to inherit from. It can be either a built-in launcher or a launcher defined in thelaunchers
map.$tags
Array of tags. Each tag is a string, which creates an independent counter of browser instances which can be used in themaxInstances
map documented in the previous section.$maxInstances
Maximum number of concurrent browser instances which can be started by this launcher. Defaults to 1. Note that this property does not include descendant launchers in the count. For example, ifMySauceLabsConfig
is defined in thelaunchers
section with its$maxInstances
property set to 5, and if theFirefox
andChrome
browsers both inherit fromMySauceLabsConfig
, then the 5 instances of Firefox are counted independently of the 5 instances of Chrome, so there can be a total of 10 instances ofMySauceLabsConfig
if we count all descendant launchers. To limit the total number of descendants of a named launcher, it is possible to use the generalmaxInstances
map documented at the previous section, with itsLauncher_
prefix (but not this$maxInstances
launcher property).$connectionRetries
Specifies the maximum number of times a launcher is allowed to fail connecting its browser to the attester server. Defaults to 3. Once this threshold is reached, the launcher is disabled. As for the$maxInstances
property, the number of failures is counted independently in each launcher, not taking into account descendant launchers.$connectingTimeout
Specifies the maximum number of milliseconds to wait between the time a launcher is started and the time the browser successfully connects to the attester server. Defaults to 120000 ms (2 min). When this timeout is reached, the browser is closed.$disconnectedTimeout
Specifies the maximum number of milliseconds to wait between the time a launcher is disconnected and the time it reconnects. Defaults to 100 ms. When this timeout is reached, the browser is closed. When a browser is disconnected, there is usually not much hope that it will reconnect, which explains why the default value is so low, but there are some use cases in which it can be interesting to define a higher value.$idleTimeout
Specifies the maximum number of milliseconds to wait between the time a browser is idle and the time it gets more tasks to execute. Defaults to 100 ms. When this timeout is reached, the browser is closed. When a browser is idle, there is usually not much hope that it will get more tasks to execute, which explains why the default value is so low. However, it can happens in case another browser of the same type gets disconnected while executing a task and if attester is configured to restart tasks when browsers are disconnected.$exitingTimeout
Specifies the maximum number of milliseconds to wait between the time a browser is asked to close and the time it is reported by the launcher as closed. Defaults to 10000 ms (10s). When this timeout is reached, the browser is considered as closed even if the launcher did not report it, and the instances counters are updated so that it is possible to start another browser if needed.$urlExtraParameters
Specifies extra parameters to set in the URL opened in the browser. Especially, attester allows to add scripts in the page with theplugin
parameter, so, for example,plugin=http://127.0.0.1:7778/robot
can be used to include the robot-server.
$process
The $process
launcher allows to start a browser by executing a process specified in the command
property.
The URL the browser should connect to is appended at the end of the arguments specified in commandArgs
if it is not specified anywhere else in the command line (through ${ATTESTER-URL}
).
The process is killed when the browser should stop.
Note that, on Windows, as stated in the Node.js documentation, killing the process means terminating it without notification.
command
Path to the executable file to start. This parameter can contain variables (cf the corresponding section below).commandArgs
Array of string arguments to pass to the executable. Defaults to an empty array. The URL the browser should connect to is appended as the last parameter if it is not specified anywhere else in the command line (through${ATTESTER-URL}
). This parameter can contain variables (cf the corresponding section below).
$phantomjs
The $phantomjs
launcher allows to easily start PhantomJS, with a control script adapted to attester. It internally relies on the $process
launcher to start PhantomJS.
phantomjsPath
Path to the phantomjs executable. Defaults to the value of thePHANTOMJS_PATH
environment variable if it is available, or the"phantomjs"
string otherwise (which means phantomjs should be in the path). This parameter can contain variables (cf the corresponding section below).phantomjsArgs
Array of string arguments to pass to the phantomjs executable. Defaults to an empty array. This parameter can contain variables (cf the corresponding section below).scriptArgs
Arguments to the phantomjs control script. Defaults to an empty array.- The
--local-console
argument can be used to display logs (calls toconsole.log
,console.error
...) locally before sending them to the attester server. If this argument is not used, those logs are only sent to the attester server.
- The
$puppeteer
The $puppeteer
launcher allows to start a browser with puppeteer or any compatible package (such as puppeteer-firefox).
Note that the puppeteer
package is not declared as a dependency of attester-launcher and has to be installed separately.
puppeteerPath
Path to the puppeteer-compatible package, passed to the node.jsrequire
function. Defaults topuppeteer
, which works out of the box ifpuppeteer
is installed as a dependency of a package which also depends on attester-launcher.puppeteerOptions
Argument to be used when callingpuppeteer.launch
. See here for a list of available options.robot
If set to a truthy value, aphantomJSRobot
object will be exposed on the rootwindow
of the browser, containing asendEvent
method and akeys
object which allow to send input events (keyboard and mouse) to the web page. This API is compatible with the one provided when using the$phantomjs
launcher.puppeteerKeyboardPath
Path to a file similar to this one, containing the definition of available keys. This value is passed to the node.jsrequire
function. Defaults topuppeteerPath + "/lib/USKeyboardLayout"
. It is only used in order to populate thephantomJSRobot.keys
object ifrobot
is truthy.
$playwright
The $playwright
launcher allows to start a browser with playwright or any compatible package (such as playwright-firefox).
Note that the playwright
package is not declared as a dependency of attester-launcher and has to be installed separately.
playwrightPath
Path to the playwright-compatible package, passed to the node.jsrequire
function. Defaults toplaywright
, which works out of the box ifplaywright
is installed as a dependency of a package which also depends on attester-launcher.browser
Name of the browser, such aschromium
(the default),firefox
orwebkit
. An object with that name must be exported by the playwright-compatible package and have alaunch
method.launchOptions
Argument to be used when callingbrowserType.launch
. See here for a list of available options.contextOptions
Argument to be used when callingbrowser.newPage
. See here for a list of available options.robot
If set to a truthy value, aphantomJSRobot
object will be exposed on the rootwindow
of the browser, containing asendEvent
method and akeys
object which allow to send input events (keyboard and mouse) to the web page. This API is compatible with the one provided when using the$phantomjs
launcher.playwrightKeyboardPath
Path to a file similar to this one, containing the definition of available keys. This value is passed to the node.jsrequire
function. Defaults toplaywrightPath + "/lib/server/usKeyboardLayout.js"
. It is only used in order to populate thephantomJSRobot.keys
object ifrobot
is truthy.
$webdriver
The $webdriver
launcher allows to start a browser with Selenium WebDriver.
server
Selenium server to connect to. By default, no server is used, and local browsers are used.capabilities
Map of desired capabilities. You can refer to the documentation. This parameter can contain variables (cf the corresponding section below).keepAliveDelay
Interval (in milliseconds) at which a keep-alive command is sent. Defaults to -1, which disables the keep-alive feature. The command used to keep the browser alive isgetCurrentUrl
.
$saucelabs
The $saucelabs
launcher allows to start a browser on the Sauce Labs platform. It internally relies on the $webdriver
launcher.
username
Sauce Labs user name to use to start a browser through the WebDriver API. Defaults to the value of theSAUCE_USERNAME
environment variable.accessKey
Sauce Labs access key, associated to the previoususername
parameter. Defaults to the value of theSAUCE_ACCESS_KEY
environment variable.server
Selenium server to connect to. Defaults to the value of theSAUCE_SELENIUM_SERVER
environment variable, orhttp://ondemand.saucelabs.com/wd/hub
otherwise.capabilities
Map of desired capabilities. In addition to standard capabilities supported by Selenium, Sauce Labs supports passing additional settings. Especially, when using a Sauce Connect tunnel, it can be useful to passtunnelIdentifier
andparentTunnel
.keepAliveDelay
Interval (in milliseconds) at which a keep-alive command is sent. Defaults to -1, which disables the keep-alive feature. The command used to keep the browser alive isgetCurrentUrl
.
$virtualbox
The $virtualbox
launcher allows to use a web browser from a Virtual Box virtual machine. The configured virtual machine is cloned from the specified snapshot. The clone is then started and executes the specified command. When tests are finished, the virtual machine is powered off and deleted.
This launcher requires Virtual Box 5.0 or later.
vboxInstallPath
Path to the directory containing Virtual Box. The directory should contain theVBoxManage
executable file. If this parameter is not specified, the value from theVBOX_INSTALL_PATH
or theVBOX_MSI_INSTALL_PATH
environment variable is used.vm
Name of the virtual machine to use. The virtual machine will be cloned before being started, so that it is possible to start multiple instances of the same virtual machine.snapshot
Name of the snapshot to use when cloning the virtual machine.command
Command to use inside the virtual machine to start the browser. This parameter can contain variables (cf the corresponding section below).commandArgs
Arguments to pass to the command. The URL the browser should connect to is appended as the last parameter if it is not specified anywhere else in the command line (through${ATTESTER-URL}
). This parameter can contain variables (cf the corresponding section below).username
Name of user to use inside the virtual machine to start the command.password
Password to use inside the virtual machine.
$vboxrobot
The $vboxrobot
launcher allows to use a web browser from a virtual machine managed by the vbox-robot server. The configured virtual machine is cloned from the specified snapshot. The clone is then started and executes the specified command. When tests are finished, the virtual machine is powered off and deleted.
server
Address of the vbox-robot server. It should include authentication information if this is required to connect to the server.vm
Name of the virtual machine to use. The virtual machine will be cloned before being started, so that it is possible to start multiple instances of the same virtual machine.snapshot
Name of the snapshot to use when cloning the virtual machine.command
Command to use inside the virtual machine to start the browser. This can be either a simple string, or an array in order to include command line arguments (which are then positioned beforecommandArgs
). This parameter can contain variables (cf the corresponding section below).commandArgs
Arguments to add tocommand
. The URL the browser should connect to is appended as the last argument if it is not specified anywhere else in the command line (through${ATTESTER-URL}
). This parameter can contain variables (cf the corresponding section below).launcherOnly
If set to true,command
is supposed to be only a launcher, which means that, when it exits, it does not mean the browser exited, so this does not cause the virtual machine to be stopped. Defaults to false (so the machine is stopped aftercommand
stops running).pingCommand
If specified, this command will be executed repetitively until its return code is 0, beforecommand
is started. This is useful especially to wait for the network to be connected in the virtual machine before starting the web browser. This can be either a simple string (if no argument needs to be passed) or an array (with command line arguments). The host name of the attester server is appended as the last argument if it is not used anywhere else in the command line (through${ATTESTER-HOSTNAME}
). This parameter can contain variables (cf the corresponding section below).pingInterval
Interval (in milliseconds) between a unsuccessful ping command (returning a non-zero exit code) and the next execution of the ping command. Defaults to 1000 (which is one second).initCommands
Array of commands to execute just beforecommand
and just afterpingCommand
. These commands can be used to configure the virtual machine before starting the browser. Each command is expected to be an object with acommand
property containing an array of string arguments (which can contain variables as described in the corresponding section).username
Name of user to use inside the virtual machine to startpingCommand
,initCommands
andcommand
.password
Password to use inside the virtual machine.closeOnFailedCalibration
If set to true (which is the default), the virtual machine will be closed (powered off and deleted) when the calibration fails. This parameter can be set to false to let the virtual machine continue running when the calibration fails. Note that this parameter requires vbox-robot version 0.0.4 and later (it is ignored with earlier versions).
Variables
Some configuration properties of the launchers, such as command line parameters, can contain variables, as documented in the corresponding properties. The following variables are available in this case:
${ATTESTER-URL}
The URL the browser should connect to.${ATTESTER-HOSTNAME}
The host name part of${ATTESTER-URL}
.${ATTESTER-SLAVEID}
The unique identifier of the current slave, which is also included in${ATTESTER-URL}
as theid
parameter.