JIRA Development Cookbook

Chapter 1. Plugin Development Process

In this chapter, we will cover the following topics:

Setting up the development environment
Creating a skeleton plugin
Adding plugin modules
Deploying a JIRA plugin
Making changes and redeploying a plugin
Using FastDev for plugin development
Testing and debugging

Introduction

Atlassian JIRA, as we all know, is primarily an issue tracking and project management system. Since version 7.0, JIRA also comes in different flavors, namely JIRA Core, JIRA Software, and JIRA Service Desk,each packaged to cater to the needs of its various user categories. JIRA Core focuses on business teams, JIRA software on software teams and JIRA service desk on IT and service teams.

What many people do not know, though, is the power of its numerous customization capabilities, using which we can turn it into a different system altogether, much more powerful than these prepackaged flavors! These extra capabilities can take JIRA to the next level, in addition to its core issue tracking and project tracking capabilities for which JIRA, arguably, is the best player in the market.

So what are these customizations? How can we convert the JIRA we know into a product we want? Or maybe just add extra functionalities that are specific to our organization?

The answer to these questions probably can be summarized in a single word,add-ons, also referred to as plugins. JIRA has given the power to its users to write add-ons and customize the functionality in a way they find suitable.

But is that the only way? Definitely not! JIRA itself provides a lot of customization options through its user interface, and in more demanding cases, using property files such as jira-config.properties. In some cases, you will also find yourself modifying some of the JIRA core files to tweak functionality or to work around a problem. We will see more of that in the chapters to come, but the best entry point to JIRA customizations is add-ons. And that is where we start our cookbook, before we move on to the in-depth details.

What is a JIRA add-on?

So, what is a JIRA add-on? JIRA itself is a web application written in Java. But that doesn't mean you need to know Java to write an add-on, though in most cases you will need to. You might also end up writing a simple descriptor file to add a few links here and there. If that makes the non-Java developer in you happy, watch out for the different plugin modules JIRA supports.

There are two frameworks for writing JIRA add-ons: Atlassian Connect and the Plugins2 framework.

Atlassian Connect add-ons are essentially web applications that operate remotely over HTTP. But they run only on Atlassian Cloud and are well documented at https://developer.atlassian.com/static/connect/docs/latest/guides/introduction.html, hence they are outside the scope of this book.

A Plugins2 plugin is a JAR file that has a mandatory plugin descriptor and some optional Java classes and velocity templates. The velocity templates are used to render the HTML pages associated with your plugin, but in some cases, you might also want to introduce JSPs to make use of some pre-existing templates in JIRA. JSPs, as opposed to velocity templates, cannot be embedded in the plugin, but instead they should be dropped into the appropriate folders in the JIRA web application. Hence using velocity templates is recommended over JSPs. You can find more details on writing velocity templates at http://velocity.apache.org/engine/1.7/user-guide.html#velocity-template-language-vtl-an-introduction.

The plugin descriptor, the only mandatory part of a plugin, is an XML file which must be named atlassian-plugin.xml. This file is located at the root of the plugin. The atlassian-plugin.xml file defines the various modules in a plugin. The different types of available plugin modules include reports, custom field types, and so on, and these are discussed in detail in the next chapter.

The plugin development process

The process of developing a JIRA plugin can be of varying complexity, depending on the functionality we are trying to achieve. The plugin development process essentially is a four-step process:

Developing the plugin.
Deploying it into local JIRA.
Testing the plugin functionality.
Making changes and redeploying the plugin if required.

Each of these is explained in detail through the various recipes in this book.

JIRA, on start-up, identifies all the plugins that are deployed in the current installation. You can deploy multiple plugins, but there are some things you need to keep an eye on.

The atlassian-plugin.xml file has a plugin key, which should be unique across all the plugins. It is much similar to a Java package. Each module in the plugin also has a key that is unique within the plugin. The plugin key combined with the module key, separated by a colon, forms the complete key of a plugin module.

The following is a sample atlassian-plugin.xml without any plugin modules in it:

<!-- the unique plugin key --> 
<atlassian-plugin key="com.jtricks.demo" name="Demo Plugin" 
  plugins-version="2"> 
    <!-- Plugin Info --> 
    <plugin-info> 
        <description>This is a Demo Description</description> 
        <version>1.0</version> 
        <!-- optional  vendor details --> 
        <vendor name="J-Tricks" url="http://www.j-tricks.com"/> 
    </plugin-info> 
    . . . 1 or more plugin modules . . . 
</atlassian-plugin>

