Add Javascript unit tests and run them with “grails test-app”

Client-side JavaScript code typically doesn’t get as much testing as back-end code, but with technologies like AngularJS becoming popular, more logic is making its way to the front-end, creating a higher need for tests. Fortunately with frameworks like Jasmine and Karma, and with a little help from the karma-test-runner plugin, we can treat our JavaScript logic with the same respect as our Grails code. The steps to make this happen include:

1. Adding Jasmine to our project.
2. Installing Node.js and npm.
3. Installing and configuring Karma and its plugins.
4. Installing the Grails karma-test-runner plugin.

My focus will be to keep a pretty minimal approach while still explaining each step of the way. This is intended to get you up and running with basic knowledge as quickly as possible.

Jasmine

The first step is to add Jasmine to our project, so we can actually test our code. The easiest way is to navigate to the master distributions and download the standalone files from there. Be sure to remember which version (e.g. 1.x or 2.x) you are using so you can grab the correct Karma adapter later.

Go ahead and create a “javascript” directory under “test/unit/”, then move and unzip Jasmine into there. You can use a different location if you prefer, but be aware that using “web-app/js/” is not typically recommended. Inside the jasmine-standalone directory, “lib/” contains the core framework, while “src/” and “spec/” have sample JavaScript files and Jasmine tests, respectively. Save these for now as we will use them to ensure proper setup.

Node.js and npm

The next step we need to take is to install Node.js and npm (not really an acronym), which are required to install and run Karma and its plugins. The exact steps can vary slightly by platform, but the easiest way is to navigate to the download section and grab the files appropriate for your platform. You can also use NVM (Node Version Manager) on OSX and Linux. Either way, be sure to install npm as well (enabled by default).

Once that is complete, we should be ready to install Karma.

Karma and plugins

Karma is the test runner we’ll be using to actually execute our Jasmine tests from earlier. Installation is pretty simple, and the only major decision we need to make right now is whether to install globally or locally. Karma recommends local installations, so that each individual project can rely on different versions, plugins, etc. The ultimate decision is up to you, and you can (almost) always mix-and-match. The difference in syntax means using the “-g” flag for global, or optionally “–save-dev” for local installation.

So let’s install Karma and the plugins we’ll be using. I’ll expand on what each one does after the code block:

The first line uses npm to install Karma globally. Again, it’s up to you if you prefer a local installation.

The next line installs the karma-jasmine adapter for Jasmine 2.0. The ‘@2_0’ part is important, or we would be installing the adapter for the 1.x line of Jasmine, which will throw errors when run. Of course, if you’re using Jasmine 1.x, be sure to install the adapter for that version.

Following that, we install the PhantomJS launcher, the headless “browser” we’ll be using. Feel free to use another browser launcher instead. The full list is available here. You can even configure multiple browsers, which will run the tests on each one in succession.

Next we install the remote reporter plugin so that the test results can be sent over to a specified server. This is necessary for the Grails plugin to function.

Lastly, we globally install the karma-cli plugin as recommended so we can run the “karma” command anytime from our terminal. This one isn’t necessary, but I’d highly recommend it.

At this point we can enter:

to see the Node modules we have installed locally and globally. You should also notice a “node_modules/” directory with all the locally-installed plugins, which you may want to add to your “.gitignore” file, although the npm FAQ lists a few rules of thumb.

Hopefully everything installed without a hitch so we can move on to the next step!

Configuration

At this point we have all the components installed but we still need a config file to tell Karma what to run. The easiest way to do this is to type:

This will prompt you with some some basic questions such as which testing framework you wish to use (Jasmine), and which browsers you want to capture . Pick whichever one(s) you installed the packages for above, but if you’ve changed your mind, it will install the proper launcher(s) for you anyway.

Karma will also ask for the patterns or locations of the JavaScript files and tests you want to run, so be sure to include the Jasmine framework along with the two Jasmine sample directories from earlier (“src/” and “spec/”). This is where you would include your tests and JavaScript files, as well. Once that is finished, you should have a “karma.conf.js” file in your working directory. Go ahead and open it, and you’ll see some preconfigured and commented properties. If you want, you can move this into the same parent directory as Jasmine, just be sure to set the “basePath” property.

At this point you have two options. If you wish to get live feedback on your tests (particularly useful when writing new tests), then make sure the following properties are set as below:

If however, you want to run these via the plugin (and via “grails test-app”), you can use:

If you need per-environment configurations and are using GruntJS, you can run grunt-karma although I won’t go into that here.

I’d actually recommend loading the first configuration regardless and running it with:

Be sure to resolve any issues before moving on to the Grails plugin section. Once you have, congrats! You now have a testing framework for your JavaScript code.

Grails karma-test-runner plugin

The last step allows us to run the JavaScript tests along with all of our other ones, via the command:

This is made possible through the Grails karma-test-runner plugin. We’ve already downloaded the karma-remote-reporter plugin and configured our “karma.conf.js” file, so all we have left is to make Grails aware of it!

First add the plugin dependency to your BuildConfig’s plugins section:

Then add a Groovy test ending with “KarmaSuite” to your “test/unit/” (or “test/unit/javascript/”) directory as recommended by the plugin, and set the path to your Karma config:

Bear in mind that the config path is hard-coded, so you may want to look into GruntJS as mentioned above if you need different configs per environment.

You should be able to run JavaScript tests alone with:

or run them with the whole suite via:

Now you can sleep a little more soundly knowing your JavaScript code has some basic assertions!

Leave a Reply

Your email address will not be published. Required fields are marked *

*

*