I’m working on a customised email handler (based on Atlassian’s original CreateOrCommentHandler class), that extends some of the available parameters to enable our team to better handle their Jira loads.
I won’t go into too much detail about the handler itself, but I would like to document the test harness that allows me to perform some integration/regression testing against it.
The test environment includes:
- an instance of JIRA (with some manual modifications)
- an IMAP/SMTP server (Apache James).
An email message handler is not a normal plugin module type for JIRA (see the list here), so there is no entry in the
atlassian-plugin.xml required for it. The plugin infrastructure in this case is merely a vehicle to upload the classes into Jira.
We need to manually enable access to the custom handler by editing the
imapservice.xml file (under
WEB-INF/classes/services/com/atlassian/jira/service/services/imap/imapservice.xml) to include our class:
Once this is done (and JIRA is restarted), we can add services that use this handler by adding a regular IMAPService, and selecting our custom handler.
We also need to set JIRA up with some dummy data - e.g. projects, users - and export this configuration as a testing baseline (using the administration tool).
Can’t really test an email handling plugin without an email!
Rather than mocking out a whole bunch of complex classes (the message itself and JIRA’s internals), using a lightweight mail server and simulating a real environment would be much simpler.
I found Apache James, and was able to quickly get it up and running as a standalone server (To use the default ports however - SMTP: 25, IMAP: 143 -, you need to start the server as root). In the default configuration, James will create a user account for the receiver(s) when receiving an email, if they don’t already exist. So we are free to send emails to and check the accounts of which ever user we want, without a setup overhead!
A utility class will help us to send emails and clear user’s inboxes (this class based on Claude Duguay’s IBM article).
The parent class
javax.mail.Authenticator helps us with the
Test class structure
The test classes extend Atlassian’s
com.atlassian.jira.functest.framework.FuncTestCase, which provides us with access to convenience functions to restore data from XML and navigate JIRA easily.
The test harness is handled by overridding
tearDownTest() (Note that to be a ‘good neighbour’, I restored a ‘clean’ version of the config when we’re done):