Introduction

JEMH now exposes an API that allows customers to write their own tests if they so wish. Do not worry though - The Plugin People test JEMH extensively as part of the app’s development process. Customer Acceptance Tests are purely to give customers additional peace-of-mind.

These tests can be used to validate business critical workflows in non-production environments, prior to migration to production environments. This means that when Jira / JEMH /3rd party add-ons are updated, expected behaviour can be validated without laborious and error-prone manual repetition.

This page will cover the mechanism by why customers can write their own Customer Acceptance Tests for JEMH. This includes using email content previously exported from JEMH, as well as Profile XML files to drive issue creation and updates.  The tests enable issue level assertions over final issue state, and deeper, enable the collection of notifications and validation of the content is as expected.

How it works

The tests are written in Java, so knowledge of Java language is required.  Assertions are made on issue state, so knowledge of Issue operations and related Jira API's is also required (but life is a learning curve!).  For those with JEMH familiarity we have effectively provided a means to run JEMH Test Cases against JEMH Profiles in a test oriented manner.  The tests run within JIRA, so assertion on post-create/update issue state is possible.

The tests exist outside your Jira as Java source code. They need to be packaged up (including Test Case and Profile XML text files that will be used in the test) and deployed into the Jira instance as an Add-on, so they are deployed within the OSGi container and can access the Integration APIs exposed by JEMH 2.4.1+ , its where local Jira classes can also be accessed.

After deployment, during test setup (now running within the deployed add-on inside Jira) its possible to do setup tasks, for example, spinning up a local (to the test) SMTP Server and re-configuring Jira to use that for the duration of the test.  After tests have completed, the generated test add-on is uninstalled.

After the test harness has been used to run Test Cases against supplied Profiles, a collection of related Issue objects will be returned, along with beans containing the JEMH audit-event detail.  Any unit test Assertion failures will be driven back to the invoking agent, whether that is your IDE running a single unit test (so Pass / Fail will be evident) or a full suite of tests via atlas-mvn clean install.

The tests are effectively JUnit tests. When executed the following process occurs:

Example Test

Setting up

Building the code will try to contact a Jira instance at http://localhost:8080 using username admin, and password admin.  You are not expected to have a production instance available like this, JEMH integration tests will manipulate mail queues and server configurations!

1. JEMH-API and JEMH-AO artifacts are now available by using the following repository in your pom.xml

   JEMH Repositories:

   <repositories> <repository> <id>atlassian-public</id> <url>https://maven.atlassian.com/repository/public</url> <snapshots> <enabled>true</enabled> <updatePolicy>never</updatePolicy> <checksumPolicy>warn</checksumPolicy> </snapshots> <releases> <enabled>true</enabled> <checksumPolicy>warn</checksumPolicy> </releases> </repository> <!-- for JEMH API package --> <repository> <id>ppl-public</id> <name>PPL Public Release Repository</name> <url>https://nexus.thepluginpeople.com/repository/ppl-public/</url> </repository> <!-- for arquillian containers --> <repository> <id>adaptavist-nexus</id> <name>Adaptavist External Releases</name> <url>https://nexus.adaptavist.com/content/repositories/external</url> </repository> </repositories>

    

2. JEMH Dependencies:

   <properties> <jemh.api.version>2.1.2</jemh.api.version> </properties> <dependencies> <dependency> <groupId>com.javahollic.jira.jemh</groupId> <artifactId>jemh-api</artifactId> <version>${jemh.api.version}</version> <scope>provided</scope> </dependency> </dependencies>

    

3. Checkout the https://bitbucket.org/pluginpeople-public/jemh-example-extensions project:

   git clone https://bitbucket.org/pluginpeople-public/jemh-example-extensions

    

4. At the command line, go into user-integration-testing and run atlas-mvn clean install to pull down all the dependencies, (the trailing 'sonar' repository in the project pom will be updated soon with our own public repo URL)

Once this has been done, dependencies will be available in target/dependencies so they can be included by path in the integration test. 

What is in the project

