Agent Files
There are two agent files
Build Scanner - sl-build-scanner.jar
Test Listener - sl-test-listener.jar
Download them from: https://agents.sealights.co/sealights-java/sealights-java-latest.zip
Build Scanner
Creating a session ID
Standard Session ID
java -jar sl-build-scanner.jar -config {-token <arg> | -tokenfile <arg>} -appname <arg> -branchname <arg> -buildname <arg> -pi <arg> [-pe <arg>] [-buildsessionid <arg>] [-proxy <arg>] [-buildsessionidfile <arg>]
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing access token generated from the SeaLights server |
appname | Name of the application |
branchname | The source branch of the application |
buildname | The build label of the current build |
pi, packagesincluded | Comma-separated list of packages to include in scan Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world' |
pe,packagesexcluded | Comma-separated list of packages to exclude from scan Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world' |
buildsessionid | Optional: A user provided session ID |
proxy | Address of proxy to run connection through |
| buildsessionidfile | Path to a file to save the build session id in. Default: buildSessionId.txt |
Pull Request Session ID
java -jar sl-build-scanner.jar -prConfig {-token <arg> | -tokenfile <arg>} -appname <arg> -targetBranch <arg> -latestCommit <arg> -pullRequestNumber <arg> -repoUrl <arg> -pi <arg> [-pe <arg>] [-proxy <arg>] [-buildsessionidfile <arg>]
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing access token generated from the SeaLights server |
appname | Name of the application |
targetBranch | The branch to which this PR will be merged into (already reported to SeaLights) |
latestCommit | The full SHA of the last commit made to the Pull Request |
pullRequestNumber | The number assigned to the Pull Request from the source control |
repoUrl | The pull request URL for the PR to be scanned, up until the section before the pullRequestNumber value |
pi, packagesincluded | Comma-separated list of packages to include in scan Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world' |
pe,packagesexcluded | Comma-separated list of packages to exclude from scan Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world' |
proxy | Address of proxy to run connection through |
| buildsessionidfile | Path to a file to save the build session id in. Default: buildSessionId.txt |
Scanning a build
java -jar sl-build-scanner.jar -scan {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} [-workspacepath <arg>] [-r] [-baseSourceFolder <arg>] [-componentfile <arg>] [-enableNoneZeroErrorCode] [-fe <arg>] [-fi <arg>] [-moduleName <arg>] [-npf | -pfn <arg>] [-pathToMetaJson <arg>] [-proxy <arg>] [-scmProvider <arg>] [-scmBaseUrl <arg>] [-scmVersion <arg>] [-scm {git|none}] [-customFilterFile <arg>]
| Parameter | Description |
|---|---|
| token | Access token generated from the SeaLights server |
| tokenfile | Path to file containing the access token generated from the SeaLights server |
| buildsessionid | Session ID of configuration created |
| buildsessionidfile | Path to file containing the Session ID of configuration created |
| workspacepath | Path to the source workspace |
r, recursive | Recursive search all folders under the workspace path |
baseSourceFolder | Relative path from user.dir to the workspace (specify the relative path from the .git folder up to com) Example: src/java |
| A path to a json file that is in the following format: |
enableNoneZeroErrorCode | Exit with an error code if an error is encountered |
fe, filesexcluded | Comma-separated list of files to exclude from scan Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.jar , bad-bad?.war, *-source.jar' |
fi, filesincluded | Comma-separated list of files to include in scan Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.jar , |
moduleName | Module name, the module name used in the pom.xml file Example: my-app |
npf, noPropertiesFile | Do not generate Sealights property file |
pfn, propertiesFileName | Path of Sealights property file to generate. Default is 'sealights.properties' |
pathToMetaJson | Optional: Path to a json file with metadata regarding the build |
proxy | Address of proxy to run connection through |
| scmProvider | The provider name of your Source Control Management (SCM) tool. Values: Github, Bitbucket and Gitlab (Default is Github) |
| scmBaseUrl | The URL to the repository which contains the code. If not provided, the url of the remote GIT origin will be used |
| scmVersion | The version of your Source Control Management (SCM) tool. If not provided, cloud version is assumed |
| scm | Search for git information Values: git, none (Default is git) |
| customFilterFile | Path to JSON format method filter rules file, format described here |
Report build scan end
java -jar sl-build-scanner.jar -buildend {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} {-failed | -ok}
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing the access token generated from the SeaLights server |
buildsessionid | Session ID of configuration created |
buildsessionidfile | Path to file containing the Session ID of configuration created |
ok | report the build scan was successful |
| failed | report the build scan was failed |
| proxy | Address of proxy to run connection through |
Updating/Deleting a component from an integration build
java -jar sl-build-scanner.jar {-componentUpdate | -componentDelete} {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} {-componentids <arg> | -componentfile <file>}
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing the access token generated from the SeaLights server |
buildsessionid | Session ID of configuration created for the integration build |
buildsessionidfile | Path to file containing the Session ID of configuration created for the integration build |
componentids | One or several build session ID's (comma separated) of the component(s) to be updated or deleted |
| A path to a json file that is in the following format: [{"appName":"","branch":"","build":""}, {...}] or [{"buildSessionId":"", {...}] |
| proxy | Address of proxy to run connection through |
Test Listener
Starting a test stage
java -jar sl-test-listener.jar start {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} -testStage <arg> [-labid <arg>] [-proxy <arg>]
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing the access token generated from the SeaLights server |
buildsessionid | Session ID of configuration created |
buildsessionidfile | Path to file containing the Session ID of configuration created |
testStage | Name of the test stage |
labid | Unique ID for a set of test labs in case multiple labs are running simultaneously |
proxy | Address of proxy to run connection through |
Upload report files
Report files must be junit style xml reports
java -jar sl-test-listener.jar uploadReports {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} {-reportFile <arg>|-reportFilesFolder <arg>} -source <arg> -type <arg> [-labid <arg>] [-proxy <arg>]
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing the access token generated from the SeaLights server |
buildsessionid | Session ID of configuration created |
buildsessionidfile | Path to file containing the Session ID of configuration created |
reportFile | Path to report file (multiple entries can be provided) |
reportFilesFolder | Path to folder containing report files (multiple entries can be provided) Note: all files in the folder will be uploaded |
source | The reports provider Example: Junit xml report |
| type | Values: JUnitReport - For uploading JUnit test report files commitLog - For uploading git style commit logs |
labid | Unique ID for a set of test labs in case multiple labs are running simultaneously |
proxy | Address of proxy to run connection through |
Ending a test stage
java -jar sl-test-listener.jar end {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} [-labid <arg>] [-proxy <arg>]
| Parameter | Description |
|---|---|
token | Access token generated from the SeaLights server |
tokenfile | Path to file containing the access token generated from the SeaLights server |
buildsessionid | Session ID of configuration created |
buildsessionidfile | Path to file containing the Session ID of configuration created |
labid | Unique ID for a set of test labs in case multiple labs are running simultaneously |
proxy | Address of proxy to run connection through |
Installing test listener as Java Agent
The listener needs to be placed alongside the server and added to the JVM command line using the -javaagent parameter together with its required parameters.
Usually the easiest is to place it in the JAVA_OPTS="..." although it can also be placed in the JVM command itself.
java -javaagent:/path/to/sl-test-listener.jar {-Dsl.token=<arg> | -Dsl.tokenFile=<arg>} {-Dsl.buildSessionId=<arg> | -Dsl.buildSessionIdFile=<arg>} [-Dsl.tags=<arg>] [-Dsl.labId=<arg>] [-Dsl.proxy=<arg>] [-Dsl.testStage=<arg>] [-Dsl.filesStorage=<folder>] [-Dsl.webappLocation=<arg>] -jar yourapp.jar
| Parameter | Description |
|---|---|
javaagent | Path to Sealights Java test agent jar |
sl.token | Access token generated from the SeaLights server |
sl.tokenFile | Path to file containing the access token generated from the SeaLights server |
sl.buildSessionId | Session ID of configuration created |
sl.buildSessionIdFile | Path to file containing the Session ID of configuration created |
sl.tags | One or several tags (comma separated) to be passed to Sealights in order to label the test listener in the cockpit |
sl.labId | Unique ID for a set of test labs in case multiple labs are running simultaneously |
sl.proxy | Address of proxy to run connection through |
sl.testStage | Name of the test stage (When running with JMeter) |
sl.filesStorage | Path to a folder that the agent can save temporary files to |
sl.webappLocation | Location of the webapps folder to search for the artifcat in, by defaule 'webapps' |
Logging
In order to enable logs you can set the following parameters as environment variables or when using as javaagent add them as -Dsl.* parameters
| Parameter | Description |
|---|---|
sl.log.level | Sets the log level to one of the following: "off", "error", "warn", "info", "debug" |
sl.log.toConsole | Set to true to enable log output to the console |
sl.log.toFile | Set to true to enable log output to a file |
sl.log.folder | Provide a folder to save the log files in |
sl.log.filename | Provide the name of the log file |
sl.log.count | Limit the number of log files to create. Default: 10 |
sl.log.limit | Limit the size of the log file in megabytes (MB). Default value is 10 (i.e. 10*1024 KB) |
--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED | Special JVM parameter to allow logging in Java 9 and later in addition to -Dsl.log.* above. |