Agent File

Our Node.js agents (slnodejs) are published in the npm registry. You download it and all its dependencies using the npm repository commands.

Downloading latest version

npm i slnodejs

Downloading the recommended version by Sealights (Best Practice)

For Customers that need to set a specific recommended agent version other than the default latest, the API will provide the recommended agent version that has been set on the dedicated settings page from the dashboard.

In the following examples, replace $DOMAIN with your domain and $SL_TOKEN with your SeaLights agent token

Linux

# Fetch Agent version defined in Sealights dashboard settings 
$SLVERSION=$(curl -X GET "https://$DOMAIN.sealights.co/api/v2/agents/slnodejs/recommended" -H "accept: application/json" -H "Authorization: Bearer $SL_TOKEN" -L)
# Install Sealights Agent (Recommended version)
npm i slnodejs@$SLVERSION

PowerShell

# Fetch Agent version defined in Sealights dashboard settings 
$SLVERSION = Invoke-RestMethod -Uri "https://$DOMAIN.sealights.co/api/v2/agents/slnodejs/recommended" -Headers @{ "accept" = "application/json", "Authorization" = "Bearer $SL_TOKEN"}
# Install Sealights Agent (Recommended version)
npm i "slnodejs@$SLVERSION"

GitLab YML

  before_script:
    - apt-get -qq update && apt-get install -y jq
  script:
    - |
      SLVERSION=$(curl -X GET "https://$DOMAIN.sealights.co/api/v2/agents/slnodejs/recommended" -H "accept: application/json" -H "Authorization: Bearer $SL_TOKEN" -L  | jq -r .agent.version )
      npm install slnodejs@$SLVERSION

Configure a session and create session ID

./node_modules/.bin/slnodejs config {--token <token> | --tokenfile <file>} --appname <appname> --branch <branch> --build <build> [--buildsessionid <buildsessionid>] [--proxy <proxy>] [--failbuild {true|false}]

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
`branch`	The source branch of the application
`build`	The build label of the current build
`buildsessionid`	(Optional) A user provided session ID
`proxy`	Address of proxy to run connection through
`failbuild`	Exit with an error code if an error is encountered (Default: `false`)

Scanning a build

./node_modules/.bin/slnodejs build {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} --workspacepath <workspacepath>  --scm {git|none} [--projectRoot <folder>] [--excludedpaths <excludedpaths>] [--uniqueModuleId <id>] [--es-modules] [--jobName <jobName>] [--logsUrl <logsUrl>] [--dependenciesFile <dependenciesFile>] [--instrumentForBrowsers --outputpath <folder> [--downloadAgent {true|false}] [--instrumentationOnly] [--labid <labid>]] [--proxy <proxy>] [--failbuild {true|false}] [--scmBaseUrl --scmProvider {github|gitlab|bitbucket} --scmVersion] [--es6Modules] [--babylonPlugins decorators-legacy|jsx]

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`excludedpaths`	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'`
`projectRoot`	Path to the root of the project. Usually where the src folder resides
`uniqueModuleId`	Unique name when providing more than one build scan per build
`es6Modules`	Indicates that you use es6 modules
`jobName`	Name of Jenkins job
`logsUrl`	Path to Jenkins log folder
`scm`	Source control used. Current options are: `git`, `none`
`dependenciesFile`	A path to a JSON file that is in the following format: `[{"appName":"","branch":"","build":""}, {...}]`
`instrumentForBrowsers`	Instrument the JS files for providing browser front-end coverage information. Must be used with the `outputpath` parameter.
`downloadAgent`	Set this value to '`false`' in order to prevent the instrumented javascript to try and download the browser test listener (for example, when using 'Karma').
`instrumentationOnly`	Only instrument the javascript files, without sending the build information to the SeaLights server (i.e. skip the build scan). This parameter must be used in addition to the `instrumentForBrowsers` parameter.
`outputpath`	Folder to generate the instrumented JS files in when using the `instrumentForBrowsers` parameter
`labid`	Unique ID for a set of test labs in case multiple labs are running simultaneously or for an integration build. This needs to be done during the instrumentation process when using the `instrumentForBrowsers` option
`proxy`	Address of proxy to run connection through
`failbuild`	Exit with an error code if an error is encountered (Default: `false`)
`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 Example: `https://my.bitbucket.com/projects/ABCD/repos/XYZ/browse/A1`
`scmVersion`	The version of your Source Control Management (SCM) tool. If not provided, Cloud version is assumed
`babylonPlugins`	Values: `decorators-legacy` - When there are decorators in the code, you should use this flag with the "decorators-legacy" value `jsx` - For React applications

Ending a multi module build

