Browser Harness
What is this?
- Simple - Use jQuery to interact with items on the page and check expected conditions. Optional fibers support makes test writing and reading straightforward.
- Fast - Can perform 50+ actions per second in the browser
- Cross-browser - Tests run on any modern web browser, and even some old ones
- Flexible - Write tests in whatever node.js framework you want
Browser Support
Tested "Should work"
Chrome 4+ ✓
Firefox 3+ ✓
Safari 3+ ✓
Opera 10.61+ ✓
IE 5.5+ ✓
IE 8+ ✓
iOS ✓
Android ✓
PhantomJS ✓
SlimerJS ✓
Other ✓
How does it work?
- Your tests include the browser-harness module and tell it to start listening for connections
- Your test (or some outside process) opens a browser to http://your-test-site/path/to/harness.html?host=path-to-the-browser-harness-server
- Harness.html connects to the browser harness server, and begins running your tests
- Your tests will control a browser running within an iframe in harness.html
See it in action
A standalone example of using browser harness can be found under the browser-harness-bootstrap-tests repository.
Screencasts
Example
The following example uses mocha, but any test framework may be used.
//This little utility function helps reduce the boilerplate needed by each testvar { ;}; ;
Fibers support
The module has built-in support for fibers via asyncblock](https://github.com/scriby/asyncblock). To take advantage of it, all you need to do is install asyncblock from npm and wrap your test with it (see above for an example).
Browser harness will auto-detect that asyncblock is being used and turn all asynchronous calls into "blocking-style".
Note that using fibers to write the tests is optional, but it is highly recommended. See no-fibers.js for an example of writing tests without fibers.
Limitations
Due to the way browser harness interacts with the browser, there are a few limitations.
- Requires harness.html be served from the domain of the site/application being tested
- Warning: Be careful not to include harness.html in production, as it opens a potential cross-site scripting attack vector
- Can only interact with pages hosted from within a single domain (barring some CORS configuration)
- Can not upload files from the local computer (but should be able to spoof file uploads via javascript)
- Can not interact directly with cookies that have the httponly flag
Documentation
Tests
There are tests for browser harness located under the "tests" folder.
To run the tests:
cd tests
#Install test dependencies
npm install
#Run test with mocha. Set a 10 second timeout as sometimes it takes a bit for the browser to open initially
#You can also use your global mocha installation if you have it installed already
./node_modules/mocha/bin/mocha all_tests.js -R spec -t 10000
#Edit the test_browser file to run the tests in a different browser (defaults to phantomjs)
Roadmap
- More streamlined browser integration (windows)
- Handle alert, input, etc.
- Cookie handling
- SlimerJS integration
- Ability to take screen shots with phantomjs / slimerjs (possible with others?)
- Switch out NowJS support for plain Socket.IO for easier Windows support
- Better support detecting javascript errors in the browser
- Build in support for other event types like right click, mouse down, mouse up, keys, etc.
- More robust error handling
- See what can be done to make it easier to interact with file upload controls
- "Ease of use" improvements around common functions, like waiting for a specific page
- Documentation