# ALTERNATIVE: Gradle Plugin

The **SeaLights Gradle plugin** is designed to wrap the entire SeaLights process into the Gradle lifecycle, allowing **seamless integration with the build tool**.

This solution uses the build scanner.jar file as well as a JSON configuration file. Once the jar is executed specifying the configuration file, the `build.gradle` files of the Gradle project are altered to incorporate the SeaLights plugin. This can be reversed using another CLI command.

## Prerequisites

* Automatic integration of Sealights settings into your *build.gradle* script is currently supported only for **Groovy** language.

## Implementation Steps

{% stepper %}
{% step %}

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

{% hint style="info" %}
Note: You will also need a valid SeaLights Agent Token, as explained in the [Prerequisites](/knowledgebase/phased-onboarding/java-onboarding-guide/getting-started/prerequisites.md)
{% endhint %}
{% endstep %}

{% step %}

#### Create a configuration file

This step allows you to set any necessary configuration in a dedicated configuration file, which will be used when adding the SeaLights Maven Plugin details to your project's `pom.xml`

**Example Configuration File:**

{% code overflow="wrap" %}

```json
{
  "tokenFile": "./sltoken.txt",
  "executionType": "testsonly",
  "testStage": "Functional Tests",
  "labId": "<test-env-id>",
  "runFunctionalTests": true,
  "createBuildSessionId": false,
}
```

{% endcode %}

**Minimum Required Parameters for this configuration:**

* `tokenfile` - Your SeaLights [agent token](/knowledgebase/phased-onboarding/java-onboarding-guide/getting-started/prerequisites.md#access-credentials) or path to token file
* `executionType` - Set to "testsonly"
* `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 test results in your SeaLights reports.
* `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.**
* `runFunctionalTests` - Set to true
* `createBuildSessionId` - Set to false

Additional optional parameters may be found here: [Java Plugin Configuration Parameters](/knowledgebase/phased-onboarding/java-agent-parameter-reference/java-agent-configuration-parameters/java-plugin-configuration-parameters.md)

{% hint style="warning" %}
Do NOT name this configuration file `sealights.json` as this is a reserved file name used by the agent for internal override options.
{% endhint %}

{% hint style="danger" %}
When using gradle on Windows, you will need to double the backslash used in path file for parameters like tokenFile, buildSessionIdFile and fileStorage - i.e. `tokenFile = "C:\\Sealights\\sltoken.txt"`
{% endhint %}
{% endstep %}

{% step %}

#### Add the plugin to your build.gradle

This step adds the SeaLights Gradle plugin, configured with the items specified in your config file, to your project's `build.gradle` . To accomplish this, you will use the command `java -jar sl-build-scanner.jar -gradle -configfile <config-file-name> -workspacepath <path>` 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`.

By doing this, you allow the SeaLights Gradle plugin to add the necessary SeaLights configuration to run with your test runner, without needing to update the JVM options at runtime.

**Minimum Required Parameters for this command:**

* `-configFile` - Path to the file containing the JSON configuration you created in Step 2.
* `-workspacepath` - The base path to the location of the pom.xml files to update

**Command:**

```bash
java -jar sl-build-scanner.jar -gradle \
-configFile /path/to/config/file.json \
-workspacepath "." 
```

What this command does:

* Creates a `sealights.gradle` script with all of the configuration taken from the JSON config file
* Updates your `build.gradle` with the SeaLights Gradle plugin and reference to the `sealights.gradle` script.&#x20;
* Creates a backup of your original `build.gradle` named `build.gradle.slback`

**Output:** In the console, you will see `[Sealights Build Scanner] - Successfully finished SeaLights integration`  if the command was successful.

{% endstep %}

{% step %}

#### Execute your tests with Gradle

Run your tests using the Gradle command you normally do (typically, something like `gradle clean test` )
{% endstep %}

{% step %}

#### Restore your gradle.build (OPTIONAL)

{% hint style="warning" %}
IF your workspace is not reset for each run, you will need to restore them at the end of the run&#x20;
{% endhint %}

Use the `-restore` flag to restore your pom.xml to its original content.

Command:

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

{% endstep %}
{% endstepper %}

#### 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 (ALTERNATIVE) 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 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/alternative-gradle-plugin.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.