Xcmailr Plugin

XcMailr Plugin

Temporary mail is one of the most needed external services in UI test automation. Exactly for these purposes XcMailr was created. To make communication with the temporary mail server easier XcMailr provides the XcMailr Client which encapsulates the provided REST API. For Neodymium users we wanted to improve the usability even more and provide an API that feels similar to the Neodymium experience. So we added an automatic setup via configuration files, polling mechanics and some handy shortcuts for often used requests.

Nevertheless the project can be used within every Maven project and doesn't requiere a Neodymium project.

Requirements

• Java 11
• Maven 3.x

Getting Started

First of all, you will need to add this plugin as a dependency in your maven project. Please review the plugin project itself for the latest release version.

<dependency>
    <groupId>com.xceptance</groupId>
    <artifactId>neodymium-plugin-xcmailr</artifactId>
    <version>1.1.0</version>
</dependency>

After including the dependency, it's time to populate the configuration file: config/xcmailr.properties. Analog to neodymium.properties, the configuration file config/xcmailr.properties can be overwritten for test purposes by providing a config/dev-xcmailr.properties file. By the way, the plugin can also be configured by providing the settinga as Java properties to the test execution process.

Setup

API Token

You need to have access to a running XcMailr instance.

• Create an account on your instance
• Go to the Edit Profile tab and scroll to the "API Token" section
• Click "Generate new token"
• Copy the token to your configuration file

XcMailr properties

In the table below you can see all available properties to configure XcMailr Plugin. In case you need to change them for the current test, you can use XcMailrApi.getConfiguration().

Property	Default value	Description
xcmailr.url	-	URL to access both XcMailr server and XcMailr website (influences all API methods)
xcmailr.apiToken	-	individual API token to access personal temporary mails (required to execute all API methods)
xcmailr.temporaryMailValidMinutes	15 minutes	period during which the created temporary email should be active
xcmailr.maximumWaitingMinutes	10 minutes	amount of time to wait for an email to be received by the temporary mail address
xcmailr.pollingIntervalSeconds	30 seconds	option to define how often should the temporary mail be checked for new emails

API

We provide the following function to use the XcMailr.

Configuration

getConfiguration() : The function give access to the current configuration. Returns the configuration.

Mailboxes

The following functions are uses to manage the mailbox that will be used for the test.

createTemporaryEmail(String eMailAddress, boolean forwardEnabled) : Create a mailbox with the given e-mail address and activate forwarding if needed. Returns the mailbox.

getMailbox(String eMailAddress) : Retrieve the mailbox of the given e-mail address. Returns the mailbox.

deleteMailbox(String eMailAddress) : Delete the mailbox of the given e-mail address.

listMailboxes() : List all mailboxes within the used XcMailr account. Returns a list of mailboxes.

updateMailboxEmailAddress(String oldEMailAddress, String newEMailAddress) : Shortcut function to update the e-mail address of the mailbox. Returns the updated mailbox.

updateMailboxDeactivationTime(String eMailAddress, int newValidMinutes) : Shortcut function to update the period until the mailbox is deactivated. Returns the updated mailbox.

updateMailboxForwarding(String eMailAddress, boolean forwardEnabled) : Shortcut function to update the forwarding setting of the mailbox. Returns the updated mailbox.

updateMailbox((String oldEMailAddress, String newEMailAddress, Integer, Boolean) : Basic function to update the mailbox settings. Returns the updated mailbox.

Mails

retrieveAllMailsFromMailbox(String eMailAddress) : Shortcut function to retrieve all e-mails from the mailbox with the given e-mail address. Returns a list of mails.

retrieveLastEmailBySubject(String eMailAddress, String subject) : Shortcut function to retrieve the last e-mails with a matching subject from the mailbox with the given e-mail address. The subject can be written as RegEx. Returns the last matching mail.

retrieveLastEmailBySender(String eMailAddress, String fromEMailAddress) : Shortcut function to retrieve the last e-mails with a matching from e-mail address from the mailbox with the given e-mail address. The from e-mail address can be written as RegEx. Returns the last matching mail.

fetchEmails(String eMailAddress, String from, String subject, String textContent, String htmlContent, String headers, boolean lastMatch) : Basic function to retrieve emails from the mailbox with the given e-mail address. All parameters (except eMailAddress and lastMatch) can be written as RegEx. Returns a list of matching mails.

Attachments

fetchAttachment(Mail mail, String attchmentId, File saveAttchmentFile) : Fetch a specific mail attachment and save it to the given file.

Open mail content within the browser

To view html content in the browser we provide a solution within the Neodymium API. Please call SelenideAddons.openHtmlContentWithCurrentWebDriver(textHtml) to open a text within the browser.

    Mail mail = XcMailrApi.retrieveLastEmailBySubject();
    SelenideAddons.openHtmlContentWithCurrentWebDriver(mail.textContent);