# Running Tests (Only)

When executing Tests via Maven you do not need to provide the buildSessionId generated in a previous step via an environment variable or a text 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 %}

You can use the SeaLights agent to update your maven pom.xml with the needed changes to run your Maven build using the Maven Plugin

## Configuring the plugin using a JSON file <a href="#configuring-the-sealights-maven-plugin-using-a-json-file" id="configuring-the-sealights-maven-plugin-using-a-json-file"></a>

Create a JSON configuration file with the following parameters in order to provide the necessary configuration fields to the SeaLights Maven 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** - Provide which executions need to handled by the Maven plugin
   * **testsonly** - Execute only the test listener
4. **testStage** - Set the name of the test stage as will be displayed on the SeaLights dashboard

There are additional parameters you can provide

1. **labId** - (Optional) Unique ID for a set of test labs in case multiple labs are running simultaneously
2. **runFunctionalTests** - (Optional) 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. (ex. without this you may see an error like this: `[INFO] - [Sealights Maven Plugin] - Initializing failed; errors:[received build session data without 'packagesIncluded' ('additionalInfo'='null')]`).
3. **filesStorage** - (Optional)Set to the temp folder for the agent to create temporary files in. For example **/tmp**
4. **logEnabled** - (Optional) Set to **true** if you want a log to be created
5. **logLevel** - (Optional) Set the log level to create. For example **WARN** or **INFO**
6. **proxy** - (Optional) Address of proxy to run connection through
7. **sealightsJvmParams** - (Optional) Entry to provide JVM params to the SeaLights agent. It should be of the format {"key1":"val1", "key2":"val2"}

{% hint style="info" %}
See [#inlineextension-starting-a-test-stage](https://docs.sealights.io/knowledgebase/setup-and-configuration/java-agent/command-reference#inlineextension-starting-a-test-stage "mention") for more parameter values and information.
{% endhint %}

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

```javascript
{
  "tokenFile": "./sltoken.txt",
  "createBuildSessionId": false,
  "executionType": "testsonly",
  "testStage": "Functional Tests",
  "labId": "my_lab_id",
  "runFunctionalTests": true,
  "proxy": "",
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "warn",
  "sealightsJvmParams": {}
}
```

{% endcode %}

### Support for Special Use Cases <a href="#support-for-special-use-cases" id="support-for-special-use-cases"></a>

Additional parameters exist to support special use cases. You can learn about those:[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")

## Integrating into the pom.xml files <a href="#integrating-into-the-pom.xml-files" id="integrating-into-the-pom.xml-files"></a>

Before running your maven build, you run the build scanner with -pom flag to integrate the SeaLights Maven Plugin into the pom.xml files. This command will use the JSON configuration file defined above to inject Sealights plugin integration into the pom.xml settings.

The parameters it receives are:

* **configfile** - The path to the JSON configuration you created with the parameters to be provided to the SeaLights Maven Plugin
* **workspacepath** - The base path to the location of the pom.xml files to update

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

```
java -jar sl-build-scanner.jar -pom -configfile sealights-tests.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] - Pom integration was completed.`\
This step will update all the *pom.xml* files and back them up to *pom.xml.slback* copies in the same directory
{% endhint %}

{% hint style="warning" %}
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 Maven <a href="#executing-your-tests-with-maven" id="executing-your-tests-with-maven"></a>

You can use your regular maven command to execute your tests\
Typically the command is '**mvn clean install**' or '**maven clean verify**' for example.

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

{% hint style="info" %}
This script was tested in a Jenkins shell command prompt (*Freestyle* Job type) added prior to the mvn command of the tests.
{% 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`

#Replace the Token value below with the proper value from your Accounts settings
export SL_TOKEN="123"
echo $SL_TOKEN>sltoken.txt 

echo  '{ 
  "executionType": "testsonly",
  "tokenFile": "./sltoken.txt",
  "createBuildSessionId": false,
  "testStage": "Functional Tests",
  "runFunctionalTests": true,
  "labId": "my_lab_id",
  "proxy": null,
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "warn",
  "sealightsJvmParams": {}
  }' > slmaventests.json
 
echo "Adding Sealights to Tests Project POM file..."
java -jar sl-build-scanner.jar -pom -configfile slmaventests.json -workspacepath .
```

{% endcode %}

## Optional <a href="#optional" id="optional"></a>

### 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": "mytag"},
  ...
}
```

{% endcode %}

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

In case the pom file is to be restored to its previous state before the Sealights plugin was applied, use the build scanner with the -restore flag on the workspace where the *pom.xml* file is located:

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

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

{% endcode %}