Home

Background

Venus is a testing tool for JavaScript (JS), which simplifies running unit tests.

When you are developing a browser-based project in JS, you'll want to create unit tests and run them frequently. To run one of your tests in the browser, you typically need to generate a test fixture page.

Rather than create an entirely new testing library, we set out to create a tool to make it easier for you to work with an existing library.

Pains of running unit tests

Generating and running the test fixture page is often a manual process (e.g, defining library, dependencies, code want to test, some initialization code).

There is often no easy way to integrate running tests from an IDE, since there is no command line output from running the test.

Venus comes to the rescue

Use simple annotations in your tests to specify which testing library you want to use, the file you are testing, other file dependencies, and a test fixture page template.

Quickly run your browser-based tests directly from the command line using PhantomJS.

Run your tests from the command line in multiple browsers (running locally or remotely) at the same time.

Integration with Continuous Integration tools (Hudson + Selenium Grid).

Setup

Install [Node.js|http://nodejs.org/]

// Mac OS X
// Use the Macintosh Installer on the Node.js website (e.g., node-v0.8.6.pkg)

// Linux RHEL
// Download source code from Node.js website (e.g., node-v0.8.6.tar.gz)
tar -zxf node-v0.8.6.tar.gz
cd node-v0.8.6
./configure
make
sudo make install

Clone the Venus repository from GitHub

git clone [email protected]:sethmcl/venus.git

Install Node.js packages {code:JavaScript} npm install {code}

Running Unit Tests

To run a unit test locally using PhantomJS, use the following command from the Venus directory: {code:JavaScript} bin/venus exec -t path/to/test/foo.js -n {code}

Socket.IO is started to handle communication between the client and server. An executor is created to run the unit test on the browser.

If the {{-n}} option is passed to the {{exec}} command, a PhantomJS browser is launched locally to run the unit test.

If the {{-n}} option is not passed to the {{exec}} command, copy the URL from the console to any browser to run the unit test.

Usage: {{bin/venus exec [options]}}

|| Option || Description || | -n, --phantom | Use PhantomJS client to run browser tests | | -t, --test | Comma separated string of tests to run |

h2. Overview

We will give an overview of the code base

bin/venus

This is a shell script that creates a new Venus object and assigns it the varible {{app}} It then calls {{app.run()}} with the command line arguments as it's parameter

Venus.js

{{run()}} It passes command line arguments to {{init()}}

{{init()}} Defines commands and options that can be used with Venus via commander.js commander.js is also used to parse command line arguments When {{exec}} is passed a command line argument, {{startExecutor()}} is called

{{startExecutor()}} Checks if overlord URL is defined (similar to InsFrame master/slave configuration) Calls {{executor.start()}}

lib/executor.js

{{start()}} Creates a new instance of Executor and calls {{init()}}

{{init()}} Calls {{initEnvironment()}} to set up application environment by creating HTTP server and defining directory paths for files/dependencies Creates test groups of all unit tests passed in as command line arguments Checks if overlord and PhantomJS are defined Calls {{initRoutes()}} to define routes via Express (executor assigns id to every test case that is loaded starting at 1 and auto increments) Calls {{start()}} to find open port for executor to run on Executor runs unit tests one by one

.venus directory

This directory defines the default configurations for the Venus project with the following folders:

• adapters => bridge files between library/framework and Venus that will normalize output to console
• libraries => libraries/frameworks that Venus supports
• templates => dust templates for the test fixture pages

test file (e.g., test/data/sample_tests/planet.js)

Can use following annotations at the top of the test file:

• @venus-library => library/framework that you want to use
• @venus-template => test fixture template (uses default test fixture template if not defined)
• @venus-include => JS file to include with test (create @venus-include for each JS file)

Easter Egg

We use the i18n and locale node packages to define the language for Venus console output:

{code:JavaScript} bin/venus exec -l en \ English bin/venus exec -l pirate \ Pirate Speak {code}

Selenium Grid/Continuous Integration (Hudson)

Selenium grid allows your to write regular selenium scripts to define a unit test on a specified browser and URL. You are able to send requests to a controller server that is responsible to get a VM up and running with a URL you define. It basically acts like a black box to run unit tests.

The former approach was to host our own browsers on a server. Connections to the server where not consistent which led to it not being manageable and scalable.

An integration between Venus and selenium grid will support continuous integration environments.

What's Next

• Build adapters for Jasmine
• Work on selenium integration to run tests remotely
• Add different format for test results

Known Issues

If you run into issues with Node.js version, make sure to update Node.js:

If you run into issues with phantonjs-node, run the following commands inside the Venus directory {code:JavaScript} git submodule init git submodule update {code}