Using Supported Test Frameworks

Capturing Coverage Using Supported Test Frameworks

You are on Phase 2: Advanced Coverage Analytics >> Implementation Path: Using Supported Test Frameworks. If you are using a "home-grown" or highly customized test framework, please see the instructions for Using Non-Supported Test Frameworks

You can add the agent in one of the following ways:

1. Inline — Add the -javaagent and parameters directly to your java -jar command used to run your tests

2. Environment variables — Set the parameters via JAVA_TOOL_OPTIONS or a similar JVM variable

Implementation Steps

1

Download the SeaLights Java Agent

The SeaLights Java Agent will need to be available on the machine where you build your test runner and/or run your tests.

Download the latest version of the SeaLights Java Agent.

There are two agent files

• Build Scanner - sl-build-scanner.jar

• Test Listener - sl-test-listener.jar

These agent files can be downloaded from: https://agents.sealights.co/sealights-java/sealights-java-latest.zip

Example CLI commands for downloading the SeaLights Java Agent:

# Download the latest Java agent
wget -nv https://agents.sealights.co/sealights-java/sealights-java-latest.zip

# Extract the agent
unzip -oq sealights-java-latest.zip

Instructions for downloading a specific version of the agent can be found here

2

Run Your Test Runner with the SeaLights Java Agent

When using a supported framework (such as JUnit or TestNG), attach the SeaLights Java Test Listener agent as a -javaagent to your test runner. This allows SeaLights to automatically associate each test execution with its code coverage.

You can add the SeaLights Java Agent in one of the following ways:

1. Inline — Add the -javaagent and parameters directly to your java -jar command used to run your component

2. JVM Environment Variable — Set the parameters via JAVA_TOOL_OPTIONS or a similar JVM variable

1. Inline

Example 1: Adding the SeaLights Agent and parameters to your java command inline

java -javaagent:/path/to/sl-test-listener.jar \
  -Dsl.tokenFile=/path/to/agent/tokenfile \
  -Dsl.labid=<test-env-id> \
  -Dsl.testStage="Functional Tests" \
  -cp $CLASSPATH org.testng.TestNG -testclass com.my.test

Or, the same approach, using a dedicated environment variable to inject the SeaLights Agent options into the command:

export SEALIGHTS_OPTS="-javaagent:/path/to/sl-test-listener.jar -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.labid=<test-env-id> -Dsl.testStage=\"Functional Tests\" "

java $SEALIGHTS_OPTS -cp <CLASSPATH> org.testng.TestNG -testclass com.my.test

In the sample command above, the javaagent is declared via a dedicated SEALIGHTS_OPTS environment variable, but you can also declare it via standard JVM variables, like JAVA_OPTS or JAVA_TOOL_OPTIONS for example. This is demonstrated on the JVM Environment Variable tab.

2. JVM Environment Variable

Minimum Required Parameters

• sl.tokenFile - Path to the agent token file

• sl.labid - A unique name representing the environment in which your AUT was deployed (and against which you are testing). This MUST match the Lab ID from Phase 1.

• sl.testStage - A label for the type of tests being run (e.g., "Functional Tests", "Integration Tests", "E2E Tests"). This will be used when displaying the coverage data in your SeaLights reports.

Additional optional parameters may be found here: Java Agent Configuration Parameters

ALTERNATIVE APPROACH: Using the SeaLights Build Tool Plugins

SeaLights provides plugins for both Maven and Gradle, allowing you to integrate it into your CI pipeline even more seamlessly. These plugins take the place of the above steps.

Instructions for each plugin can be found:

• ALTERNATIVE: Maven Plugin

• ALTERNATIVE: Gradle Plugin

What Happens When Your Test Runner Starts?

The SeaLights agent rides along with your test runner to send metadata about the tests you're running to the SeaLights Backend. After your test execution is completed, SeaLights will automatically show you the percentage of code covered by this test run.

Verification

To confirm Phase 2 was successful:

1. Check the console output — Look for messages confirming successful agent startup.

2. Visit the SeaLights Dashboard — Verify that:

   • Your new test stage appears in the dashboard under your component

   • Coverage data begins appearing under the new test stage

If this test stage reflects coverage under your component, Phase 2 is complete!

---

Next Steps

With advanced coverage analytics in place, you're ready to move on to Phase 3: Continuous Coverage. In Phase 3, you'll integrate SeaLights into your CI pipeline for continuous, up-to-date visibility into build coverage.