Atlassian plugins depend on Maven 2 for running their test suites. This is advantageous because all plugins are always tested the same way, and because Bamboo, our continuous integration server, can do likewise.

Building a suite of tests for your plugin is extremely important. We're big believers in Test Driven Development, and we think that writing tests as you go is one of the best ways to ensure you build a high-quality and functional application. Additionally, having a comprehensive suite of tests means that other developers in the community (or even Atlassian developers) can jump in and collaborate on your plugin without fear of breaking anything inadvertently.

Our products are always moving forward. We enhance and change things. We move or deprecate APIs. A plugin that works perfectly in Confluence 2.5 might change in Confluence 2.6, in subtle or profound ways. That's the primary reason that we run the Developer Bamboo Server – to alert us to any changes that might break plugins. When those breakages occur, we might be able to go back and do things another way that preserves compatibility. Or, at the very least, we can notify developers in advance of a new release about what has changed. Continuous Integration is a crucial safeguard, and it depends largely on a comprehensive test suite to alert us when things break.

Unit Tests

The first tests you should write for your plugin are unit tests. Unit tests are designed to exercise individual chunks of your code in isolation. To run unit tests, the default maven 'test' command works:

> mvn clean test

For examples of unit tests, take a look at the Confluence Chart Plugin test or the JIRA Fisheye Plugin tests.

Integration, or Functional, Tests

Integration Testing is designed to test your code inside the the Atlassian product. The goal is confirm that the plugin functionality works as designed, and is compatible with various versions of the product. To achieve this goal, Maven will actually deploy your plugin to a running version of JIRA or Confluence and then run tests that you write to exercise its functionality. To run integration tests, the command is:

> mvn clean integration-test

When you run this command, Maven will start up a new instance of JIRA or Confluence, running inside Tomcat, and install some default data into it: things like a license, database configuration, and an admin account. This will save you the effort of having to set up the product each time. It's important to note that the license installed is a unique one: it is perpetually valid, but only for a period of three hours (which should be more than enough time to run your tests.) Should you keep going longer than three hours, the license system will lock you out, and you'll need to restart it to proceed.

For examples of integration tests, take a look at the JIRA Fisheye Plugin tests. A Confluence example is forthcoming.

Skipping tests

To skip the various test phases, add one of the following options to your Maven command:

> -Dmaven.test.skip=true - skips both unit and integration tests
> -Dmaven.test.unit.skip=true - skips unit tests
> -Dmaven.test.it.skip=true - skips integration tests

Notes

Oftentimes, your functional tests will need to set up the product in a particular state. You may wish to do this by creating an XML export of JIRA or Confluence data in a known state, and importing that data at the beginning of your tests. XML data that is usually imported by the tests into the running product should be placed in src/test/xml/ directory provided.

Packages containing integration tests should start with it. For instance:

• it.com.atlassian.jira.plugins.fisheye
• it.com.atlassian.jira.plugins.calendar

This is due to inability of Maven to discriminate unit tests from integration tests. This will be resolved in the coming Maven 2.1 and we will take care of the migration for you then.

System Properties

The following system properties are available to control the behaviour of the integration test harness:

• tomcat.installer.url - path to the tomcat zip file to install. Default: http://repository.atlassian.com/maven2/org/apache/tomcat/apache-tomcat/5.5.20/apache-tomcat-5.5.20-jdk14.zip
• cargo.wait - if this is set to true tomcat will be started up and then cargo suspends allowing you to manually access this JIRA from the browser.
• confluence.version / jira.version - version of JIRA to compile and test against. default is 3.10.2
• confluence.data.version / jira.data.version - version of the test resource bundle that contains the basic JIRA configuration data for the integration test environment. These versions mimic the actual JIRA versions. However we might only modify and release this project for the reasons of non-backwards compatibility of the new versions of JIRA. Therefore not every version of JIRA will have a corresponding version of the resource bundle. By default this is set to 3.10.2 which should be migrated and work correctly with the newer versions.
• jira.test-lib.version - version of jira-func-tests JAR to compile and test against. default is 3.10-DEV (JIRA only).
• confluence.url / jira.url - base URL for this instance of JIRA. Default: http://localhost:$http.port/jira/
• http.port - port on which this instance of JIRA will be accessible on. Default: 8989
• rmi.port

Debugging your failing tests

All of the necessary output generated by tests will be found under target subdirectory of your module. The following files are useful places to look at dire times:

• surefire-reports/*.txt - a log file per test class of failed tests (both unit tests and functional tests)
• cargo.log - the log file of cargo trying to deploy jira and start or stop the tomcat
• output.log - the log file of tomcat and jira to which the plugin is deployed for functional testing