rc for loading configuration.
Be aware that command line arguments won’t work
since most test runners (e.g.
mocha) have their own argv handling.
The name of the browser to use.
If no browser is specified, Testium will assume it’s
Typical values are
The latter two depend on which browsers are installed on your computer.
A fully featured selenium grid might support many more browsers.
The webdriver docs contain a list of known values for
Additional desired webdriver capabilities.
browserName field is ignored. It’s read from
This is mostly useful when running against a dedicated selenium grid.
It allows you to describe what kind of browser and OS you need
and the grid will create a session for the best match it can find.
Determines the interface for interacting with the browser.
Testium will prepend the value with
testium-driver- and treat the resulting string as an npm module name.
The default value is “wd”, so Testium will try to load
testium-driver-wd (the “promise-chain” interface is powered by
A simple example:
await browser.loadPage('/'); assert.strictEqual(await browser.getPageTitle(), 'Hello');
Set this to
true if you want Testium to handle starting the app during initialization and stopping it at the end.
This is not enabled by default.
NODE_ENV to use when launching the app.
By default, Testium uses
Testium will capture the output of all processes it manages
and write it to separate files in this directory.
Directory paths are relative to the working directory.
The default is
Testium will create the following files in this directory:
application.log: Output of the application under test.
proxy.log: Output of the proxy that captures status codes and headers.
selenium.log: This only exists if you use a browser other than PhantomJS. It fulfills a role similar to
Automatically generated screenshots like the ones created on failing mocha tests will be placed in this directory.
Directory paths are relative to the working directory.
By default, Testium will use
The command to use when launching the app.
This is ignored unless
launch is enabled.
If no command is provided, Testium will parse
package.json to simulate the behavior of
The port the app is listening on.
Setting the port to
0 tells Testium to select a random available port.
Testium will always pass the port as the environment variable
PORT to your app.
The final port (after resolving a port of
0) determines the base url when navigating to urls paths.
E.g. with a port of
browser.loadPage('/foo') will load
How long Testium should wait for the app to listen. Expects a time in milliseconds. By default, Testium will wait 30 seconds.
Mixins allow you to extend
testium.browser for all your tests.
They are commonly used for shorthands like
This feature is best used in moderation.
Having too many mixed-in methods can make it hard to tell where a specific method is defined or what a certain test is actually doing.
Each setting is an array of module names that will be resolved relative to the working directory. E.g.
./test/mixins/session.js will be resolved to
mixins/session may be resolved to
Additional methods for
See section on custom methods for how the files should be structured.
As part of its before hook,
testium-mocha will override some of mocha’s options.
This allows you to define custom
timeout values just for integration tests without having to touch the global
Specify the “slow” test threshold. Mocha uses this to highlight test-cases that are taking too long. The default value is two seconds. (Mocha Documentation)
Specifies the test-case timeout. The default value is 20 seconds. (Mocha Documentation)
Command to start PhantomJS.
Change this if you don’t have PhantomJS in your
By default, this is just
How long to wait for phantomjs to listen in milliseconds. By default, Testium will wait 6 seconds.
Controls the behavior of Testium’s HTTP proxy. Testium will send all requests through a local proxy process. This allows Testium to provide some additional features:
- Capture HTTP status codes and -headers.
- Inject additional headers to outgoing requests.
- Normalize response codes to 200. Some Webdriver implementations are sensible to server errors. Which means that server error pages won’t show up properly. By always rewriting the status code to 200, Testium ensures that screenshots taken on error actually show the error pages.
The port to use for proxying. If the port is set to 0, Testium will select a random available port. The default is 4445.
If you wish to run your browser on a different host (see
selenium.serverUrl), this will default to the output of
hostname -f in order to let the browser know how to reach this proxy running on localhost - if this is not correct, set this to a hostname that can be reached by the selenium browser. If this host is not reachable directly by the selenium host (due to firewall, NAT, VPN, CI container, etc.), see
If you are using
driver = wd, you may set this to open an SSH tunnel from a random port on a third party host thru to
proxy.port on localhost by setting
proxy.tunnel.host to a hostname which the Testium-running user has permission to ssh to with no password (via
$SSH_AUTH_SOCK agent or unencrypted private keys in
~/.ssh). If this hostname is not the same as the hostname that selenium will need to contact (e.g. you have to ssh to
foo-internal.example.com, but selenium will contact the same host as
proxy.host to the latter - otherwise you can leave
proxy.host unset and it will default to the value of
You must set
GatewayPorts yes in
/etc/ssh/sshd_config on the tunnel host to allow it to accept connections to proxy.
$USER environment variable is not an appropriate username for the ssh connection, you can override it here.
Defaults to 22
If have already set up your own tunnel from a port on
proxy.port on this host, set
proxy.tunnel.port to that port, and the SSH connection open will be skipped.
Module to use for the Testium repl.
By default, this is node’s built-in
If you want to use coffee-script in the repl, use
These settings will only be used when using a browser other than
Set to false to disable verbose logging into
This is enabled by default.
Path to the
If not provided, Testium will download it automatically on demand.
Path to the selenium standalone jar. If not provided, Testium will download it automatically on demand.
Allows to provide an existing selenium server.
serverUrl is set, Testium will not try to launch its own instance of selenium.
How long to wait for selenium to listen for requests in milliseconds. Defaults to 90 seconds.