JavaScript testing with Maven

This is a step-by-step instruction for integrating Jasmine testing framework with maven.

Requirements

• JDK 8+
• Maven 3.0.4+

Step 1: Configure POM file

Augment plgins section of the project's pom file with the following instructions:

		<plugins>
			<plugin>
				<groupId>com.github.searls</groupId>
				<artifactId>jasmine-maven-plugin</artifactId>
				<version>1.3.1.5</version>
				<executions>
					<execution>
						<goals>
							<goal>test</goal>
						</goals>
					</execution>
				</executions>
				<configuration>
					<webDriverClassName>org.openqa.selenium.phantomjs.PhantomJSDriver</webDriverClassName>
					<specRunnerTemplate>REQUIRE_JS</specRunnerTemplate>
					<jsSrcDir>src/main/web/ua/com/fielden/platform/web</jsSrcDir>
					<jsTestSrcDir>src/test/web/ua/com/fielden/platform/web</jsTestSrcDir>
					<customRunnerConfiguration>src/test/web/ua/com/fielden/platform/web/app/testspike/jasmine.txt</customRunnerConfiguration>
					<preloadSources>
						<source>vendor/require.js</source>
					</preloadSources>
				</configuration>
			</plugin>
		</plugins>

These instructions tells Maven to use maven-jasmin-plugin for testing JavaScript code. The most interesting part of these instructions is plugin configurations. The following is an explanation of the configuration options used in this example:

• <webDriverClassName>...</webDriverClassName> - tells plugin which web driver (web emulator) to use for running test cases. In our example org.openqa.selenium.phantomjs.PhantomJSDriver (PhantomJS web driver) is used. Next step shows where to download and how to install that web driver.
• <specRunnerTemplate>...</specRunnerTemplate> - tells plugin which html template to use to run jasmine unit tests. Fortunately maven-jasmine-plugin has two predefined templates: DEFAULT and REQUIRE_JS. If your JavaScript code and test are wrapped in RequireJS module then REQUIRE_JS template should be used otherwise DEFAULT template can be used.
• <jsSrcDir>...</jsSrcDir> - tells plugin where all JavaScript sources can be found. In our case all sources are in src/main/web/ua/com/fielden/platform/web directory.
• <jsTestSrcDir>...</jsTestSrcDir> - tells plugin where all Jasmine tests can be found. In our case all tests are in src/test/web/ua/com/fielden/platform/web directory.
• <customRunnerConfiguration>...</customRunnerConfiguration> - this option allows to specify file that contains additional instructions for script loader (mostly file paths, a URL, or a classpaths). When testing RequireJS modules this option should point to shim file. In our example shim file is located at src/test/web/ua/com/fielden/platform/web/app/testspike/jasmine.txt.
• <preloadSources><source>...</source></preloadSources> - defines the list of JavaScript source files that must be loaded before test run (it might be some third party JavaScript libraries). In our example only RequireJS library must be preloaded.

Other maven-jasmine-plugin configuration options can be found at http://searls.github.io/jasmine-maven-plugin/test-mojo.html

Step 2: Download and install PhantomJS

Download PhantomJS for preferred operating system from http://phantomjs.org/download.html (e.g. for Linux you can simple use wget such as wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2) and install it. After the installation please make sure that phantomjs executable is in your system's PATH by running phantomjs command in the terminal. Following is the instruction about how to install PhantomJS for Linux users.

• Download PhantomJS from http://phantomjs.org/download.html for preferred linux distribution (for 64-bit or 32-bit systems).
• Unpack the downloaded archive into phantomjs-<version> directory. <version> - version number (e.g. 1.9.7).
• Move the directory phantomjs-<version> to the /usr/local/phantomjs directory using the following commands:

   sudo mkdir -p /usr/local/phantomjs
   sudo mv phantomjs-<version> /usr/local/phantomjs

• Update system paths using the following commands:

   sudo nano /etc/profile

scroll to the end of the file and add the following instructions:

   PHANTOMJS_HOME=/usr/local/phantomjs/phantomjs-<version>
   PATH=$PATH:$PHANTOMJS_HOME/bin
   export PHANTOMJS_HOME
   export PATH

• Reload your /etc/profile with

. /etc/profile

P.S. In some cases reloading profile won't be enough. In that case restart your computer.

Step 3: Testing JavaScript with Maven

jasmine-maven-plugin has three available goals:

• jasmine:help - prints out information about how to configure this plugin.
• jasmine:test - runs all jasmine unit tests specified in your test directory. This test runner is headless.
• jasmine:bdd - Runs web server that allows one to run tests in the preferred browser. Also monitors sources and specs for changes during development, so that one can see test result after refreshing the web browser page.

One can run also mvn test. In that case Maven runs all the tests in the project including Jasmine unit tests.