Payara Server Remote Arquillian Container

The Payara Server Remote Arquillian container connects to a running remote Payara Server instance for integration testing using a remote protocol. You can use your normal Payara deployment to perform your test. The integration connects Arquillian to the DAS via the REST Interfaces to manage Payara Server over HTTP or HTTPS protocol.

This gives you the flexibility to use any possible deployment scenarios having your servers either on many different physical or virtual nodes, or on the same one.

Usage

The Payara Server Remote Arquillian container can be found on Maven Central, and can be included in your project using the following Maven coordinates:

<dependency>
  <groupId>fish.payara.arquillian</groupId>
  <artifactId>arquillian-payara-server-remote</artifactId>
  <version>${version}</version>
</dependency>

You can find the latest artifact version from here.

Configuring the Container

The container can be configured via the arquillian.xml using the standard Arquillian Container Configuration mechanism.

The following Arquillian Container configuration options are available:

Table 1. Configuration Options
Name	Description	Default
`adminHost`	The host to be used to access Payara Admin API.	`localhost`
`adminHttps`	You can use it to specify whether the http or https protocol shall be used to access the DAS. The property value can be true or false.	`false`
`adminPort`	The port to be used to access Payara Admin API.	`4848`
`adminUser`	The name of the admin user of your DAS. If omitted, no authentication will be used to access the DAS. In this case the `adminPassword` property should also be empty.
`adminPassword`	The password of the admin user of your DAS. Cannot be omitted if you declare the admin user. If no authentication will be used to access the DAS you must have empty password for your admin user of your domain.
`authorisation`	If true, basic access authentication is enabled. And indicates that remote server requires an `adminUser` & `adminPassword`.	`false`
`ignoreCertificates`	If true, ignores all certificate checks when connecting to the server. Useful when testing domains hosted in Docker containers and there is no way to turn off SSL.	`false`
`libraries`	A comma-separated list of library JAR files. Specify the library JAR files by their relative or absolute paths. Specify relative paths relative to `domain-dir/lib/applibs`. The libraries are made available to the application in the order specified.
`properties`	Optional keyword-value pair that specify additional properties for the deployment. The available properties are determined by the implementation of the component that is being deployed.
`target`	Payara has a notion of a target, which specifies the target to which you are deploying. We use the "target" as property key with the same semantics as the standard Payara utilities do. Valid values of the target are: - server: Deploys the component to the default Admin Server instance (on your DAS server). This is the default value if the property is omitted. - instance_name: Deploys the component to the specified stand-alone sever instance, which may be on the same hosts or can be on a different one as the DAS server. - cluster_name: Deploys the component to every server instance in the cluster. They can be on the same or on several other hosts as the DAS server. Note: Arquillian use only one instance to run the test case. The domain name as a target is not a reasonable deployment scenario in case of testing. The HOST address and port numbers of the test server instance used by Arquillian (determined by the target property) been retrieved automatically from the DAS server. You have to make them accessible for your test environment (consider any firewall or proxy configuration).	`server`
`type`	If set to `osgi`, the component is packaged as an OSGi bundle. If the component is packaged as a regular archive, do not set this option.

The context root that will be used to run the tests is also retrieved automatically from the DAS server. If you do not have a sun-web.xml, glassfish-web.xml or payara-web.xml file in your web application, Payara will use the name of your deployment without the extension as context root. The same rule is applied for enterprise applications if there is no application.xml file. The jar test-deployments are treated as a web application. You can use the above standard GlassFish / Payara XML files as normal to declare your context root to be applied. You should consider the above description to avoid any conflict with your already deployed web or enterprise applications in your administrative domain.

Examples

To configure the Arquillian Container options, you need to use an arquillian.xml file placed on the test classpath. Here’s an example arquillian.xml file. It configures adminPort with a static value. It configures adminPassword as a value of a system property my.admin.password, which you can specify for example in the maven surefire plugin using the systemPropertyVariables option or on command line like mvn -Dmy.admin.password=mypassword test.

Example arquillian.xml file

<?xml version="1.0"?>
<arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://jboss.org/schema/arquillian"
            xsi:schemaLocation="http://jboss.org/schema/arquillian
                http://jboss.org/schema/arquillian/arquillian_1_0.xsd">

    <container qualifier="payara" default="true">
        <configuration>
            <property name="adminPort">4848</property>
            <property name="adminPassword">${my.admin.password}</property>
        </configuration>
    </container>
</arquillian>

If you want to configure more containers, you can switch between them by setting the arquillian.launch system property to the container’s qualifier. This is how you can do it with the maven surefire plugin (my.admin.password system property is used to set the adminPassword property in arquillian.xml):

Example Surefire plugin configuration in a pom.xml file

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <systemPropertyVariables>
            <arquillian.launch>payara</arquillian.launch>
            <my.admin.password>mypassword</my.admin.password>
        </systemPropertyVariables>
    </configuration>
</plugin>