The plugin, as you can see, has details such as description, version, vendor-details, and so on, in addition to the key and name. When a plugin is loaded, all the unique modules in it are also loaded.

Suppose you have a report module in your plugin; it will look as follows:

<report key="demo-report" name="My Demo Report" ....> 
... 
</report>

The plugin key in the preceding case will be com.jtricks.demo and the module key will be com.jtricks.demo:demo-report.

Hang on; before you start writing your little plugin for a much wanted feature, have a look at the Atlassian Marketplace to see if someone else has already done the dirty work for you!

Atlassian Marketplace

Atlassian Marketplace is a one-stop shop where you can find the entire list of commercial and open source plugins people around the world have written. See https://marketplace.atlassian.com/plugins/app/jira for more details.

Troubleshooting

A common scenario that people encounter while deploying the plugin is when the plugin fails to load even though everything looks fine. Make sure your plugin's key is unique and is not duplicated in one of yours or another third-party's plugin!

The same applies to individual plugin modules.

Setting up the development environment

Now that we know what a plugin is, let's aim at writing one! The first step in writing a JIRA plugin is to set up your environment, if you haven't done that already. In this recipe, we will see how to set up a local environment.

To make plugin development easier, Atlassian provides the Atlassian plugin software development kit (SDK). It comes along with Maven and a preconfigured settings.xml to make things easier.

The Atlassian Plugin SDK can be used to develop plugins for other Atlassian products, including Confluence, Crowd, and so on, but we are concentrating on JIRA.

Getting ready

The following are the prerequisites for running the Atlassian Plugin SDK:

Note

At the time of writing this recipe, the latest version of the Atlassian Plugin SDK is 6.1.0.

The default port for the SDK, 2990,should be available. This is important because different ports are reserved for different Atlassian products.
Install JDK. Java version 1.8.X is required for Atlassian Plugin SDK 6.1.0. Please verify the compatible Java version for your SDK version.
Make sure the JAVA_HOME is set properly and the command java -version outputs the correct Java version details.

How to do it...

Once we have Java installed and the port ready, we can download the latest version of Atlassian plugin SDK from https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project.
Unzip the version into a directory of your choice or follow the instructions on the page, depending up on the operating system. Let's call this directory SDK_HOME going forward.
Add the SDK's bin directory into the environment PATH variable. If you are using the installer, this step is automatically done.
Create a new environment variable, M2_HOME, pointing to the apache-maven directory in your SDK Home. SDK version 4.x+ handles this step automatically.
Install the IDE of your choice. Atlassian recommends Eclipse, IntelliJ IDEA, or NetBeans, as they all support Maven.
Ready, set, go...

There's more...

With the preceding steps executed properly, we have a development environment for JIRA plugins. You can verify the installation of the SDK by running the following command:

atlas-version

This command displays the version and runtime information of the installed SDK.

The next step is to create a skeleton plugin, import it into your IDE, and start writing some code! Creating the skeleton plugin, deploying it, and so on, is explained in detail in the following recipes.

If you face issues while downloading the dependencies using Maven, read on.

Proxy settings for Maven

If you are behind a firewall, make sure you configure proxy in the Maven settings.xml file. Proxy can be configured as follows:

<settings> 
    ... 
    <proxies> 
        <proxy> 
            <active>true</active> 
            <protocol>http</protocol> 
            <host>proxy.demo.com</host> 
            <port>8080</port> 
            <username>demouser</username>
            <password>demopassword</password>
            <nonProxyHosts>localhost|*.demosite.com</nonProxyHosts> 
        </proxy> 
    </proxies> 
    ... 
</settings>

Find more about that and other aspects of Maven at http://maven.apache.org/index.html.

Using local Maven

If you are a developer, in many cases you will have Maven already installed in your local machine. In that case, point the M2_HOME directory to your local Maven and update the respective settings.xml with the repository details in the default settings.xml that ships with the Atlassian Plugin SDK.

Or you can simply add the following to the existing settings.xml:

<pluginRepository> 
    <id>atlassian-plugin-sdk</id> 
    <url>file://${env.ATLAS_HOME}/repository</url> 
    <releases> 
        <enabled>true</enabled> 
        <checksumPolicy>warn</checksumPolicy> 
    </releases> 
    <snapshots> 
        <enabled>false</enabled> 
    </snapshots> 
</pluginRepository>

Configuring IDEs to use the SDK

