Angela
Angela is a Node.js test runner for acceptance tests written with the Jasmine JavaScript testing framework and Selenium's WebDriverJS implementation of the WebDriver API. In other words, Angela helps test a Web application from an end user perspective with scenarios such as:
;
Tests are run in PhantomJS by default but can equally run in Chrome, Firefox, Opera, Safari or Android thanks to the --browser
option (some of them are platform-dependent).
Angela sets things up so that you can focus on actually writing tests and not lose time figuring out the libraries to install and the servers to run:
- it starts the right WebDriver server for the targeted Web browser
- it creates the Webdriver session, one for all tests by default or one per suite of tests if so requested
- it exposes the WebDriver instance in test files
- it reports WebDriver errors as test failures
Installation
To install Angela globally with npm:
npm install -g angelaangela --help
This may take a couple of minutes as Angela includes a few binary files (~50Mb). If you prefer, you can clone the source code to your machine:
git clone git@github.com:joshfire/angela.git
cd angela
npm install
The angela
program is an alias to the lib/runner.js
script in the source code. If you are looking at the source code of the tool and wondering how to run it, just type: node lib/runner.js --help
.
Getting started
Install Angela and create a file named sweet.spec.js
that contains:
;
Then ask Angela to run the test:
angela sweet.spec.js
After a couple of seconds, you should see something like:
Running 1 spec tests... Progress--------Angela is very sweet... passed Summary-------1 spec run in 1 second.no failure.
Usage
Run angela --help
for usage information. This should output something like:
Angela - Copyright 2013 Joshfire. All rights reserved. CLI tool to run Jasmine test suites against a Web application that runs in aWeb browser controlled with WebDriver. Usage: /Users/fd/bin/angela [path] Parameters: path Spec file or folder that contains the spec files. Spec file names must end with ".spec.js" or "Spec.js". The tool will recurse through subfolders to list spec files. If no path is given, the tool will search
Execution
When run without parameter or option, Angela lists all files that end with .spec.js
or Spec.js
in the current working directory (and its subdirectories), starts a PhantomJS server in the background that exposes a WebDriver endpoint on port 8195
and runs the spec files it found against PhantomJS. It reports the results to the console.
Spec files are run one after the other using the same browser session unless you set the --sessionperspec
flag (this does slow down execution quite a bit, though).
Set the path
parameter to the spec file to run or to the folder that contains the spec files to run to override default behavior.
The --browser
option lets you change the targeted Web browser. Unless you also set the --userserver
option or set the --host
option, Angela will try to start the right WebDriver server on your local machine to interact with the targeted Web browser. This may or may not work depending on the operating system you are running:
- The
firefox
,opera
andphantomjs
values use the default Selenium standalone server and should work in all sorts of environments providedjava
is available from the command-line. - The
chrome
value will only work on a Mac. It should be straightforward to check the platform when the tool is run and run the appropriate ChromeDriver, that's just not done at this stage. - The
safari
value will only work provided a recent version of Safari is available. - The
android
value will only work provided you have a Linux-based OS (to run the small bash script), Android's SDKadb
tool in your path, one and only one connected Android device or emulator instance, and that the Android Webdriver server application has been installed onto that device (*) - Other values (e.g.
internet explorer
) are not supported by Angela, meaning that you need to set the right Webdriver server on your own and tell the tool to use that server with the--useserver
option.
(*) To install the Android Webdriver server application to the connected device or emulator instance, run the following command from the root folder of Angela:
adb install drivers/android-server-2.32.0.apk
Spec files
Test files are regular Jasmine spec files. On top of the usual Jasmine functions (describe
, it
, expect
), the spec files can interact with the global driver
variable to send commands to the running Web browser through WebDriver.
;
Angela ships with version 2.0 of Jasmine, which introduces a number of changes that ease authoring of asynchronous tests in particular.
The driver
instance is the one exposed by the Selenium's WebDriverJS library. Check its documentation for usage. In particular, note the use of promises and the fact that WebDriverJS manages the underlying control flow for you, allowing you to write scenarios in a synchronous way if you so wish (as in the Getting started example) or using promises all the way down as in the above example.
The closest thing to a useful documentation of methods you can use is Selenium's Javadoc, starting from the WebDriver class. Next in line is the WebDriver W3C Working Draft.
The examples
folder contains a number of examples to help you get started. To run the above example from the root folder of Angela:
angela examples/test.spec.js
Each test must complete within 30 seconds (or 2 minutes if tests are run on an Android device). That setting cannot be changed for the time being but could easily be exposed in a future version of the tool if that seems useful.
Custom matchers
If you want to define custom matchers shared by all your test suites, use the --before
option to target a JS file that defines the matchers with code such as:
;
(For those used to previous versions of Jasmine, note that the interface to describe matchers has changed in version 2)
The examples
folder contains an example that may be run with:
angela examples/sweet.spec.js --before examples/matchers.js
Unit tests
While Angela is designed to run acceptance tests, you may also use it to run unit tests written with Jasmine. It just seems a bit overkill to use Angela if you only have unit tests as the instance of PhantomJS that the tool runs in the background is simply useless when unit tests are run.
Integration with continuous integration servers
The --junit
option generates JUnit XML reports in the junitreports
folder. This lets you integrate Angela pretty easily with continuous integration servers such as Jenkins.
Cleanup
Angela closes everything it can on exit. Set the --keep
option to tell Angela to keep everything alive as long as you do not hit Ctrl+C
. This can be useful to continue browsing afterwards, e.g. to detect other things worth testing.
Things can get a bit messy from time to time with WebDriver as servers sometimes crash for no apparent reason. If Angela reports weird results and refuses to run again, there may be some server still running in the background. A few commands that may help detect processes that should not be around in a Linux based environment:
ps aux | grep adbps aux | grep phantomjsps aux | grep selenium
License
Angela is licensed under the MIT license. Copyright (c) 2013 Joshfire. All rights reserved.
Angela uses great open-source libraries:
- Jasmine. Copyright (c) 2008-2013 Pivotal Labs. MIT Licensed.
- optimist. Copyright 2010 James Halliday (mail@substack.net). MIT/X11 license
- PhantomJS. Copyright 2010-2013 Ariya Hidayat. BSD License
- npm wrapper for PhantomJS. Copyright 2012 The Obvious Corporation. Apache License 2.0
- Selenium, including WebDriverJS, licensed under an Apache License 2.0
- trycatch. Copyright (C) 2011 by Adam Crabtree (dude@noderiety.com). MIT License
- walk. Copyright (c) 2011 AJ ONeal. MIT license
- Woodman. Copyright (c) 2013 Joshfire, all rights reserved, MIT licensed