Use WebStorm to Run Protractor

I've recently started playing around with unit testing. At first I looked at using Jasmine with Karma, and in Visual Studio there's a fabulous plugin called Chutzpah that can do some cool things in relation to testing. However, my company has yet to pick up unit testing and so a couple of months passed without me looking into it again. Then I went to an AngularJs meetup in London where Julie Ralph from Google talked to us about Protractor, which is a test framework designed with testing AngularJs in mind. I was blown away with the way it ran real browsers and sent real user interactions to the browser in order to complete e2e testing, and decided that I needed to look into it further.
(This is a talk Julie Ralph gave at ng-conf about Protractor. This isn't the same as the one I saw but covers the same bases and is well worth watching.)

I'll talk about the amazing stuff that Protractor can do in posts to come. For me what really made it was being able to run the tests from within WebStorm itself. This is a guide to installing all the pre-requisites for Protractor and setting it up within the IDE.

Install Protractor

Protractor requires node.js installed first. Once you have, run the following command on the command line:

npm install -g protractor

Then check your version (and that it's installed) by running:

protractor --version

At time of writing the version that came down was 1.3.1. Once this is installed you'll need to update the selenium standalone server that is part of the installation by running:

webdriver-manager update

Protractor uses this server to serve your site when running your tests. Once everything is up to date you can start the server by running:

webdriver-manager start

You'll need to run this command a lot as this needs to be running in order to run your tests. Once you've run this command you'll need to leave the command prompt alone as it is now running the server processes, and any output from the server will appear here. If you want to run any further commands then you'll need to open a new instance of the command prompt. If you want to stop the server (or any other process through the command prompt) hit Ctrl+C twice.

Try starting the server. If you have a fresh Windows build then you'll probably get an error like this:

'java' is not recognized as an internal or external command,
operable program or batch file.
Selenium Standalone has exited with code 1

Now you need to install the Java Development Kit. Unless you have any particular needs the standard installation will suffice. If you've had to install this then you'll need to restart your command prompt before you can attempt to start the server again. If you get a Windows Security Alert dialogue appear about letting Java through the firewall I would recommend selecting allowing it through private networks and not public ones as you are only going to be using this for loopback. However, I am not a security, server, or networking expert so please take this under advisement.

Protractor Configuration

Once you've got the server running you'll have exposed http://localhost:4444/wd/hub. The first thing to do is to write a configuration file using JSON to describe where your tests are and which browsers to run them in. First create a directory in the root of your project's script directory called tests or test, or something equally descriptive that fits your paradigm. In the root of that directory create a JavaScript file called conf.js (or whatever you like). The most basic configuration will look like this:

exports.config = {
    seleniumAddress: 'http://127.0.0.1:4444/wd/hub',

    specs: [
        'spec.js'
    ],

    capabilities: {
        'browserName': 'chrome'
    }
};

seleniumAddress: This is the same for everyone
specs: An array of locations to find test scripts, using paths relative to this configuration file's location
capabilities: An object of configuration for the browser to run your tests in
or alternatively
multiCapabilities: An array of objects, each containing configuration information for a browser to run your tests in - allowing you to run your tests in multiple browsers:

multiCapabilities: [{
  browserName: 'firefox'
}, {
  browserName: 'chrome'
}]

There's lots more that can be done in the configuration file, head over to the example file for more details. The above has been fine for me until now, the only thing I might change is the specs location. As my projects grow in size I may choose to split the tests out to match the directory structure of my javascript files. If that becomes the case then I'll change the specs location to /**/*.js meaning all JavaScript files within all sub-directories of this location.

Protractor will allow you to use the Mocha or Cucumber frameworks for writing your tests. However, by default it supports Jasmine, and as I'd already played around with Jasmine I decided to stick with it. For further information on working with other testing frameworks check out their setup guide.

Run Protractor from the Command Line

Before you setup Protractor to run it's worth running this from the command line to see what it looks like. Let's quickly write a test so that we have something to run. In the root of your test folder create a file called spec.js (or whatever else you put in your configuration file to be your test file name). In there pop in the following code:

describe('a quick test', function(){
  it('should be true', function(){
    expect(true).toBe(true);
  });
});

I'll talk about what all this means in further posts, for now just trust that this should be a successful test. Now drop into the command line and navigate to the directory of your configuration file (use cd <yourTestDirectory>). Once here run the following command:

protractor conf.js

Where conf.js is the location of your configuration file. Remember, you need to have selenium running in another command prompt window. You'll see something like the following as your test runs in the window you triggered the test:

Something like this will have happened in the Selenium window:

And you'll also notice a new instance of Chrome (and/or any other browser that you've configured Protractor to use) pop up and close again. As you see in the Protractor command prompt it shows that there was one test run, with one assertion, and no failures. It's also in green, so you know at a glance that it's a good thing. Now go back to your spec.js and change one of the trues to false, then re-run Protractor.

You'll notice that this time it says that one test failed (well, true isn't false). It prints out the test name where the assertion failed and a stack trace. This time the result is in red, so obviously a bad thing. In both these scenarios you'll receive the same output when you configure WebStorm to run Protractor, so you won't be loosing any functionality by not running the tests manually on the command line.

Setup WebStorm

The first thing you need for setting up WebStorm is the location of Protractor's cli. As you installed Protractor with the -g flag it will be in Node's global location. By default this is C:\Users\<user>\AppData\Roaming\npm\node_modules. If you can't see the AppData directory in your user directory it's probably because you have system folders hidden (default in Windows). You can set these to show in Folder Options. This is in a different place in nearly every version of Windows, so have a Google of how to show system folders in your particular version of the OS. In here you'll find a list of directories, one for each globally installed Node package. Within the Protractor directory you should be able to find lib\cli.js. All put together for me the location is C:\Users\<user>\AppData\Roaming\npm\node_modules\protractor\lib\cli.js. Open up your project within WebStorm. In the top right corner of the IDE you'll have a row of buttons, such as below. Click the downward arrow and the click Edit Configurations...

When the new dialogue appears click the green plus in the upper left corner, and select Node.js from the drop down list. Give the new configuration a name, I've called mine Protractor. Leave all pre-populated fields as they are. In the JavaScript file field enter the location of the cli.js that we found above. In the Application parameters field put the location of your configuration file relative from the root of your project. For me this is scripts\tests\conf.js. That's it. Click OK, and when you return to the IDE you'll notice the buttons shown above have changed slightly.

The green triangle will run the tests for you in the same manner as we saw earlier on the command line, but within the IDE. The little green bug next to it allows you to run the tests and debug them. This means that you can place break points in your test file and see what's happening as they run through. Return your test file to expect true to be true. Click the run button and watch your tests run in WebStorm. You'll see a new panel open up where the command line output will be displayed.

There you have it. WebStorm running Protractor tests.