Last updated Dec 8, 2017

Run Wired Tests with the Plugin Test Console

In previous pages in this tutorial, you learned how to use JUnit to construct unit tests, how to configure and run your traditional integration tests, and how to use the atlas- commands to run tests. On this page, you learn how to speed up and simplify plugin development using the Atlassian Wired Test Framework and the Plugin Test Console.

Overview of the Atlassian Wired Test Framework

While the atlas-unit-test and atlas-integration-test commands allow you to run tests from the command line, neither allowed for a fast development process. The Atlassian Wired Test Framework lets you test your plugin in the context of the host Atlassian product. (In contrast, the traditional plugin testing framework required the use of a host-mocking framework, such as Mockito.)

An additional advantage of the framework is that it facilitates faster test development. Instead of recompiling your plugin and restarting the host application every time you make a change to a test, you can use the test console to re-run the test, without having to recompile and restart the host.

Running as a plugin in product has several advantages:

  • Test code is deployed as a plugin bundle in the same OSGI-fied Tomcat container as the host application.
  • Your code can use all the JUnit functionality and any additional functionality you would be able to do in non-test plugin.
  • Dependencies in your test code are "wired" by Spring inside the container.
  • Test code runs in the product container and reports back to the locally running JUnit.
  • Test results display in the Plugin Test Console in addition to Surefire reports.

Finally, since your tests are running in the product, you can test your plugins in a more realistic context.

JUnit Enhancements for Wired Tests

The Atlassian Wired Test Framework includes some enhancements that causes difference in how you use JUnit annotation inside of Atlassian Wired Tests. The following table lists these differences.

  • Standard JUnit Test: Requires a single zero-argument, public constructor.

  • Atlassian Wired Test: Can use constructor for dependency injection.

  • Standard JUnit Test: Tests are stateless and every method is run on its own instance of the test class.

  • Atlassian Wired Test: Tests are stateful. All methods run on the same test class instance. You must be careful to clean up any data at the end of your methods!

  • Standard JUnit Test: @BeforeClass and @AfterClass must annotate a public static void method.

  • Atlassian Wired Test: @BeforeClass and @AfterClass must not annotate a static method. These methods should annotate a public void method.

The @Before and @After annotations remain the same both in standard and wired tests; they annotate public void methods.

Step 1. Ensure you have the correct dependencies

If you have followed along through this tutorial, you should already have the correct dependencies in your pom.xml.  If you are upgrading a pom.xml file you used from a pre-existing project, you may need to add dependencies to it.  Regardless, it is good to check your dependencies. 

  1. Navigate to the top of your project's PLUGIN_HOME.

  2. Open the pom.xml file.

  3. Make sure you have the following wired test dependencies:

    1
2
    <dependencies>
....

  <!-- WIRED TEST RUNNER DEPENDENCIES -->
  <dependency>
    <groupId>com.atlassian.plugins</groupId>
    <artifactId>atlassian-plugins-osgi-testrunner</artifactId>
    <version>${plugin.testrunner.version}</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>javax.ws.rs</groupId>
    <artifactId>jsr311-api</artifactId>
     <version>1.1.1</version>
    <scope>provided</scope>
    </dependency>
    <dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.2.2-atlassian-1</version>
  </dependency>
</dependencies>

    Specifying the jsr311-api and gson dependencies overrides the transitive versions Maven would have fetched.

  4. Set your JUnit dependency version to 4.10 or higher:

    1
2
    <dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.10</version>
  <scope>test</scope>
</dependency>

  5. Include the following values in your <properties>:

    1
2
    <amps.version>8.2.3</amps.version>
<plugin.testrunner.version>2.0.2</plugin.testrunner.version>

  6. Save any changes you made and close the file.

Step 2. Examine the atlassian-plugin.xml file for your tests

Remember, your wired tests get bundled together as a plugin.  Like any other Atlassian plugin, your test suite needs a plugin descriptor file (atlassian-plugin.xml).  The descriptor lists any components or modules needed by your integration tests.  At runtime, Spring examines this plugin file and wires in the modules needed by your tests.

The Plugins Test Console always runs and displays results from wired tests. It can also run and display the results of unit tests and traditional integration tests. It can do this only if your descriptor file also includes any resources need by these tests as well.  For example, unit tests typically have dependencies on the base plugin.  So, your descriptor should make sure to include any base plugin dependencies.

If you are following along with this tutorial, the atlassian-plugin.xml descriptor file was created for you in the PLUGIN_HOME/src/test/resources directory. To convert a pre-4.1 SDK existing project over to using the Wired Test Framework, you'll need to add this file yourself (or better yet, use Spring Java Configuration). Take a moment to familiarize yourself with the test descriptor file and how it differs from your standard descriptor.

  1. Navigate to your project's PLUGIN_HOME/src/test/resources directory.

  2. Open the atlassian-plugin.xml file.
    It should look similar to the following:

    1
