Jenkins CI integration

When integrating Intern with Jenkins, there are two primary ways in which the integration can be completed: either creating a new project that executes as a post-build action for your primary project using a shared workspace, or by creating a multi-step free-style software project that executes Intern after the first (existing) build step. For projects that are already using Maven, a third option is to execute Intern using exec-maven-plugin from an existing pom.xml.

Intern as a post-build action to an existing project

This option enables you to use an existing build project by adding a new project that executes unit tests in a separate job from the main build. This option is ideal for situations where you want to be able to manage the build and testing processes separately, or have several projects that need to be built downstream from the main project that can occur in parallel with test execution.

In order to accomplish this efficiently without the need to copy artifacts, use of the Shared Workspace plugin is recommended. To install and configure the Shared Workspace plugin, follow these steps:

1. Install the Shared Workspace plugin from the Jenkins → Manage Jenkins → Manage Plugins page.
2. Go to the Jenkins → Manage Jenkins → Configure System page.
3. Under Workspace Sharing, add a new shared workspace. For the purposes of these instructions, this shared workspace will be called “myApp”.
4. Save changes.

Once the Shared Workspace plugin is installed, all projects that need to share the same workspace must be updated. The shared workspace for each project can be selected from the first section of the project’s configuration page.

Once the main project is set to use the shared workspace, the new unit test project should be created:

1. Create a new free-style software project, e.g. “myApp-tests”.
2. At the top of the configuration, change the shared workspace to “myApp-tests”.
3. Under “Source Code Management”, leave the “None” option checked. Because of the shared workspace, source code checkout will be handled by the upstream project.
4. Under “Build triggers”, check the “Build after other projects are built” checkbox. Enter the name of the existing Maven project in the text box that appears. (This will create a corresponding post-build action to build “myApp-tests” in the existing project’s configuration.)
5. Under “Build”, click the “Add build step” button and choose “Execute shell” from the drop-down.
6. Under “Execute shell”, enter the command you want to use to run Intern. See the Running Intern section for possible commands.
7. Save changes.

Once this project has been configured, test everything by running a build on the main project. Once the main project build finishes successfully, the new “myApp-tests” project will begin executing automatically.

Intern as part of a free-style software project

When working with an existing free-style software project it is possible to simply add the unit testing as an extra build step, following steps similar to the above:

1. Open the configuration page for the existing free-style software project.
2. Under “Build”, click the “Add build step” button and choose “Execute shell” from the drop-down.
3. Under “Execute shell”, enter the command you want to use to run Intern. See the Running Intern section for possible commands.
4. Save changes.

Intern as an execution step in a Maven pom.xml

Intern can be executed by Maven from a pom.xml during the test or integration-test phases of the build by using the exec-maven-plugin to spawn a new Intern process:

<plugin>
	<artifactId>exec-maven-plugin</artifactId>
	<groupId>org.codehaus.mojo</groupId>
	<version>1.2.1</version>
	<executions>
			<execution>
			<id>run-tests</id>
			<phase>test</phase>
			<goals>
				<goal>exec</goal>
			</goals>
		</execution>
	</executions>
	<configuration>
		<executable>node_modules/.bin/intern-runner</executable>
		<arguments>
			<argument>config=tests/intern</argument>
		</arguments>
	</configuration>
</plugin>

The executable and arguments elements should be modified to run Intern using your desired client and configuration.

Additional Jenkins test report options

It is also possible to retrieve and display code coverage results within Jenkins by using the Cobertura plugin for Jenkins along with the cobertura reporter for Intern by adding the “Publish Cobertura Coverage Report” post-build action to any project that runs Intern. The coverage report generated by Intern’s cobertura reporter will be written to cobertura-coverage.xml in the root workspace directory.

Future improvements to Intern will include a JUnit/xUnit reporter that can be used to display test results within Jenkins in a more user-friendly manner than having to view the raw console log output. This will be enabled by the “Publish JUnit test result report” post-build action once the corresponding Intern reporter is available.