In order to capture code coverage on your backend server, you need to install our test listener as a Java agent.
The listener needs to be placed alongside the server and added to the JVM command line using the -javaagent parameter together with its required parameters.

We recommend using the Lab ID method to link between the test listener and the test runner. For this you will have to pass the labid on top of the buildSessionId parameter.

• If the artifact was packaged using the Include Resources option, then Test Listener will find the token and session ID inside it therefore you only need to pass the javaagent parameter:

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend [-Dsl.labId=<lab ID>]

• If the artifact was not packaged using the Include Resources option, then the Test Listener needs to be provided the token and session ID as well:

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

We have gathered a list of the most common configurations below

Command Line

Usually the easiest is using the JAVA_TOOL_OPTIONS environment variable - Note it will affect every JVM that runs. If you need to affect specific JVM, then it can be provided directly to the JVM command line or to the JVM through its own technologies standards, like JAVA_OPTS, JAVA_OPTIONS etc.

• If the artifact was packaged using the includeResources option, then Test Listener will find the token and session ID inside it therefore you only need to pass the javaagent parameter:

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/sl-test-listener.jar  -Dsl.tags=backend [-Dsl.labId=<lab ID>]"

• If the artifact was not packaged using the includeResources option, then the Test Listener needs to be provided the token and session ID as well:

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=backend -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]"

Tomcat

The CATALINA_OPTS environment variable is used to pass configuration flags and system properties to the JVM that runs specifically the Tomcat server. Since Sealights Agent is usually in use only by Tomcat, you'll be best advised to use CATALINA_OPTS, whereas if you put your settings in JAVA_OPTS, it will be used locally by other Java applications as well. Both options are compatible with Sealights.

CATALINA_OPTS+="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=tomcat [-Dsl.labId=<lab ID>]"

If you are running Tomcat from the command line, you can just set the environment variable, either from the command line or by updating the setenv.sh (or setenv.bat in windows)
If you are running Tomcat as a service on Linux, you will need to update the service file itself under /etc/init.d or any other startup script you have set up for the service.
Another option is to update the setenv.sh (setenv.bat on Windows) and update the JVM parameters inside it.

Tomcat as a Windows Service

If you are running your application ou need to edit the Windows service. There are three ways to do this:

1. Start Tomcat9 with //MS//ServiceName to get an icon in the system tray which gives you a quick access to the configuration of the service.

2. Open the service manager in the "Control Panel". There is an entry for Tomcat. In the editor, there is a tab where you can add additional JVM parameters (See screenshot below)

3. Write a script which edits the config for you using a command like tomcat9 //US//... . This way, you can save the config somewhere for backup or update dynamically your server from a CI/CD script. You can refer to the official Tomcat documentation page for more details and options. For example, the ommand may look like tomcat9 //US//MyService --JvmOptions='-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=tomcat [-Dsl.labId=<lab ID>]'

Kubernetes using an Init container

In the sample Yaml file below, we dynamically download the agent into a side car container to make it available to the JVM of our application container

spec:
  initContainers:
  - name: java-cd-agent
    image: busybox:latest
    imagePullPolicy: IfNotPresent
    command: ["/bin/sh", "-c"]
    args:
      - |
        wget -nv -O /tmp/sealights-java-agents.zip https://agents.sealights.co/sealights-java/sealights-java-latest.zip;
        mkdir -p /sealights;
        unzip -j /tmp/sealights-java-agents.zip sl-test-listener.jar -d /sealights;
    volumeMounts:
      - mountPath: /sealights
        name: sealights-java-coverage-listener
  containers:
  - name: your-main-container
    # other container configurations
    env:
    - name: sl.tags
      value: k8s
    - name: sl.labId
      value: integ_test_microservices
    - name: JAVA_TOOL_OPTIONS
      value: -javaagent:/sealights/sl-test-listener.jar 
    volumeMounts:
    - mountPath: /sealights
      name: sealights-java-coverage-listener
  volumes:
    - name: sealights-java-coverage-listener
      emptyDir: {}

JBoss & Wildfly

When the application server is JBoss or WildFly, you should also update the following parameters: jboss.modules.system.pkgs=org.jboss.byteman,io.sealights

JAVA_OPTS+="-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=jboss -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>] -Djboss.modules.system.pkgs=org.jboss.byteman,io.sealights"

