dockular v0.0.1

Dockular

Dockular is a skeleton setup project for testing web apps with Protractor, Sauce Labs, and Dockerized selenium services. All the hard work and configuration has already been done for you. All you need to do is fill out your SauceLabs credentials, write some tests, and think about all that free time you have now.

Project Overview

Prerequisites

This project uses the following software for running automated UI tests, so be sure you have them installed:

• Node.js
• Docker
• Docker-compose
• Google Chrome
• Firefox

Structure

There are a few scripts in the root of the project directory:

1. start-docker.sh will pull the necessary Docker images, and start running them for you. These are nodes for Chrome and Firefox, as well as Selenium Hub, which serves a middle man between them and Protractor. Once it's running, you can go to http://localhost:<port>/wd/hub to get a list of all current and past sessions, as well as verifying that it's up. You can get the port by looking at the docker information inside of docker-compose.yml. To stop it, all you need to do is Ctrl+C inside the terminal. Docker compose handles shutting down gracefully for you. Note, Docker must be running for this to work.

2. run-ui-tests.sh calls on Protractor to run the tests against these Selenium services. It supports two command line arguments, the first of which is the configuration file you want to use, either selenium or sauce labs. The second is the environment you want to test. Protractor is agnostic about whether Selenium is Dockerized or not.

3. start-selenium.sh starts the selenium service locally, outside of Docker. Running tests against this will actually open up a new browser instance and run it before your very eyes so you can see tests executing in real time.

4. setup-browser-drivers.sh calls on Protractor to set up browser drivers within the Protractor node_modules/ folder. This allows you to interact with selenium.

Basic Usage Instructions

1. Install all of the necessary external tools
2. Start Docker
3. Clone this repo, then run npm install
4. Write tests in the tests/ folder, naming them <name>-test.js
5. Configure selenium services

• If you want to use selenium locally, run ./run-selenium.sh
• If you want to use Dockerized selenium , run ./start-docker.sh
• If you want to use Sauce Labs, continue on to 6

6. Run your tests

• If you have selenium running either locally or inside of Docker, run ./run-ui-tests selenium_conf.js <env>
• If you want to use Sauce Labs, run ./run-ui-tests sauce_conf.js <env>

7. Your tests will run, and you can see their output either in Selenium, Docker, or Sauce Labs.

Known Issues

You cannot currently test against an app running on localhost using a Dockerized selenium service because localhost on Docker means the Docker machine's localhost, not the host machine's localhost. If you want to test against the host machine's localhost, you will need the natively running Selenium.jar file.

Notes / Other Info

It should be noted that the Docker instances handle visual output by using XVFB, which is short for X Visual Frame Buffer. This means that it no-ops all visual output instead of using the graphics card of whatever machine it's running on. This means you won't be able to see the actual tests themselves running, even though they are. If you want to be sure that the tests are actually hitting the Docker instance, or want to debug it, just look at the Docker instances console output from docker-compose.