What it is?
We're at alpha! The API and functionality may change at any time. Use at your own risk.
This is a workflow problem. Developer writes his/hers code in one application, then changes the view to a browser, refreshes that browser and then visualizes the changes. In the ideal world these tests should be executable directly in the editor. This is what Phantom Runner tries to achieve.
In order to use Phantom Runner you need three things:
- Install latest version of PhantomJS
- Create a separate JUnit class and configure it to use PhantomRunner
- Write some Jasmine tests
After this you can execute the created JUnit test class in your favourite environment, for example in Eclipse you can use the normal right click -> run as -> JUnit test to run your Jasmine tests.
Configuring PhantomRunner JUnit runner
An example configuration for PhantomRunner would be:
Let's go through the @PhantomConfiguration annotation settings and what they do:
- phantomPath: defines the path where the PhantomJS executable can be found. Usually it is a good idea to add it to your operating system's path so you won't cause a system specific dependency into your PhantomRunner configurations.
- tests: a ant-style path pattern which is used to scan for the Jasmine tests. This is done relative to the JVM execution path, thus usually it is the root of your project
- PhantomJettyServer: Launches an embedded Jetty and ties PhantomJs with it through websockets.
- PhantomJsServer: Launches the PhantomJS embedded web server and Java code sends HTTP requests to this server telling it what to do. Please note that currently the port configuration does not affect PhantomJsServer!
Basically these server implementations are used to first initialize a specific test run (meaning, one Jasmine test file) and then to execute each of these tests one at a time. This allows a more refined integration with JUnit which can provide execution times and so on since the control of running each test is at Java side. This architectural design will allow (in the future, not in 0.1) also integration with real server implementations which would allow you to run full system level tests with Phantom Runner using PhantomJS.
PhantomJsServer starts up a lot faster than PhantomJettyServer which makes it ideal for small test suites. When your test suites get bigger however then PhantomJettyServer will be the faster one since it's websocket based communication is way faster than common HTTP requests and responses.
Good to know
Since Phantom Runner controls an external process which it runs few things need to be remembered:
- PhantomJS process can get "stuck", this means that if you forcefully terminate the test execution run (kill it, not send sigterm) then JVM doesn't get a chance to kill the PhantomJS process. Sometime this might be necessary to do: for example if your code ends up in an infinite loop. If this happens then please remember to kill the PhantomJS process manually via your operating system's process management ("kill" in *nix, task manager in Windows).
- Please be certain that proper execution rights are set so that Phantom Runner can actually start the PhantomJS process
- Phantom Runner cannot completely replace your browser based test execution. It is effectively using only one browser - PhantomJS - and there's a whole bunch of other browsers out there. You should create system level tests with more traditional ways (eg. Selenium) which will execute your code in the real browsers. Most of the bugs should be catched by your Phantom Runner/Jasmine tests - let your system level tests catch the browser differences