In the world of Test Driven Development (TDD), writing tests is part and parcel of the development process. I don't want to bore you with why testing is important!
Let us just say that all the advantages of TDD hold true for JIRA plugin development as well. And if you are wondering what exactly TDD is, start at http://en.wikipedia.org/wiki/Test-driven_development.
In this recipe, we will see the various commands for running unit tests and integration tests in JIRA plugins.
Make sure you have the plugin development environment set up and that you have created the skeleton plugin.
You might have noticed that there are two sample test files, one each for unit tests and integration tests, created under the src/test/java/ut/
and src/test/java/it/
folders.
You can build on top of these files to create a suite of test cases and use the SDK commands to run them.
The first step is, of course, to write some tests. I recommend the use of some powerful testing frameworks such as JUnit in collaboration with mocking frameworks such as PowerMock or Mockito. Make sure you have the valid dependencies added on to your pom.xml
. The Atlassian SDK adds JUnit and Mockito by default under the dependencies, but you can change them if you are planning to use other frameworks.
Let us now make the huge assumption that you have written a few tests!
The following is the command to run your unit tests from the command line:
atlas-unit-test
The normal Maven command atlas-mvn clean test
also does the same thing.
If you are running the integration tests, the command to use is as follows:
atlas-integration-test
The Maven command is as follows:
atlas-mvn clean integration-test
Once we are on to the stage of running tests, we will see it failing at times. Then comes the need for debugging. Check out the *.txt
and *.xml
files created under target/ surefire-reports/
, which has all the required information on the various tests that are executed.
Now, if you want to skip the tests at the various stages, use -skip-tests
.
For example, atlas-unit-test --skip-tests
will skip the unit tests.
You can also use the Maven options directly to skip the unit/integrations tests, or both together:
-Dmaven.test.skip=true
: This skips both unit and integration tests-Dmaven.test.unit.skip=true
: This skips unit tests-Dmaven.test.it.skip=true
: This skips integration tests
The atlas-unit-test
command merely runs the related Maven command atlas-mvn clean test
in the backend to execute the various unit tests. It also generates the outputs into the surefire-reports
directory for reference or debugging.
The atlas-integration-test
does a bit more. It runs the integration tests in a virtual JIRA environment. It will start up a new JIRA instance running inside a Tomcat container, set up the instance with some default data, including a temporary license that lasts for three hours, and execute your tests!
How does JIRA differentiate between the unit tests and integration tests? This is where the folder structure plays an important role. Anything under the src/test/java/it/
folder will be treated as integration tests and everything under src/test/java/ut/
folder will be treated as unit tests.
There is more to it.
While atlas-integration-test
makes our life easier by setting up a JIRA instance with some default data in it, we might need some custom data as well to successfully run a few functional tests.
We can do this in a few simple steps:
Export the data from a preconfigured JIRA instance into XML.
Put it under the
src/test/xml/
directory.Provide this path as the value for
jira.xml.data.location
property in thelocaltest.properties
, undersrc/test/resources
.
The XML resource will then be imported to the JIRA before the tests are executed.
Just like the atlas-run
command, you can use the -v
option to test your plugin against a different version of JIRA. As before, make sure you do an atlas-clean
before running the tests if you had tested it against another version before.
You can also use the -c
option to test it against a different version of the Tomcat container.
For example, atlas-clean && atlas-integration-test -v 3.0.1 -c tomcat5x
will test your plugin against JIRA version 3.0.1 using Tomcat container 5.