Generate and Examine Skeleton Tests
When you generate a new plugin with an
atlas-create-application-plugin command, the generated plugin skeleton includes skeleton tests. This page walks you through the process of generating the plugin skeleton and its tests. It also introduces you to the project components the tests rely on.
Backgrounder: Supported Plugin Test Types
You can and should test plugins using the same types of tests as you would for other software. In general, the different types of tests fall into these categories:
|unit||Test on a distinct unique of work within the plugin such as a single method or function.|
Tests the interactions between the plugin and the plugin's target environment. In the case of an Atlassian plugin, the target environment is the host application. Integration tests can also include or rely on other external, services.
Atlassian supports traditional integration tests and wired integration tests. Wired integration tests are bundled as a plugin and run directly in the host application. You'll learn more about creating wired integration tests later in this tutorial.
|functional||Tests the functionality of the application's features and functions.|
|stress||Tests how the application performs under a large number of requests within a given period.|
|acceptance||Tests how well the application meets a customer's needs.|
Unit and integration tests test your plugin's internal structures or functions. Atlassian provides you with a plugin test skeleton and a tools for unit and integration testing. Often, you can combine functional tests with your integration tests. In some cases, Atlassian host applications supply functional test libraries that you can leverage in developing your own tests.
The stress and acceptance tests require you to write specifications or build systems specific to your plugin and its requirements. Atlassian does not provide tools, processes, or infrastructures for these test types but we do encourage you to do them on your own.
Step 1. Create a Plugin Skeleton
In this step, you create a simple plugin skeleton and import it into the Eclipse IDE. You can create a skeleton for any of the Atlassian host applications. This tutorial uses JIRA.
If you aren't interested in using Eclipse and prefer another IDE, you are perfectly free to use another. However, the tutorial assumes you are using Eclipse.
Do the following to generate the plugin skeleton and its tests resources:
- Open a terminal and navigate to your Eclipse workspace directory.
Enter the following command to create a JIRA plugin skeleton:
When prompted, enter the following information to identify your plugin:
Create a plugin for?
Enter a JIRA version
- Confirm your entries when prompted.
- Change to the
testTutorialdirectory created by the previous step.
Run the command:
You should repeat this command after you add a dependency to your
pom.xmlfile. It ensures that Eclipse populates your project dependencies correctly.
- Start Eclipse.
- Select File->Import.
Eclipse launches the Import wizard.
- Filter for Existing Projects into Workspace (or expand the General folder tree).
- Press Next and enter the root directory of your workspace.
Your Atlassian plugin folder should appear under Projects.
- Select your plugin and click Finish.
Eclipse imports your project.
Step 2. Review the Generated Test Structure
atlas-create-jira-plugin command creates test directories and skeleton test files. Most
atlas-create-application-plugin commands create the following directories:
||Place integration tests here. You must package all your integration tests in a package that begins with the
||Place unit test here. You must package all your unit tests in a package that begins with the
||Place resource test files here.|
atlas-create-application-plugin commands generate these directories. If you use a command that does not generate these directories, create them yourself.
Along with the test directory structure, most
atlas-create-application-plugin commands generate skeleton test files. For this tutorial, the generation step created these additional files:
The wired integration tests rely on the descriptor file (
atlassian_plugin.xml). You'll learn more about this later in the tutorial.
Take some time and open the generated test files. The Java files contain simple classes that you can expand on as you work. If you use the
atlas-create-application-plugin-module commands to add plugin modules, you may find the commands generate additional files in these folders.
Step 3. Review the pom.xml Test Dependencies
pom.xml file contains three elements related to test dependencies.
The JUnit Dependency
In the previous step, you may have noticed that all of your plugin test files import a
org.junit.Test class. JUnit is a widely-used testing framework supported for testing Atlassian plugins. When you generate a plugin, the
pom.xml file includes a dependency on JUnit 4.10:
The scope of this dependency limits the availability of JUnit only to the project test compilation and execution phases. If you are packaging a plugin, you need not remove your tests files as the test dependencies do not load at runtime in a production system.
Look for the wired test runner dependencies further down the page. These look like the following:
Your integration tests can make use of these dependencies to write in-product, wired integration tests.
Depending on which host application you are using, Jira, Confluence, etc., your
pom.xml file may contain dependencies in addition to JUnit. The dependencies can be on third-party test frameworks, like Mockito, or to Atlassian test suites. The JIRA generated
pom.xml includes two additional dependencies:
jira-tests artifact contains the JIRA Unit tests. The
jira-func-tests, like the name sounds, contains the JIRA functional tests. When you write your tests, you can access these artifacts from your own unit, integration, and functional tests. The application-specific sections of this site contain information on these resources. The last page of this tutorial explains where those are.
So far, you've learned about the generated structure created for you when you run an
atlas-create-application-plugin command. This structure includes test directories, files, and dependencies. This is code that Atlassian generates for all plugin developers automatically. In the next section, you write a simple unit test, execute the test in your plugin, and review the results of the test.