The dryRun command allows to validate and fix configuration errors in order to have a shorter configuration cycle. Please follow the commands in the right order in order to progress step-by-step.

The dryRun command allows you to accelerate the setup of your project integration with Sealights by removing the dependency on new build for every scan and shortening significantly every iteration of troubleshooting steps.

The dryRun command DOES NOT replace integration with your CI but accelerates the integration of your Node.JS project with Sealights. It only creates a local report and does not send any data to Sealights servers.

Prerequisites

Please make sure the slnodejs agent is properly installed as described in https://sealights.atlassian.net/wiki/spaces/SUP/pages/3473605.
For any front-end Javascript application minified and/or uglified as part of its build process, you’ll need to ensure the Source Map files (*.js.map) are available to Sealights agent inside the application folder - next to the application’s JS files -, pointing to the right source folder and including column information (also known as column-mapping). This will allow Sealights agent to retrieve the real names of your methods from your source code and not their “obfuscated” version. Please refer to the following page for more information: https://sealights.atlassian.net/wiki/spaces/SUP/pages/1172144129.

Running the dryRun command

The dryRun command runs locally and does not require token nor build session ID but has 2 mandatory parameters required

workspacepath should provide the folder containing the final JS files of your build (e.g. dist folder)
scm should pass git value by default or none otherwise

Unix:
./node_modules/.bin/slnodejs dryRun --verbose --instrumentForBrowsers --workspacepath "./dist" --scm git 
 
Windows:
call .\node_modules\.bin\slnodejs dryRun --verbose --instrumentForBrowsers --workspacepath ".\dist" --scm git

If Unit Tests are in scope, you can process and validate their resulting JSON coverage files via the dryRun command using the following parameters

./node_modules/.bin/slnodejs dryRun --verbose --instrumentForBrowsers --workspacepath "./dist" --scm git --hasNycReport --report ./report/coverage-final.json

A successful command will result with:

the number of scanned methods, branches, and files from the build
a table summarizing the status of different aspects of your project
the creation of an sl-dry-run-output folder containing several files allowing you to analyze your project configuration

Below is a sample of a successful scan with a single warning

Analysis completed, found the following:
┌─────────────────────────────────────────────────────────────────────────────────┬─────────────────────────┬──────────────────────────────┐
│Name                                                                             │Status                   │Message                       │
├─────────────────────────────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Column information                                                               │ok                       │                              │
├─────────────────────────────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Git paths                                                                        │ok                       │                              │
├─────────────────────────────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Raw third party                                                                  │ok                       │                              │
├─────────────────────────────────────────────────────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│Logical third party                                                              │ok                       │                              │
└─────────────────────────────────────────────────────────────────────────────────┴─────────────────────────┴──────────────────────────────┘
 1 warnings or error has found. For more information please see sl-dry-run-output/agent-events.json

All the details of the analysis (including errors and warnings) and agent logs are exported into dedicated files under sl-dry-run-output folder, to allow you to refine the configuration of your SeaLights' slnodejs agent commands.

Analyzing the command results

As a best practice, we recommend going through the following steps based on the dryRun command insights:

Reduce the scope of files analyzed to the files maintained by your developers in the SCM and exclude third-party and framework automatically-generated files.
Fix any issues detected with the source map files
Resole any Git related issue
Resolve any Unit Test related issue

The sections below are going over these recommendations in this order.

Defining the right project scope (Files to exclude)

Excluding irrelevant files and folders will optimize the slnodejs commands and reduce their duration to optimize your CI jobs.
In order to identify what are the files analyzed by the SeaLights agents, you’ll need to review the content of two files:

sl-dry-run-output/included-files.json: list of files analyzed and instrumented by the agent and included in the project scope.
sl-dry-run-output/excluded-files.json: list of files excluded by the agent - automatically or explicitly excluded in parameters and/or ignore files. These files are not scanned nor instrumented.

After identifying the list of relevant files, you can define or update the content of .slignore and .slignore.generated files and execute again the dryRun command until you are satisfied with the project files in-scope.

Source Map Files Content Validity

If your front-end Javascript application is minified and/or uglified as part of its build process, you’ll need to ensure the Source Map files (*.js.map) are available to the Sealights agent inside the application folder - next to the application’s final JS files (the ones deployed). The content of these files needs to point to the right source folder and including line and column information (also known as column mapping).

This will allow Sealights agent to retrieve the real names of your methods from your source code and not their “obfuscated” version.

