Command Reference

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. (This ID must be under 40 characters length).
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
componentfile	A path to a json file that is in the following format: [{"appName":"","branch":"","build":""}, {...}] or [{"buildSessionId":"", {...}]
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' use comma separated file names or paths like "SpecificFileName1.class,specificFileName2.class" OR "some/sub/folder/*Test.class,another/folder/*/resources/*" Don’t use dot separated packages such as *.ms.*.gateways.mappers.implementation.MapResource.class
fi, filesincluded	Comma-separated list of files to include in scan Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.jar , use comma separated file names or paths like "SpecificFileName1.class,specificFileName2.class" OR "some/sub/folder/*Test.class,another/folder/*/resources/*" Don’t use dot separated packages such as *.ms.*.gateways.mappers.implementation.MapResource.class
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
componentfile	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
sl.calibrationLearning	(Optional) True/False. Passed as system property (e.g. java -Dsl.calibrationLearning=true -jar sl-test-listener.jar start ...) or via Env Var (SL_CALIBRATION_LEARNING=true) If set to true, the test runner marks the test run as a calibration execution (for TIA). Available from SeaLights agent v4.0.2610 Test Runners & Java Agent: Special Cases

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	(Optional) Path to the folder containing the artifact of the application, by default 'webapps'. If the property is provided, the agent looks recursively inside the .war and .ear files in the path defined by the property. The search stops on the first file found. This parameter is used when the agent does not find automatically the sltoken.txt and buildSessionId.txt files added to the artifact by Sealights Maven or Gradle plugins during the build.
sl.collectorUrl	http/https dns to the collector for when working with lambda methods

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. Both console output and file options are compatible and non-exclusive.

For logging into the console, add

-Dsl.log.toConsole=true -Dsl.log.level=info [--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED]

For logging into a file, add

-Dsl.log.toFile=true -Dsl.log.level=info -Dsl.log.folder=<path/with/permissions/> [--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED] [-Dsl.log.count=<value>] [-Dsl.log.limit=<arg>] [-Dsl.log.filename=<arg>]

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.* options above. If the option is not provided, the test listener will work as usual, but logging will not work.