Command-line interface tool to test Web applications from the command-line. The tool runs suites of tests written with Jasmine in some Web browser (Chrome, Firefox, Safari, PhantomJS, Android) using WebDriver.
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:
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 email@example.com:joshfire/angela.gitcd angelanpm install
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.
Install Angela and create a file named
sweet.spec.js that contains:
Then ask Angela to run the test:
After a couple of seconds, you should see something like:
Running 1 spec tests...Progress--------Angela is very sweet... passedSummary-------1 spec run in 1 second.no failure.
angela --help for usage information. This should output something like:
Angela - Copyright (c) 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 for spec files incurrent working directory.Options:--browser, -b Webdriver browser endpoint. The code automatically startsthe "right" Webdriver server based on that setting.Possible values include "phantomjs", "chrome", "firefox","safari", or "android" (provided browser or device isavailable on your machine). [default: "phantomjs"]--before JS file to "require" before tests are run. Use this optionto add custom matchers or expose additional variables tothe global scope as needed. Code must be synchronous.--after JS file to "require" after tests have run. Use this optionto run custom code when execution is over. Code must besynchronous.--host Webdriver server host [default: "localhost"]--port Webdriver server port [default: 8195]--verbose, -v Trace Angela's execution to the console [default: false]--serverlog Log Webdriver server execution to provided log file[default: ""]--useserver Whether to use running Webdriver server or to start one[default: false]--printerrorstack Print stack trace when a test fails because of anexception. This makes failure reports potentially quiteverbose but can greatly help you track down the origin ofthe exception. [default: false]--sessionperspec Angela uses the same browser session throughout bydefault. Set the flag to use one browser session per spec.Specs will run considerably slower. [default: false]--keep, -k Whether to keep the browser open when tests are over[default: false]--junit Create JUnit XML reports (in "junitreports" folder)[default: false]--help, -h Displays usage help
When run without parameter or option, Angela lists all files that end with
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).
path parameter to the spec file to run or to the folder that contains the spec files to run to override default behavior.
--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:
phantomjsvalues use the default Selenium standalone server and should work in all sorts of environments provided
javais available from the command-line.
chromevalue 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.
safarivalue will only work provided a recent version of Safari is available.
androidvalue will only work provided you have a Linux-based OS (to run the small bash script), Android's SDK
adbtool 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 (*)
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
(*) 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
Test files are regular Jasmine spec files. On top of the usual Jasmine functions (
expect), the spec files can interact with the global
driver variable to send commands to the running Web browser through WebDriver.
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.
examples folder contains a number of examples to help you get started. To run the above example from the root folder of Angela:
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.
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)
examples folder contains an example that may be run with:
angela examples/sweet.spec.js --before examples/matchers.js
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.
--junit option generates JUnit XML reports in the
junitreports folder. This lets you integrate Angela pretty easily with continuous integration servers such as Jenkins.
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
Angela is licensed under the MIT license. Copyright (c) 2013 Joshfire. All rights reserved.
Angela uses great open-source libraries: