# Using Supported Test Frameworks

{% hint style="info" %}
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](/knowledgebase/phased-onboarding/java-onboarding-guide/phase-2-advanced-coverage-analytics/using-non-supported-test-frameworks.md)
{% endhint %}

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

{% stepper %}
{% step %}

#### 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:

```bash
# 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

#validate the agent version
echo "Sealights Java Agent version used is:" `cat sealights-java-version.txt`
```

{% hint style="info" %}
Instructions for downloading a specific version of the agent can be found [here](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/downloading-the-java-agent#downloading-the-specific-agent-version-defined-in-customer-settings)
{% endhint %}
{% endstep %}

{% step %}

#### 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

{% tabs %}
{% tab title="1. Inline" %}
**Example 1: Adding the SeaLights Agent and parameters to your java command inline**

```bash
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:

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}
{% endtab %}

{% tab title="2. JVM Environment Variable" %}
Example 2: Using `JAVA_TOOL_OPTIONS`&#x20;

In this example, we declare the `javaagent` via standard JVM variables, like JAVA\_OPTS or JAVA\_TOOL\_OPTIONS for example. This is useful for testing frameworks like Cucumber for Java, which relies on JUnit or TestNG behind the scenes.

{% code overflow="wrap" %}

```bash
export JAVA_TOOL_OPTIONS=-javaagent:/path/to/sl-test-listener.jar -Dsl.tokenFile=/path/to/agent/tokenfile -Dsl.labid=<test-env-id> -Dsl.testStage="Functional Tests"
```

{% endcode %}

{% hint style="info" %}
NOTES:&#x20;

* Setting `JAVA_TOOL_OPTIONS` affects every JVM on the machine. If you only want the agent to run with a specific JVM, use inline parameters instead. `J`
* `JAVA_TOOL_OPTIONS` is limited to 1024 characters.
  {% endhint %}
  {% endtab %}
  {% endtabs %}

**Minimum Required Parameters**

* `sl.tokenFile` - Path to the [agent token file](/knowledgebase/phased-onboarding/java-onboarding-guide/getting-started/prerequisites.md#access-credentials)
* `sl.labid` - A unique name representing the environment in which your AUT[^1] 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](/knowledgebase/phased-onboarding/java-agent-parameter-reference/java-agent-configuration-parameters.md)
{% endstep %}
{% endstepper %}

<details>

<summary>ALTERNATIVE APPROACH: Using the SeaLights Build Tool Plugins</summary>

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.&#x20;

Instructions for each plugin can be found:

* [ALTERNATIVE: Maven Plugin](/knowledgebase/phased-onboarding/java-onboarding-guide/phase-2-advanced-coverage-analytics/using-supported-test-frameworks/alternative-maven-plugin.md)
* [ALTERNATIVE: Gradle Plugin](/knowledgebase/phased-onboarding/java-onboarding-guide/phase-2-advanced-coverage-analytics/using-supported-test-frameworks/alternative-gradle-plugin.md)<br>

</details>

#### 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

{% hint style="success" %}
If this test stage reflects coverage under your component, Phase 2 is complete!
{% endhint %}

***

### Next Steps

With advanced coverage analytics in place, you're ready to move on to [**Phase 3: Continuous Coverage**](/knowledgebase/phased-onboarding/java-onboarding-guide/phase-3-continuous-coverage.md). In Phase 3, you'll integrate SeaLights into your CI pipeline for continuous, up-to-date visibility into build coverage.

[^1]: Application Under Test


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealights.io/knowledgebase/phased-onboarding/java-onboarding-guide/phase-2-advanced-coverage-analytics/using-supported-test-frameworks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.