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 Downloading the Node.js agent file.

  • 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 and 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

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
BASH

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
BASH

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

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
TEXT

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:

  1. 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.

  2. Fix any issues detected with the source map files

  3. Resole any Git related issue

  4. 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 https://sealights.atlassian.net/l/c/n6GuFwok

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

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 and 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: Using Node.js Agent - 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: Using Node.js Agent - 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

./node_modules/.bin/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]
BASH

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

See 'Node.js Command Reference' for full parameter details

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