Create and Run Traditional Integration Tests
This page explains the tools and processes you use in the Atlassian Plugin SDK, to create and run traditional integration tests for your plugin. The material on this page assumes you have already worked through or otherwise understand the information in Create and Run Unit Tests. On this page, you do the following:
Overview of Integration Testing
Integration testing validates the interactions between an Atlassian host application (JIRA, Confluence, Stash, etc.) and your plugin. Traditional integration tests typically used Mockito to replicate or mock-up functions in the host. Now, Atlassian offers the Wired Test Framework for integration and unit testing.
The Wired Test Framework allows you to test your plugin in the actual host application environment rather than against mocked functions. Thus, for example, if your plugin creates an issue in JIRA by invoking the JIRA API, the Wired Test Framework lets you invoke your plugin and then test whether an issue was actually created in JIRA.
If you have existing integration or functional tests, you can convert these to the new framework. You also have the choice of continuing to use your traditional integration tests. And, of course, you can use both the traditional and wired integration test in the same plugin.
There are several ways to execute integration tests and review the results—from the command line or from the test console in the host application's UI. The command line approach as described here compiles the project, starts up the application and executes all the tests. When writing and tweaking the test code itself, this may not be the most efficient manner of working.
As an alternative, if you are using the Wired Test Framework, you can use the test console in the application. The test console lets you modify test code and rerun the individual test you are working on and see the results of the test without having to recompile the plugin and restart the application. This is usually the most efficient manner of working when you are developing and tweaking test code. (The test console is described in the next page in this tutorial).
The atlas-integration-test Command
You use the
atlas-integration-test command to run integration tests explicitly. The command does the following:
- executes your unit tests (unit tests are part of the
- starts the host application configure in your
<build>section (for this tutorial JIRA)
- loads the application with some default data
- executes your integration tests
Just as with unit tests, the integration tests use Maven's Surefire plugin. Unlike unit tests, the
atlas-integration-test command starts a host application environment.
By default, the system runs all the tests defined in your project's
it package with the host application. You can configure additional information in the
<build> block of your
pom.xml file through the
<configuration> element. You can specify one or more <products> to test against. You can also use the
<testGroups> element to group integration tests. The following example illustrates both elements:
You can specify one or more
<product> children in
<products> element. A <product> has the following fields:
Can be one of:
||Unique identifier for this product definition.|
|Version of the product to use.|
|Version of test data to use.|
You can specify one or more
<testGroup> children in
<testGroups> element. A
<testGroup> has the following fields:
||Unique identifier for the test group.|
Contains one or more
Alternatively, you can refer to a defined
||Contains one or more
Through this configuration you can specify which tests to include in your integration tests and which products to run them against. You can even configure the build to run multiple versions of the host application or more than one host application. For example, you can run Confluence and JIRA together with your plugin tests. Or, you could run JIRA 5.0 and JIRA 4.0.
Accessing Test Instances
During each test execution, the build system sets the following system properties for each product definition:
The base url of the application, e.g.http://localhost:8990/jira
The HTTP port that the application is listening on, e.g.
The context path of the application, e.g.
Use these values to co-ordinate communication between your integration tests and running application instances.
Step 1. Run the Skeleton Integration Tests
When you created the plugin, the system generated an integration test class for you, the
MyComponentWiredTest.java file. You can find this file in your project's
PLUGIN_HOME/src/test/java/it /com/atlassian/plugins/tutorials/jira/testTutorial folder. As the file's name implies, the generated test files assume you plan to use the Wired Test Framework rather than traditional integration tests. This is really the recommended approach during the development phase.
However, you may have situations where you want to run your integration tests using traditional tools, from the command line. One such situation would be if you are building your plugin with Bamboo. In that case, you can still use the traditional Atlassian
atlas-integration-test command-line interface. The command executes only the
test scope as defined in your
pom.xml file (which also includes any unit tests you may have). Try the command now to run the generated test files:
- Go to a command line.
- Make sure you are in at the top level
PLUGIN_HOMEdirectory for you plugin.
Notice in command's output, the system runs the unit tests, starts the host application, and then runs your integration tests. The command output should succeed with test output similar to the following:
When you next run your plugin with
atlas-run, the command also runs both your unit and integration tests. If the build were to fail on unit or integration tests, the application does not start.
Step 2. Create a Traditional Integration Test
You may have existing traditional integration tests you want to maintain for some time. You can still do so. The difference between traditional tests and wired tests is the use of the
AtlassianPluginsTestRunner. If your tests omit the
@RunWith(AtlassianPluginsTestRunner.class) annotation, they are treated as traditional integration tests. Try adding a traditional integration test. If you haven't already done so, start Eclipse and open the testTutorial project you created.
- Go to the
- Create a
Edit the file and add the following code:
- Save and close the file.
Step 3. Configure Test Groups
When your tests run, Surefire creates a
PLUGIN_HOME/target/testgroupname directory to hold temporary files during the test generation and reports. At this point, you haven't defined any test groups. So, Surefire created a
PLUGIN_HOME/target/group-__no_test_group__ directory. Test groups are useful if you are running a lot of integration tests. You can create test groups that represents categories in your tests. Try this now.
While still in Eclipse and do the following to define a
<testGroup> for your integration tests.
- Open your
This section lists each plugin you are building. You are using a built-in Atlassian Maven plugin to run your plugin build. Locate the plugin with the
com.atlassian.maven.pluginsyou should see the following:
<testGroups>section with two
<testGroup>elements inside the configuration:
You defined a test group consisting of all the test files ending with
WiredTestand another for traditional tests
TrdTest. If you have multiple
<testGroups>defined, you can run a subset of those groups by using the
-DtestGroups=groupnameflag on the command line.
- Save and close the file.
but only for the traditional tests.
Surefire creates the
- Change directory to
List the directory contents.
You should see something simliar to the following:
Take some time and browse the contents of each file.
- Try the command again without the
Surefire creates a directory for each group.
In this page and the previous, you learned how to build, configure, and run tests. All the testing is run from the command line, this can make the development process time consuming and awkward. In the next section, you learn how to use wired test together with the test console to test your code and speed up development.