dryRun Command: Troubleshooting & Validation

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 a new build for every scan and significantly shortening 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 Downloading the Node.js Agent.
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: Javascript & Node.js Source Map Files.

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

npx slnodejs dryRun --verbose --instrumentForBrowsers --workspacepath "./dist" --scm git

call npx 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

npx 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

For "JavaScript heap out of memory" errors while running dryRun, see: NodeJS - JavaScript heap out of memory

In case the agent detected a misconfiguration, it will provide insights and recommendations in the Message column.

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.

In order to ignore specific files or folders during the Scan operation, please refer to Ignoring Files or Folders

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.

Please refer to the following page for more information: Javascript & Node.js Source Map Files

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 suggests 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

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 Javascript & Node.js Source Map Files.

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: Ignoring Files or Folders.

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: Ignoring Files or Folders

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

npx slnodejs dryRun --workspacepath <workspacepath> [--help] --scm {git|none} [--verbose] [--buildScanProjectRoot <project root folder>] [--hasNycReport {--nycProjectRoot <path to nyc project folder> | --report <full path to NYC report file>}] [--instrumentForBrowsers] [--es6Modules] [--babylonPlugins {jsx| decorators-legacy}] [--folderDepth <depth value>] [--excludedpaths <list of paths>] [--outputpath <output path for SL agent>] [--usebranchcoverage]

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