The user-integration-testing src/test folder contains the following:

AbstractJEMHIntegrationTest is the superclass of your integration test

ExampleTest class, is the integration test you will run

ITBootstrap is a utility class to help build the JAR containing the test and its dependencies to Jira, in order for it to be run.

arquillian.xml is a configuration file required to configure the artifact deployment, configure as needed (host / port / user / pass)

basic-profile.xml is a Profile, exported from JEMH, possibly from production!

basic-testcase.txt is a Text email source, exported from JEMH auditing/Test Case features.  Its used to drive the test.  No, you cannot use a .msg file, they are binary and proprietary!

Acceptance Test structure

The superclass of the test is AbstractJEMHIntegrationTest, covered later.  

TEST_PROFILE_KEY

This field of the test defines a test-specific reference (you can vary it if several are needed per test).  Its purpose is to act as a constant reference to a deployed Profile, so that one Profile may be installed, and then retrieved and used by many Test Methods, as each test method invocation results in cleared local field variables.

deployTests()

The test contains a static method that is invoked by the Arquillian TestRunner (indicated by @RunWith(Arquillian.class) annotation.  This method uses Shrinkwrap via the ITBootstrap helper class to package up all the resources required by the current test (Test Case text files, and Profile XML files).  The ITBootstrap class is there to allow customers to potentially package any required Maven dependency is in the project pom.xml, required within the test.  The default includes the Greenmail SMTP server, covered later.  Remember that resources referred here exist in src/test/resources, resources should not be prefixed with /.  In our example, all integration test resources live under src/test/resources/integration.

The archive.toString(true) method call will log out the content of the test to be deployed, which is helpful in determining that all expected resources are actually present.

Test Method : installProfile()

This test is executed in sequence, lowest first, so this test runs first.

The installProfile() method uses a helper method to install the referred Profile XML resource that was packed as part of deployment.  The TEST_PROFILE_KEY as discussed above is a unique key that will be used to store the related ProfileBean within the JEMH Integration Test Harness.  Test Methods use this key to retrieve a given Profile rather than go through a lengthy process of Profile re-creation.

This test just deploys a profile, and asserts that a Profile Bean (not backed by an Active Objects entity) is created.  

Test Method : runTestCase()

This test has a higher sequence so runs second.  Here you can see the ProfileBean is retrieved using the TEST_PROFILE_KEY.  A helper method is then called to invoke and run the Test Case (referred by resource path in the packaged JAR).

The ProcessingResultBean here is tested to contain one result, each result contains a reference to the related Issue operated on, and the related JEMH audit event bean.  Here we aren't processing any notifications on the mail queue, so we purge any that are present.

AbstractJEMHIntegrationTest structure

setupTest()

This method is executed one per Test class, before any @Test methods are executed.  Its here to enable precise setup of required resources, the current example just clears the JIra mail queue of pending notifications (why you may want to use this on a TEST instance initially!). We remove items from the mail queue so that we know that notifications in the queue after the test runs were as a result of the test!

teardownTest()

Likewise, after all @Test methods have run, this is called to clear up.

Selecting a Jira instance

JEMH uses the AMPS launcher to bootstrap an environment as part of the build.  For Customer Acceptance Testing, its more likely you'll be pointing at a DEV or UAT server.  In src/test/resources/arquillian.xml you will find the following that defines what hostname / port / contextPath / username /password (sys admin required for JEMH), update these as required.

Running the Example Test

Initially, just run atlas-mvn clean install from the project folder where the pom.xml is, or run an individual test from within your favourite IDE.  A full log of an example invocation is attached (log.txt).  By doing this, Maven will resolve all pom.xml dependencies and copy them into target/dependencies.  This means they would then be available to the test packaging instruction, see ITBootstrap.buildArchive() and how it includes such a dependency (greenmail jar):

The results for a single execution triggered from the UI look like this in Eclipse:

Open

A full build run from the command line results in:

Using atlas-debug

The following, when launch a bootstrapped Jira environment, once up, the tests above can be run against it.