If you are using IntelliJ IDEA, it is an easy job because IDEA integrates Maven out of the box. Just load the project by selecting the pom.xml! See https://developer.atlassian.com/docs/developer-tools/working-in-an-ide/configure-idea-to-use-the-sdk for details.

If you are using Eclipse, make sure you have M2Eclipse installed. This is because Eclipse integrates Maven through the Sonatype M2Eclipse plugin. You can find more details on configuring this at https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project/set-up-the-eclipse-ide-for-linux or https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project/set-up-the-eclipse-ide-for-windows, depending on the OS.

For NetBeans, see https://developer.atlassian.com/docs/developer-tools/working-in-an-ide/configure-netbeans-to-use-the-sdk.

Troubleshooting

If you see Maven download errors such as Could not resolve artifact, make sure you verify the following:

Entry in Maven settings.xml is correct, that is, it points to the correct repositories.
Proxy configuration is done if required.
Antivirus in the local machine is disabled and/or firewall restrictions removed if none of the above works! Seriously, it makes a difference.

Creating a skeleton plugin

In this recipe we will look at creating a skeleton plugin. We will use the Atlassian Plugin SDK to create the skeleton.

Getting ready

Make sure you have the Atlassian Plugin SDK installed.

How to do it...

Open a command window and go to the folder where you want to create the plugin.
Type atlas-create-jira-plugin and press Enter.
Enter the groupID when prompted. groupID would normally be coming from your organization name and mostly resembles the Java package. Of course, you can enter a different package name as we move forward if you want to keep it separate. groupID will be used to identify your plugin along with artifactID.
For example: com.jtricks.demo
Enter the artifactId. The identifier for this artifact. Do not use spaces here.
For example: demoplugin
The default version is 1.0-SNAPSHOT. Enter a new version if you want to change it or press Enter to keep the default.
For example: 1.0
Press Enter if the package value is same as the groupID. If not, enter the new value here and press Enter.
For example: com.jtricks.mypackage
Confirm the selection when prompted. If you want to change any of the entered values, type N and press Enter.
Wait for the BUILD SUCCESSFUL message.

How it works...

A skeleton plugin is nothing but a set of directories and subdirectories along with a pom.xml (Maven project object model) file and some sample Java and XML files in the appropriate folders.

Here is a snapshot of how the project will look in Eclipse. It also shows the design view of the default atlassian-plugin.xml:

As you can see, there is a pom.xml at the root level and a src folder. A sample LICENSE file and a README file are also created for you at the root level.

Under the src folder, you will find two folders, main and test, with an identical folder structure. All your main Java code goes under the main folder. Any JUnit tests you write will go into the same location under the test folder. There is an additional folder, it, under the test folder where all the integration tests will go.

You will find the plugin descriptor, that is, atlassian-plugin.xml, under src/main/resources with sample values already populated in it. The values in the preceding screenshot are populated from the pom.xml. In our case, the plugin key will be populated as com.jtricks.demo:demoplugin when the plugin is built.

You will also notice that the skeleton plugin has some sample resources, which includes a CSS file, a JavaScript file, a plugin icon image, and a plugin logo image. The CSS and JS files are registered as resources under a web-resource plugin module. The images folder is also registered as a resource under the same module. The skeleton plugin also has a demoplugin.properties file, which is registered as an i18n resource. These files are placeholders and we can use them to add the respective functionality to the plugin.

So, that is our plugin skeleton. All that is pending is some useful Java code and proper module types in the atlassian-plugin.xml!

Tip

Remember, the first Maven run is going to take some time as it downloads all the dependencies in to your local repository. A coffee break might not be enough! If you have a choice, plan your meals.

There's more...

Sometimes, for the geeks, it is much easier to run a single command to create a project without bothering about the step-by-step creation. In this section, we will quickly see how to do it. We will also have a look at how to create an Eclipse project if you opt out of installing m2eclipse.

One step to your skeleton plugin

You can ignore the interactive mode by passing parameters such as groupID, artifactId, and so on, as arguments to the atlas-create-jira-plugin command:

atlas-create-jira-plugin -g my_groupID -a my_artifactId -v my_version -p my_package   --non-interactive

For the example values we saw previously, the single line command will be as follows:

atlas-create-jira-plugin -g com.jtricks.demo  -a demoplugin -v 1.0 -p com.jtricks.mypackage --non-interactive

You can pick and choose the parameters and provide the rest in an interactive mode as well!

Creating an Eclipse project

If you are not using m2eclipse, just run the following command from the folder where you have the pom.xml file:

atlas-mvn eclipse:eclipse

