# Capturing Unit Tests (UT) with the SeaLights Maven Plugin — Delta Guide

## What changes vs. scan-only?

1. **executionType**

* Set to **`full`** (instead of `scanonly`).\
  This injects **both** the Build Scanner and the Test Listener (Surefire/Failsafe).

2. **testStage (optional)**

* Default stage label is **`Unit Tests`**.
* If you want a different label (e.g., “UT – Fast”, “UT CI”), set `"testStage": "<your-name>"`.

3. **Surefire/Failsafe argLine merge**

* If your POMs already set `<argLine>…</argLine>`, keep your content **and** append SeaLights’ variable:
  * Surefire: `@{sealightsArgLine}` (or override via `surefireArgLine`)
  * Failsafe: `@{sealightsArgLine}` (or override via `failsafeArgLine`)
* If you don’t touch argLine yourself, the plugin wires it automatically.

4. **Listener/Scanner jars (if pre-downloading)**

* If you pin artifact paths, provide **both**: `scannerJar` **and** `listenerJar`.

5. **(Optional) labId / tags / metadata**

* Use when you want to group or filter test runs (e.g., multiple suites in parallel).

## Configuration file <a href="#configuration-file" id="configuration-file"></a>

### Minimal JSON snippet (delta only)

```json
{
  "executionType": "full",
  "testStage": "Unit Tests"   // change if you want a custom label
}
```

Keep all your existing base fields from the “Scanning Builds” doc (token/BSID/app/branch/packages, etc.).

***

### Recommended full JSON (compact but complete)

> Start from your scanning JSON and add the bolded fields.

{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
  "executionType": "full",
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${JOB_NAME}",
  "branchName": "${GIT_BRANCH}",
  "buildName": "${BUILD_NUMBER}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "off",
  "logFolder": "/tmp",
  "sealightsJvmParams": {}
}
```

{% endcode %}

### Frequently used parameters <a href="#frequently-used-parameters" id="frequently-used-parameters"></a>

#### Surefire and Failsafe argLine update <a href="#surefire-and-failsafe-argline-update" id="surefire-and-failsafe-argline-update"></a>

If you have configured the argLine for surefire and/or failsafe, the integration will include adding `@{sealightsArgLine}` to them.\
This can be updated/overridden by adding and updating the following parameters to the JSON file:

* **surefireArgLine** - Whatever is defined here will be updated in the argLine of surefire if it exists. By default `@{sealightsArgLine}`
* **failsafeArgLine** - Whatever is defined here will be updated in the argLine of failsafe if it exists. By default `@{sealightsArgLine} -Dsl.testStage="Integration Tests"`

**Sample of Surefire and Failsafe argLine update**

{% code overflow="wrap" lineNumbers="true" %}

```
"surefireArgLine": "-Xms1280m -Xmx1280m @{sealightsArgLine}"
"failsafeArgLine": "-Xmx8192m @{sealightsArgLine} -Dsl.testStage=\"Integration Tests\""
```

{% endcode %}

#### Tagging <a href="#tagging" id="tagging"></a>

You can add tags to be viewed in the cockpit for the agents started by this maven job by passing them through the `sl.tags` property in the `sealightsJvmParams` field

{% code overflow="wrap" lineNumbers="true" %}

```
"sealightsJvmParams": {
    "sl.tags": "ci,unittest",
}
```

{% endcode %}

## Sample script <a href="#sample-script" id="sample-script"></a>

{% hint style="info" %}
**Best Practice:** This script is very often added to a dedicated **pre-build step** in the CI job (i.e. Jenkins).
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```sh
echo "Downloading Sealights Agents..."
wget -nv https://agents.sealights.co/sealights-java/sealights-java-latest.zip
unzip -o sealights-java-latest.zip
echo "Sealights agent version used is:" `cat sealights-java-version.txt`

echo  '{ 
    "executionType": "full", 
    "tokenFile": "./sltoken.txt", 
    "createBuildSessionId": true,
    "appName": "${JOB_NAME}",   
    "branchName": "${GIT_BRANCH}", 
    "buildName": "SL_Timestamp",  
    "packagesIncluded": "*com.example.*",   
    "includeResources": true, 
    "logEnabled": false, 
    "logDestination": "console", 
    "logLevel": "warn"
  }' > slmaven.json
 
echo "Updating POM with Sealights..."
java -jar sl-build-scanner.jar -pom -configfile slmaven.json -workspacepath .
```

{% endcode %}

**Next step** is to run your regular maven command typicall like '**mvn clean install**' or '**mvn clean verify**' for example.


---

# 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/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/sealights-maven-plugin/advanced-features/capturing-unit-tests-ut-with-the-sealights-maven-plugin-delta-guide.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.