# Phase 1: Core Coverage

## Overview

In this phase, you'll integrate the SeaLights Java Agent with your application to start collecting coverage data. This is the foundation for all subsequent phases and provides immediate visibility into your application's test coverage.

By the end of Phase 1, you'll have real-time coverage data flowing from your application component to the SeaLights Dashboard.

### What You'll Get

* **Real-time visibility into application component coverage** — See which parts of your code are being exercised during testing
* **Quick assessment of testing completeness** — Understand gaps in your test coverage at a glance
* **Improved release confidence** — Make data-driven decisions about release readiness

## Implementation Steps

{% stepper %}
{% step %}

#### Step 1: Download the SeaLights Java Agent

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 %}

#### Step 2: Run Your Component with the SeaLights Java Agent

Attach the **SeaLights Java Agent** as a `-javaagent` to your Java component. This enables SeaLights to capture coverage data whenever a method is executed within your component.

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

1. **Inline** — Add the `-javaagent` and parameters directly to the `java -jar` command used to run your component
2. **Environment variable** — Set the parameters via `JAVA_TOOL_OPTIONS` or a similar JVM variable

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

```bash
java -javaagent:/path/to/sl-test-listener.jar \
  -Dsl.mode=scanAndCoverage \
  -Dsl.tokenFile=/path/to/agent/tokenfile \
  -Dsl.appname=<component-name> \
  -Dsl.buildname=<component-build-number> \
  -Dsl.labid=<test-env-id> \
  -Dsl.includes=<included-packages> \
  -jar my_component.jar
```

{% endtab %}

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

{% code overflow="wrap" %}

```bash
export JAVA_TOOL_OPTIONS="-javaagent:/path/to/sl-test-listener.jar -Dsl.mode=scanAndCoverage -Dsl.tokenFile=/path/to/agent/tokenfile -Dsl.appname=<component-name> -Dsl.buildname=<component-build-number> -Dsl.labid=<test-env-id> -Dsl.includes=<included-packages>"

java -jar my_component.jar
```

{% 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.mode` - Defines the **operational mode of the Java Agent**, controlling how the agent behaves during test execution. When set to `scanAndCoverage`, the agent operates in **CD Only mode**, enabling:
  * Test detection (scan phase)
  * Coverage collection during test execution

{% hint style="info" %}
**Note:**

* This parameter is **required for CD Only Agent Mode - Phase 1: Core Coverage**

* The same agent is used across all phases

* To transition to full CI/CD (Phase 3: Continuous Coverage), **remove this parameter**
  {% endhint %}

* `sl.tokenFile` - Path to the [**agent token file**](/knowledgebase/phased-onboarding/java-onboarding-guide/getting-started/prerequisites.md#access-credentials). Note: The token can also be placed in a file named `sltoken` in the same directory as the agent. In that case, this parameter is not required.

* `sl.appName` - The **name of your application component**. This name will appear in the SeaLights dashboard and reports. This can be any name that represents your component.

* `sl.buildname` - A **unique identifier** that represents the current build of your application component — for example, the CI build number, a timestamp, or a custom name (as long as it is unique).

* `sl.labid` - A **unique name** representing the environment where the application component is deployed — for example, a machine IP or a label like `E2E-test-env-5`. Make sure the name is unique for each test environment.

* `sl.includes` - Specifies which Java packages SeaLights should monitor for coverage. By default, SeaLights may analyze all packages, but explicitly setting this improves performance. *Accepts a comma-separated list of search patterns with wildcards (`*` = any string, `?` = any character)*

Additional optional parameters may be found here: [CD Only Agent Mode Configuration Parameters](/knowledgebase/phased-onboarding/java-agent-parameter-reference/cd-only-agent-mode-configuration-parameters.md)
{% endstep %}
{% endstepper %}

#### What Happens When Your Application Component Starts?

After your application component starts, **SeaLights begins scanning it to analyze its method structure**. This process may take a few minutes.

During this time:

* The component—along with its specified build number—will appear immediately in the **SeaLights dashboard**, indicating a successful connection between the agent and SeaLights.
* The console will display messages confirming the successful startup of the SeaLights agent and later the completion of the scan.

If an error occurs, a detailed message will appear in the console with suggested troubleshooting steps.

### Verification

To confirm Phase 1 was successful:

1. **Check the console output** — Look for messages confirming successful agent startup and scan completion.
2. **Visit the SeaLights Dashboard** — Verify that:
   * Your application component appears in the dashboard
   * The build number you specified is visible
   * Coverage data begins appearing after you run tests against your application

{% hint style="success" %}
If your component appears in the dashboard and coverage data is being collected, Phase 1 is complete!
{% endhint %}

{% hint style="info" %}
Repeat the Phase 1 steps above for each Java component in your application. Doing so will allow SeaLights to capture coverage across a multi-service application!
{% endhint %}

***

### Next Steps

With core coverage in place, you're ready to move on to **Phase 2: Advanced Coverage Analytics**. In Phase 2, you'll gain granular coverage insights by test stage (Integration, Regression, E2E), enabling you to optimize your testing strategy and make more informed release decisions.


---

# 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-1-core-coverage.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.