A dockerized Selenium Grid with Nightwatch
I built this project to quickly provision a dockerized environment for running UI tests against a dockerized app. It employs a dockerized Selenium Grid which yields a far more cost-effective CI solution compared to purchasing and maintaining dedicated machines.
This project is geared toward a Node.js audience, meaning I've included npm
scripts as wrappers for the docker-compose
commands. Hopefully, once you've
completed the initial setup, you won't have to recall any docker commands.
:smiley:
Nightwatch serves as the testrunner. It is automatically provisioned in the
nightwatch
docker image, which you can easily customize in the included
nightwatch.conf.js
file.
Here's the default workflow when writing Nightwatch tests in this project:
bin/build && bin/start && bin/test
bin/build && bin/start && bin/test
:sadtrombone:
To make your life easier, first do this:
cp docker-compose.dev.override.yml docker-compose.override.yml
Now any changes you make within this repo on your host file system will
automatically show up in the nightwatch
docker container. Here's your new
workflow:
bin/build && bin/start && bin/test
bin/test
:party:
Some folks have reported file permission issues with this workflow, so YMMV.
By default this project will use a bare-bones Sinatra web app as the system
under test (SUT). If you want to replace that default web app with your own,
open the docker-compose.yml
file, find the web
service configuration, and
replace mycargus/hello_docker_world:master
with your app's docker image label.
For example:
web:
image: my-app-under-test:master
If you're not sure how to create or pull a docker image, I recommend working through the official Docker tutorial located on their website.
Start the Selenium hub, the SUT, and the Selenium browser nodes:
npm start
Execute the tests with Nightwatch:
npm test
When you're done, stop and remove the docker containers:
npm stop
Alternatively, if you don't want to install Node on your native machine, you may
use the included bin/
scripts. For example:
bin/start
bin/test
bin/stop
If you're using the default web app provided, then open your browser and go to http://locahost:8080.
If you're using your own web app, make sure to expose a port in your web app's
Dockerfile. For example, if you have EXPOSE 9887
in your web app's Dockerfile,
then you can view it at http://localhost:9887.
Yep! After having started the Selenium hub and nodes (npm start
), open a
browser and go to http://localhost:4444, then click the 'console' link.
Start the Selenium hub, the app under test, and the Selenium debug browser nodes:
npm run start:debug
or
bin/start-debug
View the chrome debug node via VNC (password: secret
):
open vnc://localhost:5900
View the firefox debug node via VNC (password: secret
):
open vnc://localhost:5901
Next execute the Nightwatch tests against the debug nodes and watch them run in the VNC window(s):
npm run test:debug
or
bin/test-debug
We publish our image to Dockerhub. Here's an example of using it in a docker-compose config:
# docker-compose.yml
---
version: '3.7'
services:
nightwatch:
image: mycargus/nightwatch:master
command: nightwatch ui-tests/ -e chrome
volumes:
- ./:/home/docker/app/
Notice you can override the default container command with standard Nightwatch
CLI commands, e.g. nightwatch ui-tests/ -e chrome
.
You can see an example of this using our docker-compose.example.yml
config:
bin/start
bin/test-example
If you're using our mycargus/nightwatch
docker image, then you have two ways
to tell Nightwatch where to find your tests.
You can provide a TESTS_DIRECTORY environment variable and value like so:
# docker-compose.yml
---
version: '3.7'
services:
nightwatch:
image: mycargus/nightwatch:master
environment:
TESTS_DIRECTORY: my_tests_directory/
volumes:
- ./:/home/docker/app/
Note you must mount your tests directory onto the container as shown above with
the volumes
configuration (or the docker run --volume
or
docker-compose run --volume
CLI equivalents) in order for Nightwatch to find
your custom tests directory. The container's default working directory is
/home/docker/app
, so as long as you mount your tests directory onto
/home/docker/app
, Nightwatch will be able to find them.
You can override the default tests
directory and any TESTS_DIRECTORY
value
by using the Nightwatch CLI inside the container:
docker run --rm --volume="./:/home/docker/app" mycargus/nightwatch:master \
nightwatch my_tests_directory/ -e chrome
Use docker run --rm mycargus/nightwatch:master nightwatch --help
for more
info.
We welcome and encourage contributions! See our Contributing doc for development instructions and more info.