In order to check the validity of the source map files analyzed by the agent, you can open the file sl-dry-run-output/sl-mapping.json, and confirm the right part of every line is a reference to an existing file of the source code of the application in the SCM. Otherwise, you’ll need to revisit the parameters of the source map files generation during the build.

Remediating issues highlighted in the table summary

If the agent identifies a potential issue related to the project configuration, the summary table will highlight it with a failed status and one (or more) message to suggest potential remediation.
The following table is suggesting a potential mapping between the issues highlighted in the summary and your configuration:

Item	Invalid Source Map Files Content	Paths/Parameters used in command	Comment

Item	Invalid Source Map Files Content	Paths/Parameters used in command	Comment
Column information			Source Map files found in the workspace directory (e.g. `dist` folder) must include both the line and column information. When the agent does not detect the column information, this validation fails. Please refer to https://sealights.atlassian.net/wiki/spaces/SUP/pages/1172144129.
Git Paths			The project structure calculated by the build scanner does not match your git project structure (retrieved from your .git folder) from please check the provided `buildScanProjectRoot` and update it in order to align git and Sealights' agent configurations.
Raw Third Parties			Several files from frameworks/3rd parties (like Angular files) were detected during the scan operation, it may impact the command duration (with unnecessary files processed) and the coverage results. Please make sure the right paths are passed to the agent and proper files/folders exclusions are defined (more specifically in the `.slignore` file). You can refer to the following article for more details:
Logical Third Parties			Source Map files are pointing to files which are not maintained/developed in your project (like Angular or Webpack files), it may impact the command duration (with unnecessary files processed) and the coverage results. Please make sure the right paths are passed to the agent and proper files/folders exclusions are defined (more specifically in the `.slignore.generated` file). You can refer to the following article for more details:
Nyc Paths (optional)			The NYC/Istanbul coverage report file includes different methods paths and signatures than the ones generated by the Sealights agent. This may lead to missing coverage in one or several Test stages. Please validate the provided `buildScanProjectRoot` and/or `nycProjectRoot` parameters.
Position Match (optional)			There was a misalignment >= 30% in methods and branches positons detected between the NYC report file content and the ones generated by SeaLights agent. This may lead to inconsistent/low coverage in one or several Test stages. Please verify the same baseline of source code is defined as the scope of both analysis for NYC coverage report and Sealights scan (same configuration in use).

Command Reference & Mapping

Parameter	Description	Regular slnodejs command equivalent

Parameter	Description	Regular slnodejs command equivalent
`verbose`	Prints additional information to the console output of command summary (default: false)
`folderDepth`	Folder depth for printing unique ids in dry run command. (default: 3)
`usebranchcoverage`	Flag indicating whether or not to collect branch coverage. (default: true)
`help`	outputs the help in console and exits.
Build Scanning validation
`workspacepath`	Path to the workspace where the source code exists	Same parameter in `build` command
`scm`	Source control used. Current options are: `git`, `none`	Same parameter in `build` command
`instrumentForBrowsers`	Use this in order to instrument the javascript for working with the browser test listener. (default: false)	Same parameter in `build` command
`es6Modules`	Use ES6 'module' mode when scanning files. (default: false)	Same parameter in `build` command
`babylonPlugins`	List of non default babylon parser plugins, separated by comma: `decorators-legacy` - When there are decorators in the code, you should use this flag with the "decorators-legacy" value `jsx` - For React applications (List of plugins: https://babeljs.io/docs/en/plugins/ )	Same parameter in `build` command
`excludedpaths`	Comma-separated list of excluded paths glob strings, in the form of `'public/*/.js,files/*/.js'`	Same parameter in `build` command
`outputpath`	Optional: output path for instrumentation.	Same parameter in `build` command
`buildScanProjectRoot`	Determine the root directory of project where the original source files (resolved by Source Map files are located). Default is current working directory applied for build scanner	`projectRoot` parameter in `build` command
Unit Test Coverage validation
`hasNycReport`	Activates Unit Tests coverage analysis for NYC coverage report in JSON format. (default: false)	`nycReport` command itself.
`nycProjectRoot`	Determine the root directory of project, default is current working directory applied for `nycReport`	`projectRoot` parameter in `nycReport` command
`report`	Path to the relevant NYC JSON report. (default: `<current working directory>/coverage/coverage-final.json`)	Same parameter in `nycReport` command

Troubleshooting common errors

In case of an error similar to ‘Failure during instrumentation' found in the agent’s log, please make sure the right project configuration details are passed as relevant flags

For applications using es6 modules, please add the --es6Modules flag.
For React applications, you should add the flag: --babylonPlugins jsx

Support

Sealights Node.js agent - dryRun command for troubleshooting and validation