With Intern you can easily run tests using your local machine’s web browser or on any other machine running a Selenium server. Sometimes a project will need to be tested across a wide range of platforms and browsers, more than an individual user or even an enterprise may have available. Cloud testing services such as BrowserStack, CrossBrowserTesting, Sauce Labs, and TestingBot provide access to hundreds of VMs running various combinations of platform and browser versions.  Intern has out-of-the-box support for several such services.

Testing in the cloud

Cloud testing services, from an automated testing perspective, are essentially giant farms of virtual servers. They tend to support similar arrays of desktop operating systems and browsers.  Generally, several versions of Windows, macOS, and possibly Linux are available. Android, iOS, and their standard browsers are also typically supported.

A tool such as Intern can request access to a machine running a particular operating system and hosting a particular browser. The testing service will create and startup a virtual machine matching the requested capabilities. Once the machine is available, Intern can send commands to it using the WebDriver protocol (or its predecessor, JsonWireProtocol) to open a browser and run tests.

When tests are run in a cloud testing provider, they will often need access to resources on the machine driving the test or within that machine’s network. To facilitate this, cloud testing services provide “tunnels”.  Tunnels are applications that run on the user’s machine and allow the remote browser to tunnel back to the user’s local network.

For example, when running WebDriver tests, Intern runs a server to instrument the code being tested, and the browser running in the cloud service must be able to access this server. A user could run such a server on an externally visible host, but this often isn’t desirable, particularly for code under development. Instead, the user runs a service-specific tunnel application that allows the remote browser to securely access hosts within the user’s own network.

Dig Dug

Intern interfaces with cloud testing services, including tunnel applications, using the Dig Dug support library. Dig Dug can download and manage a service’s tunnel application, establish a connection to a testing service, and send test run results to the service.

Dig Dug is configured with two options in the Intern config: tunnel and tunnelOptions. The tunnel property specifies a tunnel class, either with the name of a built in tunnel like 'SauceLabsTunnel', or a module ID like 'dojo/node!./myTunnelClass'.

As its name suggests, tunnelOptions specifies configuration options for a tunnel. It’s common to only use tunnel since the default options are often sufficient.

Certain tunnel properties can also be set with environment variables. Cloud services require users to authenticate, typically with an account ID and an API key. It’s possible to specify these in the tunnelOptions property.  This should be sufficient in certain circumstances, but you’ll want to be careful not to inadvertently check authentication credentials into publicly-available projects. To keep this information out of the codebase, these properties may be specified using environment variables like SAUCE_ACCESS_KEY and SAUCE_USER_NAME (each tunnel class uses its own property names).

Leadfoot

Dig Dug connects Intern to a cloud service, but it isn’t responsible for the testing process itself. The remote tests are driven by another Intern support library, Leadfoot. Leadfoot creates and manages sessions in a cloud testing service. When you write a functional test and call commands on this.remote, you’re using Leadfoot.

There are two main configuration options for Leadfoot in the Intern config file: capabilities and environments. Both of these options are ways of setting the remote machine with certain properties. The environments option specifies which browser + operating system combinations you would like to use for testing. The capabilities property specifies any settings that should apply to all environments, such as a default idle timeout or a descriptive name for a test session. Intern will mix the capabilities data into the relevant environment data when creating a new session with the testing provider. Learn more about the capabilities supported by test providers by reviewing their documentation:

Putting it all together…

First things first: you’ll need an account with whichever cloud service you plan to use. For this example, we’ll use Sauce Labs. Assuming you have a Sauce Labs account, you can find your access key in your user settings page, under “Access Key”. It should be a 32-character string, like “1234abcd-12ab-34cd-12cd-1234abcd1234”.

Once you have a cloud testing account, you can use intern-cli to quickly create a test config and a few simple tests:

  1. Install intern-cli: npm install -g intern-cli
  2. Create a new, empty project directory and install Intern: npm install intern
  3. Use intern-cli to create some starter tests: intern init
  4. Edit the intern config:
    • Set the tunnel property to 'SauceLabsTunnel'
    • Set the tunnelOptions property to 
      {
	accessKey: 'your access key',
	username: 'you@somewhere.com'
}

Note:  We’re adding your username and access key to the Sauce Labs Intern config example. In general and as a reminder, supplying these credentials via environment variables is advisable in order to avoid accidentally checking them into a source code repository.  The username and access key are being added to the configuration file for example purposes only.

The project directory should now contain a tests directory with a starter Intern configuration, along with one unit test suite and one functional test suite.

project_directory/
    tests/ 
        intern.js 
        unit/ 
            hello.js 
        functional/ 
            hello.js 
            page.html

To run the sample functional test suite with Intern, run the command intern run -w. The first time you run the tests, you’ll see a tunnel download progress message, then something similar to the following:

Listening on 0.0.0.0:9000
Tunnel started
* Created session chrome on any platform (a2b118...d54)

These messages indicate that the service tunnel has successfully started and that a session was created on the remote testing service. At this point, Intern will start running tests on the test VM. The default reporter will display the IDs of tests as they pass, showing a summary of the test results when the tests have completed.

And with that, you’re running tests in the cloud!