# Running Tests (Only) (JSON file)

{% hint style="warning" %}
Please make sure the Sealights Test Listener is deployed to capture coverage of the application to be tested by this script.\
For Java application, you can refer to [installing-the-coverage-listener-as-a-jvm-java-agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/installing-the-coverage-listener-as-a-jvm-java-agent "mention")
{% endhint %}

SeaLights build scanner (sl-build-scanner.jar) can be used to update build.gradle script with the settings and enable its execution during the relevant Gradle projects.

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

Create a JSON configuration file with the following parameters in order 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. **createBuildSessionId** - Set to **false**
3. **executionType** - set to **testsonly** to execute only the test listener. This will appear as `runTestOnly=true` in the integrated gradle file.

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

```javascript
{
    "executionType":"testsonly",
    "tokenFile": "./sltoken.txt",
    "createBuildSessionId": false,
    "labId": "${System.getenv('LAB_ID')}",
    "filesStorage":"/tmp",
    "logEnabled":false,
    "logLevel":"off",
    "logToFile":false,
    "logToConsole":true,
    "proxy": null,
    "runFunctionalTests": true,
    "testTasksAndStages":{"test":"Functional Tests"},
    "testListenerJvmParams":{"sl.tags":"cucumber"}
}
```

{% endcode %}

The following optional parameters:

1. **logEnabled** - Set to **true** if you want a log to be created
2. **logLevel** - Set the log level to create. For example **WARN** or **INFO**
3. **logToFile** - Set to **true** if you want the log to written to a file
4. **logToConsole** - Set to **true** if you want the log to written to the console
5. **filesStorage** - location of temporary folder location to store cached agent files
6. **proxy** - Provide the URL to the proxy to route the calls through if needed
7. **labId** - Unique ID for a set of test labs in case multiple labs are running simultaneously
8. **runFunctionalTests** - Set to **true** to enforce partial validation of build. This is commonly used when the tested application is for example an *Integration Build* or a different technology than Java. In these cases, the Java packages included parameter will not be validated.
9. **testListenerJvmParams** - Containing an array of all the parameters you want to pass to all the SeaLights test execution step, Note: the key and values must always be strings
10. **testTasksAndStages** - A map of tasks and their test stage names to integrate SeaLights into the `jvmargs`. Default are `test`, `unitPlatformTest` with test stage "Unit Tests" and `integrationTest` with test stage "Integration Tests"

{% hint style="info" %}
For more parameters values and information, please refer to [#json-configuration-file-parameters](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/command-reference#json-configuration-file-parameters "mention")

Additional helpful configuration details can also be found: [test-runners-and-java-agent-special-cases](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/advanced-features/test-runners-and-java-agent-special-cases "mention")
{% endhint %}

{% hint style="warning" %}
When using gradle on Windows, you will need to double the backslash used in path file for parameters like tokenFile and fileStorage - i.e. `tokenFile = "C:\\Sealights\\sltoken.txt"`
{% 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`copie 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 %}

## Executing your tests with Gradle <a href="#executing-your-tests-with-gradle" id="executing-your-tests-with-gradle"></a>

You can use your regular gradle command to execute your tests.\
Typically the command is '**gradle clean test**' for example.

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