Create and Run Unit Tests
This page explains how to create and run unit tests in a plugin. You should you have already worked through Generate and Examine Skeleton Tests. The Atlassian Plugin Framework requires that you use JUnit 4.10 or higher. By default, the SDK 4.1 (and higher)
atlas- commands all generate a
pom.xml file with a dependency on the appropriate JUnit version. If you are working with an older plugin, you should make sure to update JUnit
<version> value to 4.10 before continuing.
JUnit Quick Reminders
You use JUnit to annotate test methods in your plugin. These annotations instruct and inform the JUnit framework how to interpret your test. The following table provides a short refresher of some common JUnit annotations:
||Release external resources allocated in the
||Release expensive external resources shared among tests. These are allocated in the
||Create resources or prepares an environment before each
||Performs expensive environment setup or creates expensive resources shared among tests.|
||Identifies a test method.|
Recall that JUnit tests can run in any order. In fact, the order varies across different Java versions. So, remember to keep each unit test independent of another. If your tests are dependent, and they run in a different order than you expect, you may find it difficult to debug test failures. Test failure is another reason to keep your tests independent. If your tests are dependent, the failure of one can cause the remaining tests to fail.
Step 1. Run the Generated MyComponentUnitTest
When you created your plugin, the system generated a skeleton
MyPluginComponent.java class. This class has a
getName() method whose implementation relies on the Shared Access Layer (SAL)
com.atlassian.sal.api.ApplicationProperties API. You'll find a unit test of this method in your
When you next run your plugin with
atlas-run, the command also runs your unit tests. Often, you only want to run your unit tests, you use the
atlas-unit-test command to do this. The command executes only the
test scope defined by the project
pom.xml file. Try the
atlas-unit-test command now:
- Go to a command line.
- Change to your plugin's top level
The command output should contain test output similar to the following:
You can see that the generated unit test was successful.
Step 2. Create a Failing Unit Test
The build fails when one of your tests fails. Let's see how this work by adding a failling file. If you haven't already done so, start Eclipse and open the
testTutorial you created.
- Edit the
Add a new method to the file:
- Edit the
Add the following code to the file:
The plugin method adds two numbers together.
- Save and close both files.
- Locate the
Edit the file and add the following unit test code:
You should now have one passing test and a new one that should fail.
- Close and save the file.
- Go to a command line.
- Make sure you are in at the top level
PLUGIN_HOMEdirectory for you plugin.
The failing test returns output similar to the following:
With a failing test, the Maven build reports an error. If you were to run
atlas-runat this point, it would fail also because you have a build error. If you have some time, try the
Step 3. Surefire Reports for Your Tests
The Atlassian Plugin SDK uses the Maven Surefire Plugin during the
test phase to run your tests. Running
atlas-unit-test creates a
PLUGIN_HOME/target/test-classes directory containing your compiled test. Surefire also creates a
PLUGIN_HOME/target/surefire directory to hold temporary files during the test generation. After the test phase completes, Surefire generates a
Take a moment and examine the Surefire report generated by your testing:
- Change directory to
List the directory contents.
You should see something similar to the following:
Both files are Surefire report files. Each time your tests you overwrite these files.
- Take a minute and review the contents of each file.
The XML report includes a set of environmental properties used in the test.
@Ignore annotation is useful if you want to skip a test you know is obsolete or you just aren't ready to use. Sometimes, during development, you may encounter tests that fail for other reasons. Remember the
atlas- commands that start a host application with you plugin installed, also runs your tests. Failing test are inconvient if you just want to do
atlas-run and see your test in a host application. Go ahead and ignore the failing test in your sample code:
- Edit the
Add an import for the JUnit @Ignore annotation.
@Ignoreannotation to the
- Save and close the file.
Rerun your unit tests.
You should see that only a single test is run, the first, the framework skips the other:
Step 4. Alternative Ways to Run or to Skip Tests
Both Eclipse and IDEA allow you to run JUnit tests from within your IDE. If you are following along with this tutorial exactly, you should be using Eclipse. Go ahead and try this now:
- Edit the
- Remove the
@Ignoreannotation you added in the previous procedure.
- Save the file.
- Select Run As > JUnit Test.
You should see output similar to the following:
- Go to the command line.
- Change to your
Very quickly the
testAdd()method fails, the build does not complete, and
atlas-runexits without launching the host application.
Rather than editing your tests to fix the failure, which can be time consuming when you many tests, skip all tests from the command line by entering the following:
It may have crossed your mind that skipping tests in general may be a good idea if you just want to run the host application and your project has a lot of tests!
In the next section, you learn about the tools and processes for running traditional integration tests.