Testing and debugging

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.

Getting ready

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.

How to do it...

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

How it works...

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's more...

There is more to it.

Using custom data for integration/functional Tests

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:

1. Export the data from a preconfigured JIRA instance into XML.
2. Put it under the src/test/xml/ directory.
3. Provide this path as the value for jira.xml.data.location property in the localtest.properties, under src/test/resources.

The XML resource will then be imported to the JIRA before the tests are executed.

Testing against different version of JIRA/Tomcat

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.

See also

• Setting up the development environment
• Deploying a plugin