2
    <atlassian-plugin key="${project.groupId}.${project.artifactId}-tests" 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}" />
  </plugin-info>
  <!-- from our base plugin -->
  <component-import key="myComponent" interface="com.example.plugins.tutorial.jira.testTutorial.MyPluginComponent"/>
  <!-- from the product container -->
  <component-import key="applicationProperties" interface="com.atlassian.sal.api.ApplicationProperties" />

</atlassian-plugin>

  3. Note that your test project key is different from your project's key.
    The test key has a  -tests identifier at the end of the plugin key as follows:

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

    This identifier distinguishes your test bundle from your project bundle in the OSGI container. 

  4. Locate the component-import from the base plugin.
    You'll recall that your MyComponentWiredTest.java file tests a method on your base plugin. This import tells Spring that your test bundle needs an interface from another bundle, the plugin. 

  5. Locate the component-import from the product  container.
    Your wired test relies on the Shared Access Layer (SAL).  This is a component common to all Atlassian applications. So, here you are just telling Spring to wire in SAL as well. 

  6. Close the file.

You may want specific modules in your test plugin that you don't have in your main plugin. If that is the case, you would add them to this descriptor rather than your main descriptor.  Any dependencies you need to declare to support the component-imports would go into your pom.xml file.

Step 3. Launch the application

Now, you are ready to launch the host application and run the tests.

  1. Open a command or terminal window.

  2. Change directory to the PLUGIN_HOME directory.

  3. Start the application with the atlas-debug command.

    1
2
    atlas-debug

Step 4. Run the tests

There are several different ways to run wired tests:

  • From the Plugin Test Console
  • From an IDE
  • Via REST
  • Via AMPS

1. From the Plugin Test Console

When the application starts, it displays the URL for the host application:

1
2
``` bash
...
[INFO] jira started successfully in 106s at http://localhost:2990/jira
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit
```

4. Copy and paste the URL into your browser's address field. 5. The browser displays the host application, in the case of this tutorial, JIRA. 

  1. Enter admin for both the User and the Password.
  2. Display the Developer Toolbar by clicking on the arrow in the lower left corner of your browser.
  3. Click Toolbox > Plugin Test Console.
    The test console appears. The console lists the type of tests it found in your project.
  4. Press Rerun all 3 test classes to run your tests and display their results:

or

  1. Copy and paste the URL into your browser's address field along with /plugins/servlet/it-test-console at the end of the URL (e.g. http://localhost:2990/jira/plugins/servlet/it-test-console).
  2. The browser displays the host application, in the case of this tutorial, JIRA. 
  3. Enter admin for both the User and the Password.
  4. The test console appears. The console lists the type of tests it found in your project.
  5. Press Rerun all 3 test classes to run your tests and display their results

2. From an IDE

  1. Run the test via the method provided within your IDE (it will fail, this is OK).
  2. Add this VM option to the relevant configuration: -Dbaseurl=http://localhost:2990/jira (adjust URL if running different products).
  3. Re-run the test and it should now pass. If you make changes to the plugin or test code, you will need to redeploy the modified plugins (see Step 4 on making changes to running plugin test suites).

3. Via REST

Send a GET request to (for example): http://localhost:2990/jira/rest/atlassiantestrunner/1.0/runtest/it.com.example.plugins.tutorial.testTutorial.MyComponentWiredTest

4. Via AMPS

AMPS provides a command for running wired tests, for example:

mvn amps:remote-test -Dserver=localhost -Dhttp.port=2990 -Dcontext.path=jira

Note that you will need to be running AMPS 8.1.1 or later due to a bug in earlier versions (if you're using the SDK, you can override the AMPS version with -u 8.2.3 or similar on the SDK command line).

Step 4. Make a Change to Your Running Test Suite

Like any other Atlassian plugin, you can use the QuickReload feature with your test plugin. Try this now:

  1. Edit the MyComponentWiredTest class.

  2. Add an @Ignore annotation to the testMyName() method.

  3. Add an org.junit.Ignore import to the test file:

    1
2
    import org.junit.Ignore;

  4. Save the test file.

  5. Run mvn package

  6. Re-run test using a method described in Step 3 - the updated test should now be ignored.

  7. Now try updating a unit test or a traditional integration test with the same steps.

Next Steps

This page taught you how to code using the Atlassian Wired Test Framework. Tests that use this framework are plugins that use Spring dependency injection to run inside an Atlassian host application. Note that test classes running under this framework are annotated with @RunWith(AtlassianPluginsTestRunner.class) to distinguish them from other integration tests.

When you use the framework, you have access to the Plugin Test Console. This console allows you to run tests and view their results right in the application. When your underlying test code changes, the system can run updated tests thanks to QuickReload.

At this point, all you really need is some test data. In the next section, you learn how to seed your host application with test data.

Rate this page: