Smarter integration testing with TestKit

The source code of the plugin used in this tutorial is available in the Atlassian public source repository. You can get the source code from bitbucket.org/atlassian_tutorial/jira-testkit-example.

Making JIRA ready for tests

Have you ever wondered how to set up complex test scenarios in JIRA? For example add multiple user accounts, groups and permissions, and check if your plugin correctly handles security constraints?

Have you ever been tired preparing different XML dumps for each configuration?

To solve problems like that you can use TestKit, our addition to test infrastructure that helps developers write integration tests with ease.

We've been using TestKit internally in JIRA for some time and as it matured and covered more and more features, we decided that it's time to share this with the ecosystem.

In the following document, we'll help you set up your plugin to use TestKit, and show you how to use it with some examples.

Benefits of using TestKit instead of FuncTestCase

As you probably noticed, FuncTestCase provides a lot of administrative methods through built-in administration attribute. You can still use them. They are all web-based, meaning that when you want to add a user, FuncTestCase goes to the page, fills in the form, submits it, and so on.

Instead TestKit talks with JIRA using REST, exchanging only crucial data to fullfil the task. It's a lot faster. And if you have many tests, you will notice the time difference when switching from FuncTestCase to TestKit.

Also TestKit is actively maintained and you can expect new features coming in.

Setting up the plugin

In your pom.xml search for maven-jira-plugin configuration, you need to extend it adding jira-testkit-plugin:

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>maven-jira-plugin</artifactId>
    <configuration>
        <pluginArtifacts>
            <pluginArtifact>
                <groupId>com.atlassian.jira.tests</groupId>
                <artifactId>jira-testkit-plugin</artifactId>
                <version>${testkit.version}</version>
            </pluginArtifact>
        </pluginArtifacts>
[...]

Also add jira-testkit-client to your project dependencies, remember to use it only with test scope:

1
2
<dependency>
    <groupId>com.atlassian.jira.tests</groupId>
    <artifactId>jira-testkit-client</artifactId>
    <version>${testkit.version}</version>
    <scope>test</scope>
</dependency>

Using TestKit in your tests

You learned in the previous sections about writing integration tests. Here's an example of an integration tests using TestKit:

1
2
package it;
import com.atlassian.jira.functest.framework.FuncTestCase;
import com.atlassian.jira.testkit.client.Backdoor;
import com.atlassian.jira.testkit.client.util.TestKitLocalEnvironmentData;
import com.atlassian.jira.testkit.client.util.TimeBombLicence;

public class MyPluginTest extends FuncTestCase {
    @Override
    protected void setUpTest() {
        super.setUpTest();
        Backdoor testKit = new Backdoor(new TestKitLocalEnvironmentData());
        testKit.restoreBlankInstance(TimeBombLicence.LICENCE_FOR_TESTING);
        testKit.usersAndGroups().addUser("test-user");
        testKit.websudo().disable();
        testKit.subtask().enable();
    }

    public void testIntegration() {
        // Put your test logic here
    }
}

In the above example you can notice how easy is to use TestKit. You can use data loading methods to populate JIRA with different configurations, then you can customize it further. Here we load a blank instance, then add a user, disable websudo and enable sub-tasks.

There's more - as you browse through the API you'll notice methods for managing permission schemes, projects, application properties, mail servers, dashboards, etc.