This will generate the plugin project for Eclipse, and you can then import this project into the IDE.

Execute atlas-mvn eclipse:clean eclipse:eclipse if you want to clean the old project and create again.

With IDEA or m2eclipse, just opening a file will do. That is, you can just import the project using the option File | Import | Existing Maven Projects, and select the relevant project.

Adding plugin modules

The plugin architecture is built around plugin modules, and JIRA exposes a number of plugin module types, each with a specific purpose. A plugin can have any number of plugin modules, either of the same type or of different types, as long as they all have a unique key. Throughout this book, we will see how we can use different plugin module types to solve different requirements.

In this recipe we will look at adding plugin modules to an existing plugin project.

Getting ready

Make sure the plugin project already exists or create a new skeleton project as explained, in the previous recipe.

How to do it...

Open a command window and go to the plugin project folder, where pom.xml resides.
Type atlas-create-jira-plugin-module and press Enter. This will show all the available plugin modules as a numbered list, as shown here:
Select the number against the module that you are planning to add. For example, type 25 and press Enter if you want to add a simple web-item module to the plugin.
Follow the instructions to provide the details required for the selected module. Some of the options may have default values. Some modules might also have an advanced setup. Type Y and press Enter when prompted, if you want to go to Advanced Setup. If not, type N and press Enter.
Once the module is completed, type Y or N and press Enter when prompted to add another plugin module, depending on whether you want to add another module or not.
Repeat the steps for every module you want to add.
Wait for the BUILD SUCCESSFUL message when no more modules are to be added.

How it works...

Similar to the skeleton plugin creation, a set of directories and subdirectories are created during this process, along with a number of Java files or velocity templates required for the selected plugin module.

It also adds the plugin module definition in the atlassian-plugin.xml based on our inputs in step 4. A sample plugin descriptor, after adding the web-item module, looks like this:

<?xml version="1.0" encoding="UTF-8"?> 
<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2"> 
    <plugin-info> 
        <description>${project.description}</description> 
        <version>${project.version}</version> 
        <vendor name="${project.organization.name}"
          url="${project.organization.url}"/> 
        <param name="plugin-icon">images/pluginIcon.png</param> 
        <param name="plugin-logo">images/pluginLogo.png</param> 
    </plugin-info> 
    <!-- add our i18n resource --> 
    <resource type="i18n" name="i18n" location="demoplugin"/> 
    <!-- add our web resources --> 
    <web-resource key="demoplugin-resources" 
     name="demoplugin Web Resources"> 
        <dependency>com.atlassian.auiplugin:ajs</dependency> 
        <resource type="download" name="demoplugin.css" location="/css
          /demoplugin.css"/> 
        <resource type="download" name="demoplugin.js" location="/js
          /demoplugin.js"/> 
        <resource type="download" name="images/" location="/images"/> 
        <context>demoplugin</context> 
    </web-resource> 
    <web-item name="My Web Item" i18n-name-key="my-web-item.name" 
      key="my-web-item" section="system.user.options/personal" 
      weight="1000"> 
        <description key="my-web-item.description">The My Web Item Plugin
        </description> 
        <label key="my-web-item.label"></label> 
        <link linkId="my-web-item-link">http://www.j-tricks.com</link> 
    </web-item> 
</atlassian-plugin>

As you can see, a web-item module is added. We will see more about the web-item module, and other modules mentioned here, in the upcoming chapters.

You can also see a resource module and a web-resource module, which are added automatically the first time a plugin module is created.

The resource module defines the i18n resource file for the plugin, and more key-value pairs will be added in to this file when more modules are added. The file has the name {plugin-artifact-name}.properties and is created under the src/main/resources{plugin-group-folder} folder. In our example, the demo.properties file is created under the src/main/resources/com/jtricks/demo folder.

A sample property file is as follows:

#put any key/value pairs here 
my.plugin.name=MyPlugin 
my-web-item.label=My Web Item 
my-web-item.name=My Web Item 
my-web-item.description=The My Web Item Plugin

The web-resource module defines the plugin web resources, which includes a JS file, a CSS file, and an images folder that has the default plugin icon and logo images. We will learn more about these modules later in this book.

Deploying a JIRA plugin

In this recipe, we will see how to deploy a plugin into JIRA. We will see both the automated deployment using the Atlassian Plugin SDK and manual deployment.

Getting ready

Make sure you have the development environment set up as we discussed earlier. Also, the skeleton plugin should now have the plugin logic implemented in it.

How to do it...

