This is a Node template for cross-browser functional tests with Selenium on Sauce Labs. The stack is all Node, but the site to test can be statically or dynamically served with any language.
Before you start: You'll need to create a Sauce Labs account if you don't have one already.
There are a couple of moving parts in this repository that you should know about before proceding:
- The test server in
server.js
is an Express app that renders an HTML page with the title, "Hello, world!". - The test suite in
test/selenium.js
is a Mocha test script that uses the Selenium WebDriver API to test the HTML rendered by our test server in a remote browser. - The sauceconnect-runner dependency and
.env.example
template simplify running Selenium tests on remote Sauce Labs virtual machines against your local test server via Sauce Connect. - The
multitest.js
script reads a list of Selenium-compatible browser configurations frombrowsers.json
and runs the test suite against each of them in parallel. See Multi-Browser Tests for more info.
Clone this repo and install the dependencies via npm:
git clone https://github.com/shawnbot/node-sauce-template.git
cd node-sauce-template
npm install
Next up, you can verify that the test server works by calling npm start
. This
fires up an Express server that serves up a page with an HTML title, "Hello, world!"
. You can confirm that it's running by visiting
http://localhost:9000 in a web browser, or:
curl -s http://localhost:9000
Note: In your project environment, the server (i.e., the "start" script in package.json) would either start up your web application or start a local HTTP server to serve static files from your project directory.
Before you can run the Selenium tests, you'll need to set some environment
variables so that the scripts can pass your credentials along to Sauce. The
easiest way to do this is to copy the provided .env.example
file to .env
:
cp .env.example .env
Then edit it to ensure that the SAUCE_USERNAME
and SAUCE_ACCESS_KEY
values
match those of your Sauce Labs account. You can also do it in your shell
manually like so:
export SAUCE_USERNAME="your-sauce-username"
export SAUCE_ACCESS_KEY="your-sauce-acess-key"
I suggest copying the file to .env
and using autoenv to have it sourced
whenever you cd
into this directory.
Sauce Connect allows you to run virtual machine tests on Sauce Labs against your local web server. Once your environment variables area set, you can run:
npm run sauce-connect
You should see output similar to below and ending with a line of green text that reads, "Sauce Connect is running". If you don't, check your Sauce credentials and try again.
Okay, now you're ready to start testing. You're going to need two shells for
this step, so get the other one ready (by opening a new window or tab in your
terminal app, for instance) and cd
into this directory. In the first shell,
start the server:
npm start
Then, in the next shell, run the tests:
npm test
If all goes well, you should see some text like this:
If you look at package.json, you can see that this is using
sauceconnect-runner's sc-run
utility to create the Sauce Connect tunnel
"around" the Mocha tests. If you're having trouble with sc-run
, you can try
decoupling it from the tests by running three shells in parallel:
npm start
to start the servernpm run sauce-connect
(or./node_modules/.bin/sc-run
) to create the Sauce Connect tunnelnpm test
to run the test
As you can see in test/selenium.js, you can use the
BROWSER
environment variable to override the default remote browser
configuration. (This is how the multi-browser tests
are run.) For instance, if you want to run your tests against Internet Explorer
9 on Windows, you could run:
BROWSER='{"browserName":"internet explorer","version":"9.0"}' npm test
By default, the Selenium test suite is only run against Chrome on Sauce Labs'
default platform (Linux as of this writing). The included multitest.js
allows you to run the tests against all of the browser configurations specified
in browsers.json in parallel, and exits with non-zero status
if any of the tests fail.
To run the multi-browser tests, just substitute node multitest.js
(or npm run test-multi
) for npm test
(i.e. mocha
) in the procedure above. You can
modify browsers.json
and specify as many browser/platform configurations as
your project needs. Just be warned that remote Selenium tests take much longer
to run than local tests, and that your workflow may be impeded by tests that
take too long to run. You can use the --serial
flag to run the tests in
serial, in which case the first failing test will abort the process:
node multitest.js --serial