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