README.rst

JS TestNet

JS TestNet is a Django web service that coordinates the execution of
JavaScript tests across web browsers. It was designed to run pure JavaScript
tests with Qunit in a CI environment like Jenkins and to get test feedback
from real web browsers. It is probably flexible enough for other JavaScript
test runners too.

Note

This was a fun experiment but is no longer under development because
Django wasn't a good choice :) Check out Karma or Yeti, both of
which are speedy alternatives with more features!

JS TestNet lets you turn any web browser into a JavaScript test runner. You
control everything through a client (like JsTestNetLib); the client talks
to the server and it doesn't have to run on the same machine as any web
browser.

Here is a screenshot of Firefox and Chrome simultaneously running a
QUnit based test suite. You can see a script running in a terminal to kick off
the tests and collect results.

This screenshot was taken with a local development install of the JS Test Net
server. In a real world situation you'd probably run each web browser in a
headless virtual machine and you'd start the tests using the shell as part of
your Continuous Integration system.

A test suite is a URL to an HTML page that runs tests in a web browser when
loaded. The front page of the JS TestNet app links to a form where an
administrator can add a test suite into the system.

You will have to make one modification to your test suite. It must include
the jstestnet.js script (found in the adapter folder) to communicate with the
worker. Be sure it loads after Qunit or whatever supported test runner you
are using.

To register a web browser to run the tests (called a worker) just open the
browser and go to this URL and leave the window open:

http://your-jstestnet-server/work/

That's it! No complicated start / stop commands are necessary.
The worker will be able to run tests for as long as you keep that window open
using Ajax polling to talk to the server.
In a CI environment you could just open this URL once in a virtual machine
and forget all about it.

In fact, you can open this URL on any web enabled device. For example, you
could type this URL into your smart phone and
your phone would become a worker.

To understand the networking needed to use jstestnet, here is a diagram of a
typical configuration. The counterintuitive surprise here is that only the
TestWorker (the web browser) needs to connect to the web server that serves
your HTML test suite. JsTestNet does not need to load your test suite.

JsTestNet

The server running the Django app. This responds to requests from clients
and workers.

Jenkins

Your continuous integration server. This will typically execute tests
that invoke a client that talks to JsTestNet. In this configuration it
also runs a web server that serves the HTML Qunit suite at
http://<jenkins>:9878/qunit

TestWorker

This is a web browser that loads the worker page from JsTestNet once.
After that it polls the server with Ajax and fetches the Qunit test suite
in an iframe.

There is a special name-colon syntax to filter browsers. It looks like this:

firefox:latest

This will return the latest version of Firefox after doing a basic
alphanumeric sort on the version string.

There are a few exceptions:

To access mobile safari and not desktop safari
you can say mobile-safari=~528.16

Because the Gecko version is oddly specified as rv there is an alias.
For example, in a user string containing
rv:1.9.2.13 ... Gecko/20101203
you would specify this version of Gecko as gecko=~1.9.2.13.

This simple pub/sub model was inspired by jsTestDriver, which is a great tool
for running very fast unit tests. JS TestNet set out with a different goal:
run any kind of JavaScript tests, especially middle-tier integration tests
that do not lock down your implementation as much as unit tests. You may want
to mock out jQuery's $.ajax method and perform asynchronous Ajax calls -- go
for it!

JS TestNet's worker implementation was forked from TestSwarm, which is a
similar tool. JS TestNet is different in that it supports direct execution of
tests suitable for CI. Big thanks to John Resig for figuring out a lot of the
cross domain stuff and implementing retry timeouts, error handling, etc :)
Also, JS TestNet is dumber than TestSwarm in that it requires an adapter.