> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/sealights-gradle-plugin/advanced-features/scanning-builds-and-capturing-unit-tests.md).

# Scanning Builds & Capturing Unit Tests

SeaLights build scanner (sl-build-scanner.jar) can be used to update build.gradle script with the changes needed to run your Gradle build using SeaLights Gradle plugin in a similar fashion as for Maven plugin [Scanning Builds](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/sealights-maven-plugin/scanning-builds.md).

{% hint style="warning" %}
Automatic integration of Sealights settings into your *build.gradle* script is currently supported only for **Groovy** language.
{% endhint %}

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

Create a JSON configuration file with the following parameters to provide the necessary configuration fields to the SeaLights Gradle plugin:

1. **token** or **tokenFile** - set with a token or a file containing the token obtained from the SeaLights dashboard
2. If you create a Build Session ID externally, provide the following fields:
   1. **buildSessionId** or **buildSessionIdFile** - Set with a build session id or a file containing the build session id created by the config step
   2. **createBuildSessionId** - Set to **false**
3. If you want to create a Build Session ID using the SeaLights Gradle plugin, provide the following fields:
   1. **createBuildSessionId** - Set to **true**
   2. **appName** - Name of the application as you want to see it on the SeaLights dashboard
   3. **branchName** - Name of the branch as you want to see it on the SeaLights dashboard
   4. **buildName** - Name of the build as you want to see it on the SeaLights dashboard
   5. **packagesIncluded** - Comma-separated list of packages to include in the scan operation. Note: This is defining a subset, so it must include the star to include all sub-packages/classes
4. **executionType** - Provide which executions need to be handled by the Gradle plugin
   1. **full** - Execute both the build scanner and the test listener
   2. **scanonly** - Execute only the build scanner
5. **testTasksAndStages** - (Optional) Mapping of test tasks’ names to test stage names as they will be displayed on the SeaLights dashboard. It should be of the format {"testTask1":"testStage1", "testTask2":"testStage2"}
6. **proxy** - (Optional) Address of proxy to run connection through