Spring boot maven plugin

When using the spring boot maven plugin, you can set the jvmArguments property in the configuration section of the plugin to define the needed arguments.

<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<configuration>
		<jvmArguments>-javaagent:${sl.testListenerPath} -Dsl.tags=springboot -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]</jvmArguments>
	</configuration>
</plugin>

Jetty

For the Jetty application server, if you are using the standard jetty.sh file then you can set the JAVA_OPTIONS environment variable with the javaagent, token and session ID.
Otherwise just add it to the JVM command you use to run jetty.

export JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/sl-test-listener.jar -Dsl.tags=jetty -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]"

Gradle Build File

When using gradle to bring up a JVM with your application, you can set the javaagent in the jvmArgs

jvmArgs=["-javaagent:/path/to/sl-test-listener.jar", "-Dsl.tags=gradlebackend", "-Dsl.tokenFile=/path/to/sltoken.txt", "-Dsl.buildSessionId=buildSessionId.txt" ["-Dsl.labId=<lab ID>"] ]

WebSphere

In the admin console:

• Go to Servers→Application servers

• Select your server

• Go to Configuration→Service Infrastructure→Java and Process Management→Process Definition→Additional Properties→Java Virtual Machine

• Add the agent configurations in the Generic JVM arguments 

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=websphere -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

WebLogic

In the admin console:

• Go to Environments→Servers

• Select your server

• Go to Server Start

• Add the agent configurations in the Arguments 

-javaagent:/path/to/sl-test-listener.jar -Dsl.tags=weblogic -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.buildSessionIdFile=buildSessionId.txt [-Dsl.labId=<lab ID>]

PCF/ VMWare Tanzu

Adding the Sealights java agent into you Pivotal Cloud Foundry / VMWare Tanzu Application Services is detailed in the following dedicated article:

• https://sealights.atlassian.net/l/c/5UZomdRK

Elastic Beanstalk

Beanstalk instance running a single Java process

• In the AWS web console, select the requested EB application

• Select the Configuration side menu

• Modify the "Software" settings in the Configuration overview

• Under Environment properties, add a new property:

  • JAVA_OPTS with the value -javaagent:sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>]

    

• Ensure the value is aligned to the location of the sl-test-listener.jar location within the Elastic Beanstalk instance

• After the Beanstalk instance runs, ensure that the Test Listener is running from the Cockpit -> Agent Monitor screen.

Using Beanstalk configuration files .ebextensions (Tomcat)

• Add .ebextensions folder to your application's directory

• Inside .ebextensions, create a file called sealights-java.config

• Now, we will need to specify to the configuration file that will be loaded into Elastic Beanstalk to perform the following actions:

  • Download the latest SeaLights agent

  • Unzip the downloaded agent

  • Give the required permissions

  • Pass the required -javaagent parameter to the JVM

  • Use the following sealights-java.config content as an example:

    commands: 1-download-java-agent: command: "sudo curl --location https://agents.sealights.co/sealights-java/sealights-java-latest.zip > /tmp/sealights-java.zip" 2-prepare-java-agent: command: "mkdir /tmp/sealights" command: "unzip /tmp/sealights-java.zip -d /tmp/sealights" 3-set-sealights-permissions: command: "chmod +rwx /tmp/sealights" option_settings: namespace: "aws:elasticbeanstalk:container:tomcat:jvmoptions" option_name: "JVM Options" value: "-javaagent:/tmp/sealights/sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>]"

Beanstalk instance running multiple Java processes

In this case, a Procfile needs to be configured which defines the JVM configuration on a per-service basis:

• Ensure the "Include Resources" checkbox is checked for this application, so that the buildSessionId.txt and the sltoken.txt files are packaged into the artifact

  • If unselected, the build session ID and token files need to be defined explicitly within the Java arguments

• The Test Listener must be deployed onto the Elastic Beanstalk instance. This can be achieved by using the Maven Copy plugin, like described here.

Once the above prerequisites are met, a Procfile needs to be defined:

• Within the Procfile, you specify the .jar with which SeaLights starts up using the following syntax:

  <service name>: <java command> <java args>

For example:

service: java -javaagent:sl-test-listener.jar -Dsl.tags=beanstalk [-Dsl.labId=<lab ID>] -jar service.jar