./node_modules/.bin/slnodejs buildend {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} [--proxy <proxy>] [--failbuild {true|false}] [--skipUpgrade {true|false}] --ok | --failed

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing access token generated from the SeaLights server
`buildsessionid`	Session ID of configuration created
`buildsessionidfile`	Path to file containing the Session ID of configuration created
`proxy`	Address of proxy to run connection through
`failbuild`	Exit with an error code if an error is encountered (Default: `false`)
`skipUpgrade`	Should not try to upgrade agent (Default: `false`)
`ok`	build finished successfully
`failed`	build not finished successfully

Updating/Deleting a component from an Integration build

./node_modules/.bin/slnodejs {componentUpdate | componentDelete} {-token  <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} [--proxy <proxy>] {-componentIds <arg> | -componentFile <file>}

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing access token generated from the SeaLights server
`buildsessionid`	Session ID of configuration created
`buildsessionidfile`	Path to file containing the Session ID of configuration created
`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

./node_modules/.bin/slnodejs start {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} --teststage <teststage> [--labid <labid>] [--proxy <proxy>] [--failbuild {true|false}]

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`failbuild`	Exit with an error code if an error is encountered (Default: false)

Upload report files

Report files must be junit style xml reports

./node_modules/.bin/slnodejs uploadReports {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} {--reportFile <reportFile> | --reportFilesFolder <reportFilesFolder>} [--labid <labid>] [--source <source>] [--type <type>] [--proxy <proxy>] [--failbuild {true|false}]

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`labid`	Unique ID for a set of test labs in case multiple labs are running simultaneously
`source`	The reports provider. Default: `Junit xml report`
`type`	Values: `JUnitReport` - For uploading JUnit test report files `commitLog` - For uploading git style commit logs
`type`	Name of testing framework type
`proxy`	Address of proxy to run connection through
`failbuild`	Exit with an error code if an error is encountered (Default: `false`)

Optional override parameters:

Parameter	Description
`appname`	Name of the application
`branch`	The source branch of the application
`build`	The build label of the current build

Upload Coverage files

Coverage file must be in JSON format, created by the Istanbul framework

./node_modules/.bin/slnodejs nycReport {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} {--report <reportFile> | --projectRoot <project root dir>} [--labid <labid>] [--proxy <proxy>]

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing access token generated from the SeaLights server
`buildsessionid`	Session ID of configuration created
`buildsessionidfile`	Path to file containing the Session ID of configuration created
`report`	Path to coverage-final.json
`projectRoot`	Path to the root of the project. Usually where the src folder resides
`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

./node_modules/.bin/slnodejs end {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} [--labid <labid>] [--proxy <proxy>] [--failbuild {true|false}]

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`failbuild`	Exit with an error code if an error is encountered (Default: false)

Running Tests using Mocha

./node_modules/.bin/slnodejs mocha {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} --teststage <teststage> [--labid <labid>] [--proxy <proxy>] [--failbuild {true|false}] -- args...

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`failbuild`	Exit with an error code if an error is encountered (Default: false)
`-- args...`	Extra arguments for running mocha framework tests Note: the double dash delimits between the SeaLights agent options and parameters passed to mocha

Running Tests using jasmine-node

./node_modules/.bin/slnodejs jasmine {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} --teststage <teststage> [--labid <labid>] [--proxy <proxy>] [--failbuild {true|false}] args...

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`failbuild`	Exit with an error code if an error is encountered (Default: false)
`args...`	Extra arguments for running mocha framework tests

Running backend server

./node_modules/.bin/slnodejs run {--token  <token> | --tokenfile <file>} {--buildsessionid <id> | --buildsessionidfile <file>} [--workspacepath <path>] [--useinitialcolor {true|false}] [--teststage <teststage>] [--labid <labid>] [--proxy <proxy>] [--failbuild {true|false}] args...

Example of command:

./node_modules/.bin/slnodejs run --tokenfile ./sltoken.txt --buildsessionidfile buildSessionId --labid "LAB_ID_2" --workspacepath "./server" --useinitialcolor true --useslnode2 -- "./server/app.js"

Note the /your/backend/server/command refers to "./server/app.js" in the above example.

Parameter	Description
`token`	Access token generated from the SeaLights server
`tokenfile`	Path to file containing 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
`useinitialcolor`	When reporting tests manually this should be set to false (Default: false)
`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
`failbuild`	Exit with an error code if an error is encountered (Default: false)
`args...`	Extra arguments for running mocha framework tests

Logging

To enable logs, you can set the NODE_DEBUG environment variable to a value defining the output per the table below:

export NODE_DEBUG=sl

Value	Description
`sl`	Display log output to the console
`sl-file`	Export the log information to a log file named '`sl.node.log`'

Furthermore, you can set the logging level by using the SL_LOG_LEVEL environment variable with one of the following options: info (default) or debug.

export NODE_DEBUG=sl
export SL_LOG_LEVEL=debug

To disable logs, unset the NODE_DEBUG variable.

export NODE_DEBUG=

The above examples are for Linux shells; for Windows CMD prompt, use the set command.

SeaLights Node.js agent - Command Reference