{% hint style="info" %}
For additional parameters values and information, see [Command Reference](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/command-reference.md#installing-test-listener-as-java-agent) for more parameter values and information.
{% endhint %}

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

```javascript
{
  "executionType": "full",
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${System.getenv('JOB_NAME')}",
  "branchName": "master",
  "buildName": "${System.getenv('BUILD_NUMBER')}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "testTasksAndStages": {"test":"Unit Tests", "junitPlatformTest":"Unit Tests", "integrationTest":"Integration Tests"},
  "labId": null,
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "off",
  "logFolder": "/tmp",
  "gradleProjectConfig": {
    "excludedProjects": ["subProject1", "subProject2"],
    "repoConfig": "mavenLocal()"
  }
}
```

{% endcode %}

{% hint style="info" %}
The values provided for fields can contain interpolated Groovy code, just like for the field `appName` in the above example: `"${System.getenv('JOB_NAME')}"` .\
It will get resolved during the Gradle build.
{% endhint %}

{% hint style="warning" %}

* Do not call the JSON file 'sealights.json' as the agent uses this file name for override options
* For troubleshooting purpose, you can use `"buildName":"SL_Timestamp"` in your JSON file to have the Sealights Gplugin generating automatically a time stamp (yyyy.MM.dd-hh.mm format) as a default buildname
  {% endhint %}

## Integrating into the Build.gradle script <a href="#integrating-into-the-build.gradle-script" id="integrating-into-the-build.gradle-script"></a>

Before running your Gradle build, you run the build scanner with -gradle flag to integrate the SeaLights Gradle plugin into the build.gradle file. This will create a sealights.gradle script with all the configuration taken from the JSON config file and append a reference to it in build.gradle.

The standard parameters the build scanner receives are:

* **configfile** - The path to the JSON configuration you created with the parameters to be provided to the SeaLights Gradle plugin
* **workspacepath** - The base path to the location of the build.gradle file to update

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

```
java -jar sl-build-scanner.jar -gradle -configfile sl-config.json -workspacepath .
```

{% endcode %}

{% hint style="success" %}
At the successful completion of the command, you’ll see the following last line in the console:\
`[Sealights Build Scanner] - Successfully finished SeaLights integration.`
{% endhint %}

{% hint style="warning" %}
This step will update the root `build.gradle` file and back it up to `build.gradle.slback`copy in the same directory.\
If your workspace is not reset for each build, you will need to restore them at the end of the run (see command below).
{% endhint %}

**Next step** is to run your regular Gradle build command, e.g. **gradle clean build.**

## Restoring the build.gradle file to its previous state <a href="#restoring-the-build.gradle-file-to-its-previous-state" id="restoring-the-build.gradle-file-to-its-previous-state"></a>

In case the project is to be restored to its previous state before the SeaLights plugin was applied, use the build scanner with the `-restoreGradle` flag on the workspace where the `gradle.build` file is located:

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

```
java -jar sl-build-scanner.jar -restoreGradle -workspacepath .
```

{% endcode %}

This command will (1) restore gradle.build from backup, (2) delete the backup file, and (3) delete the sealights.gradle file.\
Failure at any of these steps won’t prevent the next ones, so that the project is restored as much as possible.

## Configuring SCM for Build Scan <a href="#configuring-scm-for-build-scan" id="configuring-scm-for-build-scan"></a>

SeaLights by default provides all links to the SCM for Github. You can configure SeaLights to prepare the links for Bitbucket and Gitlab as well with the following parameters placed under the sealightsJvmParams section:

* **sl.scm.provider** - set to **github, Bitbucket** or **gitlab**
* **sl.scm.baseUrl** - When working with an on-premise installation of your SCM and access from the build machine is different than the one accessed by the users, then you can provide the base URL to use
* **sl.scm.version** - set to the version of the on-premise version you use

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

```
"sealightsJvmParams": {
    "sl.scm.provider": "bitbucket",
    "sl.scm.baseUrl": "https://my.bitbucket.com/projects/ABCD/repos/XYZ/browse/A1",
    "sl.scm.version": "4.9.0"
}
```

{% endcode %}

## Pre-downloading the agents <a href="#pre-downloading-the-agents" id="pre-downloading-the-agents"></a>

The Gradle plugin downloads the recommended agent at the beginning of the run. If you want to pre-download them and provide them to the plugin, you can do so with the flags `scannerJar` & `listenerJar`.

{% hint style="info" %}
The agents referred here can be either the latest agent or the recommended one set in your account settings as stated in [Downloading The Java Agent](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/downloading-the-java-agent.md). They should be downloaded and made available **prior** to the Gradle execution.
{% endhint %}

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

```
"scannerJar": "./sl-build-scanner.jar"
"listenerJar": "./sl-test-listener.jar"
```

{% endcode %}

## Using a local repo <a href="#using-a-local-repo" id="using-a-local-repo"></a>

The Gradle plugin, by default, is downloaded from Maven Central. If you want to update the repo it downloads from, you can do so using the gradleProjectConfig->repoConfig option

{% hint style="info" %}
As repo configurations are usually multiline, its important to maintain this new line format using `\n`
{% endhint %}

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

```
"gradleProjectConfig": {"repoConfig": "maven{\nurl \"https://artifactory.company.com/artifactory/remote-repos\"\ncredentials {\nusername = \"USERNAME\"\npassword = \"PASSWORD\"\n}\n}"}
```

{% endcode %}

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

{% hint style="info" %}
This script is very often added to a new pre-build step in your CI configuration (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": "scanonly",
    "tokenFile": "sltoken.txt", 
    "createBuildSessionId": true,
    "appName": "${System.getenv(\"JOB_NAME\")}",   
    "branchName": "${System.getenv(\"GIT_BRANCH\")}",
    "buildName": "SL_Timestamp",
    "packagesIncluded": "*com.example.*",   
    "packagesExcluded": "",
    "filesIncluded": "*.class",
    "filesExcluded": "*test-classes*",
    "recursive": true,
    "includeResources": true,
    "proxy": null,
    "logEnabled": false,
    "logDestination": "console",
    "logLevel": "off",
    "logFolder": "/tmp"
  }' > sl-config.json
 
echo "Updating Build.gradle with Sealights..."
java -jar sl-build-scanner.jar -gradle -configfile sl-config.json -workspacepath .
```

{% endcode %}

**Next step** is to run your regular Gradle build command, e.g. **gradle clean build.**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/sealights-gradle-plugin/advanced-features/scanning-builds-and-capturing-unit-tests.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.