Installing a JIRA plugin using the Atlassian Plugin SDK is a cakewalk. Here is how it is done:

Open a command window and go to your plugin's root folder, that is, the folder where your pom.xml resides.
Type atlas-run and press Enter. It is possible to pass more options as arguments to this command for which the details can be found at https://developer.atlassian.com/docs/developer-tools/working-with-the-sdk/command-reference/atlas-run.
You will see a lot of things happening as Maven downloads all the dependent libraries in to your local repo. As usual, it is going to take lot of time when you run it for the first time.
If you are on Windows, and if you see a security alert popping up, click Unblock to allow incoming network connections.
When the installation is completed, you will see messages similar to the following:
Open http://localhost:2990/jira in your browser.
Log in using the username admin and password admin.
Test your plugin! You can always go to Administration | Add-ons | Manage add-ons menu to confirm that the plugin is deployed properly.

If you already have a local JIRA installed or if you want to manually install your plugin due to some reason, all you need to do is to package the plugin JAR and install it via UPM (Universal Plugin Manager) as described at https://confluence.atlassian.com/display/UPM/Installing+add-ons#Installingadd-ons-Installingbyfileupload. Or, you can copy it across to JIRA_Home/plugins/installed-plugins directory and restart JIRA.

You can package the plugin using the following command:

atlas-mvn clean package

Use atlas-mvn clean install if you also want to install the package plugin into your local repo.

How it works...

There is only one single command that does the whole thing: atlas-run. When you execute this command, it does the following:

Builds your plugin .jar file. It also builds the .obr file, which is the OSGi Bundle Repository file; that is essentially a .jar file containing our plugin and all dependent plugins, if we have any. More details on .obr files can be read at https://developer.atlassian.com/docs/faq/advanced-plugin-development-faq/bundling-extra-dependencies-in-an-obr.
Downloads the latest/specified version of JIRA to your local machine if it is the first time you are running the command.
Creates a virtual JIRA installation under your plugin /target folder.
Copies the .jar file in to the /target/jira/home/plugins/installed-plugins directory.
Starts JIRA in the Tomcat container.

Now, if you look at your target folder, you will see a lot of new folders that were created for the virtual JIRA installation! The main two folders are the container folder that has the Tomcat container set up and the jira folder that has the JIRA WAR along with the JIRA home setup.

You will find the database (HSQLDB), indexes, backups, and attachments under /target/jira/home, and you will see your jira-webapp at /target/container/tomcat8x/cargo-jira-home/webapps/jira.

If you have any JSPs that need to be put under the webapp, you will have to copy it to the appropriate folder under the aforementioned path.

There's more...

It is also possible to use a specific version of JIRA or to reuse the data that we have used for testing.

Using a specific version of JIRA

As mentioned earlier, atlas-run deploys the latest version of JIRA. But what if you want to deploy the plugin into an earlier version of JIRA and test it?

There are two ways to do it:

Mention the JIRA version as an argument to atlas-run; make sure you run atlas-clean if you already have the latest version deployed:
a. Run atlas-clean (if required)
b. Run atlas-run -v 5.0 or atlas-run -version 5.0 if you are developing for JIRA version 5.0. Replace the version number with a version of your choice.
Permanently change the JIRA version in your plugin pom.xml:
a. Go to your pom.xml
b. Modify the jira.version property value to the desired version.
c. Modify the jira.data.version to a matching version.
This is how it will look for JIRA 5.0:
```
      <properties> 
        <jira.version>5.0</jira.version> 
        <jira.data.version>5.0</jira.data.version> 
      </properties> 
```

Reusing the data in each run

Suppose you added some data on to virtual JIRA; how do you retain it when you clean start-up JIRA next time?

This is where a new SDK command comes to our rescue.

After atlas-run is finished, that is, after you pressed Ctrl + C, execute the following command:

atlas-create-home-zip

This will generate a file named generated-test-resources.zip under the target/jira folder. Copy this file to the /src/test/resources folder or any other known location. Now modify the pom.xml to add the following entry under configurations in the maven-jira-plugin:

<productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>

Modify the path accordingly. This will reuse the data the next time you run atlas-run after an atlas-clean.

Troubleshooting

Missing JAR file exception? Make sure the local-repository attribute in the settings.xml points to the embedded Maven repository that comes with the SDK. If the problem still persists, manually download the missing .jar files and use atlas-mvn install to install them in to the local repository.

Watch out for the proxy settings or antivirus settings that can potentially block the download in some cases!

