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.
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).
You use the atlas-integration-test command to run integration tests explicitly. The command does the following:
<test> scope)pom.xml file's <build> section (for this tutorial, Jira)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:
1 2<build> <plugins> <plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>jira-maven-plugin</artifactId> <version>${amps.version}</version> <extensions>true</extensions> <configuration> <products> <product> <id>jira</id> <instanceId>jiraExpected</instanceId> <version>${jira.version}</version> <productDataVersion>${jira.version}</productDataVersion> </product> </products> <testGroups> <testGroup> <id>jira-integration</id> <productIds> <productId>jira</productId> </productIds> <includes> <include>it/**/*Test.java</include> </includes> </testGroup> </testGroups> </configuration> </plugin> ...
You can specify one or more <product> children in the <products> element. A <product> has the following fields:
| Field | Description |
|---|---|
id | Can be one of:
|
instanceId | Unique identifier for this product definition. |
productVersion | Version of the product to use. |
productDataVersion | Version of test data to use. |
You can specify one or more <testGroup> children in <testGroups> element. A <testGroup> has the following fields:
| Tag | Definition |
|---|---|
id | Unique identifier for the test group. |
productIds | Contains one or more
Alternatively, you can refer to a defined |
includes | Contains one or more <include> values. |
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 8.13 and Jira 8.5.
1 2<configuration> <products> <product> <id>confluence</id> <instanceId>confluence-7.13.0</instanceId> <productVersion>7.13.0</productVersion> <productDataVersion>7.13.0</productDataVersion> </product> <product> <id>confluence</id> <instanceId>confluence-7.4.11</instanceId> <productVersion>7.4.11</productVersion> <productDataVersion>7.4.11</productDataVersion> </product> <product> <id>jira</id> <instanceId>jiraExpected</instanceId> <productVersion>${jira.version}</productVersion> <productDataVersion>${jira.version}</productDataVersion> </product> </products> <testGroups> <testGroup> <id>allConfluence</id> <productIds> <productId>confluence-7.4.11</productId> <productId>confluence-7.13.0</productId> </productIds> <includes> <include>it/**/confluence/*Test.java</include> </includes> </testGroup> <testGroup> <id>jira</id> <productIds> <productId>confluence-7.4.11</productId> <productId>confluence-7.13.0</productId> </productIds> <includes> <include>it/**/confluence/*Test.java</include> </includes> </testGroup> <testGroup> <id>jira-integration</id> <productIds> <productId>jira</productId> </productIds> <includes> <include>it/**/jira/*Test.java</include> </includes> </testGroup> </testGroups> </configuration>
Accessing Test Instances
During each test execution, the build system sets the following system properties for each product definition:
| Property | Description |
| 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.
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_HOME directory for you plugin.
Enter the atlas-integration-test command:
1 2atlas-integration-test
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:
1 2------------------------------------------------------- T E S T S ------------------------------------------------------- Running it.com.example.plugins.tutorial.jira.testTutorial.MyComponentWiredTest SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder". SLF4J: Defaulting to no-operation (NOP) logger implementation SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details. [INFO] [talledLocalContainer] Nov 15, 2012 11:32:50 AM com.sun.jersey.server.impl.application.WebApplicationImpl _initiate [INFO] [talledLocalContainer] INFO: Initiating Jersey application, version 'Jersey: 1.8-atlassian-6 03/12/2012 02:59 PM' [INFO] [talledLocalContainer] Nov 15, 2012 11:32:51 AM com.sun.jersey.api.wadl.config.WadlGeneratorLoader loadWadlGenerator [INFO] [talledLocalContainer] INFO: Loading wadlGenerator com.sun.jersey.server.wadl.generators.WadlGeneratorApplicationDoc [INFO] [talledLocalContainer] Nov 15, 2012 11:32:51 AM com.sun.jersey.api.wadl.config.WadlGeneratorLoader loadWadlGenerator [INFO] [talledLocalContainer] INFO: Loading wadlGenerator com.sun.jersey.server.wadl.generators.WadlGeneratorGrammarsSupport [INFO] [talledLocalContainer] Nov 15, 2012 11:32:51 AM com.sun.jersey.api.wadl.config.WadlGeneratorLoader loadWadlGenerator [INFO] [talledLocalContainer] INFO: Loading wadlGenerator com.atlassian.plugins.rest.doclet.generators.resourcedoc.AtlassianWadlGeneratorResourceDocSupport Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.185 sec Results : Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
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.
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 PLUGIN_HOME/src/test/java/it/com/atlassian/plugins/tutorials/jira/testTutorial folder.
Create a MyComponentTrdTest.java file.
Edit the file and add the following code:
1 2import static org.junit.Assert.assertEquals; import org.junit.Test; public class MyComponentTrdTest { @Test public void testSomeFailure() { System.out.println("I RAN But failed..."); assertEquals("something failed","blah","boo"); } }
Save and close the file.
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 PLUGIN_HOME/pom.xml file.
Locate the <build> section.
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 <groupId> of com.atlassian.maven.plugins you should see the following:
1 2<plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>jira-maven-plugin</artifactId> <version>${amps.version}</version> <extensions>true</extensions> <configuration> <productVersion>${jira.version}</productVersion> <productDataVersion>${jira.version}</productDataVersion> </configuration> </plugin>
Define a <testGroups> section with two <testGroup> elements inside the configuration:
1 2<plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>jira-maven-plugin</artifactId> <version>${amps.version}</version> <extensions>true</extensions> <configuration> <productVersion>${jira.version}</productVersion> <productDataVersion>${jira.version}</productDataVersion> <testGroups> <testGroup> <id>wired-integration</id> <productIds> <productId>jira</productId> </productIds> <includes> <include>it/**/*WiredTest.java</include> </includes> </testGroup> <testGroup> <id>traditional-integration</id> <productIds> <productId>jira</productId> </productIds> <includes> <include>it/**/*TrdTest.java</include> </includes> </testGroup> </testGroups> </configuration> </plugin>
You defined a test group consisting of all the test files ending with WiredTest and another for traditional tests TrdTest. If you have multiple <testGroups> defined, you can run a subset of those groups by using the -DtestGroups=groupname flag on the command line.
Save and close the file.
Re-run atlas-integration-tests but only for the traditional tests.``
1 2atlas-integration-test -DtestGroups=traditional-integration
Surefire creates the PLUGIN_HOME/target/group-traditional-integration directory
Change directory to PLUGIN_HOME/target/group-traditional-integration/tomcat6x/surefire-reports directory.
List the directory contents.
You should see something simliar to the following:
1 2TEST-it.com.example.plugins.tutorial.jira.testTutorial.MyComponentTrdTest.xml it.com.example.plugins.tutorial.jira.testTutorial.MyComponentTrdTest.txt
Take some time and browse the contents of each file.
Try the command again without the -D flag.
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.
Rate this page: