Testing and debugging

In the world of test-driven development (TDD), writing tests is a part and parcel of the development process. I don't want to bore you with why testing is important! Let us just assume that this holds true for a JIRA plugin development as well. In this recipe, we will see the various commands for running unit tests and integration tests in JIRA plugins.

Note

If you are wondering what exactly TDD is, just go to http://en.wikipedia.org/wiki/Test-driven_development.

Getting ready

Make sure you have the plugin development environment set up and the skeleton plugin created! 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/your_package/ and src/test/ java/it folders. Once you have done this, it is time to write some tests and run those tests to make sure things work as expected!

How to do it...

Without further delay, lets perform the following steps:

1. The first step is to write some tests! We recommend you use 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 onto your pom.xml file.

2. Let us now make a huge assumption that you have written a few tests! 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.

3. If you are running the integration tests, the command to use is:

   atlas-integration-test
   

   Or, the Maven command to use is:

   atlas-mvn clean integration-test
   

4. Once we are onto the stage of running tests, we will see them failing at times. Here comes the need for debugging. Checkout the *.txt and *.xml files created under target/ surefire-reports/, which have all the required information on the various tests that are executed.

5. 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.

6. You can also use the Maven options directly to skip the unit/integrations tests or both together:

   • -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

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 command 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!

But 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 else will be treated as unit tests!

There's more…

It is also possible to use custom data for integration tests and to test it against different JIRA versions.

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. Save it under the src/test/xml/ directory.

3. Provide this path as the value for the jira.xml.data.location property in the localtest.properties file under src/main/resources.

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

Testing against different versions 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. Just like before, make sure you run atlas-clean before executing the tests if you had tested it against another version earlier.

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

• The Setting up the development environment recipe

• The Deploying a JIRA plugin recipe