BeanCreationException? Make sure your plugin is version 2. Check atlassian-plugin.xml to see if the plugins-version="2" entry is there or not. If not, add the entry, as shown here:

<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}"
 plugins-version="2">

Run atlas-clean followed by atlas-run.

Using FastDev for plugin development

We have seen how to use atlas-cli to reload a plugin without having to restart atlas-run. It is a pretty good way to save time, but Atlassian have walked the extra mile to develop a plugin named FastDev, which can be used to reload plugin changes, during development, to all Atlassian applications, including JIRA. And that from the browser itself!

Getting ready

Create a plugin and use atlas-run to run the plugin as in the aforementioned recipe. Let us assume we are doing it on the plugin we created in the previous recipe, the one with the sample web-item.

Make sure FastDev is enabled in the maven-jira-plugin configuration in the pom.xml, as shown here:

<plugin> 
    <groupId>com.atlassian.maven.plugins</groupId> 
    <artifactId>maven-jira-plugin</artifactId> 
    <version>${amps.version}</version> 
    <extensions>true</extensions> 
    <configuration> 
        <productVersion>${jira.version}</productVersion> 
        <productDataVersion>${jira.version}</productDataVersion> 
        <enableQuickReload>true</enableQuickReload> 
        <enableFastdev>true</enableFastdev> 
    </configuration> 
</plugin>

Note

Enabling FastDev is an important step, as it might be disabled by default, depending on the version of Atlassian SDK.

If we run that sample web-item plugin, using atlas-run, we can access JIRA at port 2990 as mentioned before and the web-item will look as highlighted here:

As you can see, the My Web Item link appears along with Profile link, under the Personal section. What if you wanted the link at the jira-help section, along with Online Help, About JIRA, and so on?

How to do it...

The following are the simple steps to make the change to the plugin and reload it using FastDev:

Access the FastDev servlet on the browser in the following path: http://localhost:2990/jira/plugins/servlet/fastdev. You will find the servlet as shown here:
Make the necessary changes to your plugin. In this example, the change is pretty small. All we do is modify the atlassian-plugin.xml to change the section in the web-item module from section="system.user.options/personal" to section="system.user.options/jira-help".
Click on the Scan and Reload button on the servlet (see the preceding image). On clicking the button, FastDev will reload the plugin. You can track the progress and see the logs on the browser itself, as shown here:
Once the plugin is successfully reloaded, you will see the following screen with a success message:
Reload the JIRA page to see if the change is effective. In our example, the new menu item moved under the Help section, as shown here:

Using FastDev is very effective while building a plugin from scratch and testing it, as the pieces gradually fall in to the right places.

How it works...

When the Scan and Reload button is pressed, FastDev looks for files that have changed since the last time plugin was installed. If it detects any changes, it starts a Maven process that re-installs the plugin.

More information on FastDev can be found at https://developer.atlassian.com/docs/developer-tools/automatic-plugin-reinstallation-with-fastdev.

There's more...

There is more to FastDev than the default configurations. They can be set in your plugin's pom.xml file by adding the required property to the systemPropertyVariables node, which in turn goes under the plugin configuration node.

You will find the details in the preceding Atlassian documentation, but the most useful ones are mentioned in the following section.

Adding ignored files

While looking for changes, it ignores certain files like .js or .css files that don't need a re-install of the plugin. Following is the full list of files/directories that are ignored:

Type	Property name	Default(s)
Directory	`fastdev.no.reload.directories`	`.svn`
Extension	`fastdev.no.reload.extensions`	`.js`, `.vm`, `.vmd`, `.fm`, `.ftl`, `.html`, `.png`, `.jpeg`, `.gif`, `.css`
File	`fastdev.no.reload.files`

If you want to ignore additional files or directories, you can add them using the preceding properties, as shown here:

<systemPropertyVariables> 
    ... 
    <fastdev.no.reload.directories>images</fastdev.no.reload.directories> 
    <fastdev.no.reload.extensions>classpath</fastdev.no.reload.extensions>
    <fastdev.no.reload.files>${basedir}/src/main/resources/LCIENSE.txt</fastdev.no.reload.files> 
</systemPropertyVariables>

Changing admin credentials

FastDev uses the default admin/admin credential to reinstall the plugin. But if the username or password is different, use the fastdev.install.username and fastdev.install.password property, as shown here:

<systemPropertyVariables> 
    ... 
    <fastdev.install.username>myusername</fastdev.install.username> 
    <fastdev.install.password>mypassword</fastdev.install.password> 
</systemPropertyVariables>

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:

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