JSHint and the ServiceNow Platform - Support and Troubleshooting

JSHint and the ServiceNow Platform Issue  Overview The ServiceNow platform uses an embedded tool called jshint to detect potential errors and violations of coding standards in JavaScript used within various forms and objects in a ServiceNow instance.

This tool can sometimes generate messages or other unexpected results in the JavaScript editor window which might be confusing to someone unfamiliar with the JSHint tool. In addition, there are a number of useful options that can be specified to customize use of the tool within the scripting field or object.

Background In the majority of cases, most customers will be unaware that the jshint tool is being used in ServiceNow scripting objects. It's use will usually be noticed when messages appear in the error bar at the left of the script field. This tool is what generates many of the error messages that are indicated in the information bar to the left of the actual script test.This will usually appear as a series of warning or error icons which can be hovered over and which will display various warnings and messages. This may appear as an error message in the error bar similar to the following (with XX replaced with some whole number equal to or less than 100 indicating how far through the script the tool reached before hitting its pre-configured threshold):

Too many errors (XX% scanned).

While most of the errors or warning are self-evident and can be rectified in the script based on the text, it is sometimes helpful to know some of the common warning types that the tool may be configured to detect and report on.

Specifics The JSHint tool has a number of configurable settings. While the general configuration of the tool as used in the ServiceNow environment is normally inaccessible, there are certain configurations and settings that can be configured directly in the script itself to modify the behavior of the tool and some of the specific coding standards it will check for and detect in the script.

The tool is designed to analyze JavaScript code and detect a number of statements and potential issues in the JavaScript code. While these statements are not necessarily errors or bad coding practice, they are statements that can be prone to errors and may be confusing to others reviewing the script.

The problem arises in cases in which these warnings are invisible to the end user. This can occur for a number of reasons, but the most common is in the case in which the tool has reached the configured threshold of errors it will detect. Once it reaches this point, it will generate the "Too many errors." message (see the image above) and no further errors will be indicated on the information bar to the left of the script. In these cases particularly, it may be helpful to know some of the common warning messages the tool will detect and methods to suppress certain warning types (through directives, described in the Directives section below).

There are two types of messages that will generally appear in the message bar, errors or warnings. Errors are indicated by a red X icon while warnings by a yellow exclamation icon. Hovering the mouse over the icon in the information bar will usually display a very brief description of the error or warning message. If the script contains any errors, the platform will not allow the script object to be saved, while having only warnings detected will not prevent the script from being saved. Note that the Too many errors message appears with the error icon, but if all the issues that caused the tool to reach this threshold were solely warnings, the script can still be saved.

While many of the the warnings the tool is configured to detect are not necessarily errors in themselves, it does point out statements and other code constructs that may violate best coding practices in the JavaScript language which probably should be reviewed by the author of the object.

While the tool, as used in the ServiceNow platform environment is configured to detect and report a number of these issues, the following are some of the most common things that may cause the tool to flag a warning on an end-users script:

Equality Operators (== and !=)

The tool is often configured to detect uses of the JavaScript operators (== and !=). Because these operators are known to sometimes enforce coercion of the operands which could leading to a possible unexpected modification of the value in these operands). Because of this the JSHint tool prefers the usage of the === or !=== version of these operators instead. Thus, the JSHint tool will flag an error or warning each time it comes across usage of the == or != operators. See below for a directive that can be used to suppress detection of this operator in a specific scripting object.

Single Statement Blocks

The JavaScript language will generally allow a code block, which consists of just a single line to have the enclosing curly braces { and } omitted. However, this can lead to confusion and lack of clarity as to what statements are actually intended to be within the block. As such, the the JSHint tool usually prefers the use of curly braces around any block of code, regardless of the number of lines and as such, may detect and generate a warning when it detects blocks of code which do not contain these enclosing braces. See the list of directives below for a directive that can be used to suppress detection of this issue.

Missing Semicolons (;)

In most cases, JavaScript code will continue to work with no issues when the trailing semi-colon is omitted. However, this can be confusing and lead to a lack of consistency in code amongst multiple objects. Due to this, the JSHint tool is configured by default in the ServiceNow environment to detect for lines in the script which are missing this trailing semi-colon. A directive is provided by the tool which will allow these missing semi-colons to be ignored in the current scripting object.

Compare to null ( == null)

Comparison to the value null in JavaScript, while valid syntax, can sometimes cause errors or invalid comparisons in a script. As such, the JSHint tool is by default in the ServiceNow environment, configured to detect such comparisons in the code. A directive can be added to the code which will allow this check to be ignored.

There are a large number of other such checks the JSHint application checks for (with many of them including directives that can be used to configure them off or on). However, the ones listed above account for the vast majority of warnings and errors that are reported by the JSHint tool.

Directives

As mentioned above, most of the constructs that the JSHint tool detects can be toggled with a specific directive for that particular issue. While there are a large number of such directives that can be configured to control the behavior of the tool, those listed below are the most commonly used and will help detect or ignore the greatest number of warning issued in the code. While most of these directives can be controlled directly from a configuration file that is installed with the tool, they can also be specified directly inline within the script to temporarily modify the behavior of the tool within that script. The common syntax for issuing a directive is the following:

// jshint diretivename:value

Where directivename is the name of a specific directive that the jshint tool recognizes and the value is an allowable value for that directive (such as true or false). These directives can be added directly inline on the script in any location, and the results of that directive will then be used from that point in the script to the end of the script object.

These are some of the directives that will most commonly be used by users in the system:

eqeqeq

This directive toggles whether the system will check for or ignore the standard JavaScript equality and inequality operators (== and !=). The system, in many cases, is configured to detect these operators, so to cause the tool to temporarily ignore these checks, the following syntax would be used:

// jshint eqeqeq:false

curly

This directive can be used to control whether the system will check to ensure that all specific code blocks are enclosed in curly braces. By default the tool is configured to perform this check on each line of the code, however to suppress this check the following inline command can be used:

// jshint curly:false

asi

The asi directive can be used to control whether the system will check to ensure that all appropriate lines are terminated by a semi-colon. By default the tool is configured to perform this check, however to suppress this check the following inline command can be used:

// jshint asi:false

maxerr

This determines the maximum number of errors and warnings that the tool will detect before it displays the Too many errors message and detects no further errors in the script. The default setting for the tool is to detect a maximum of 50 errors or warning. However, this value can be increased or decreased through the use of the maxerr directive. This can be particularly useful if the jshint tool is generating a large number of errors or messages based on your own personal coding style (such as usage of the == operator).

// jshint maxerr:100

ignore

This directive causes the jshint tool to completely ignore a section of code in the script. There may be occasions in which the flag is flagging a valid set of syntax or giving issues in which it should not. In order to force the tool to ignore all such warnings (or errors) the ignore directive can be used, passing a value of start. Once the directive is passed a value of start all errors will ignored until either the end of the script is reached or a ignore:end directive is found. The following shows the commands that might be used to ignore a specific section of code.

// jshint ignore:start

// Ignored JavaScript code section

// jshint ignore:end

There are a number of other directives that can also be used directly inline within the script field to customize the jshint tool to a user's specific needs. The links found in the Additional Information section below can provide more information about the joshing tool and and specifics about it's use and configuration.

Additional Information

There are several official links to the JSHint tool that can be found to be useful while working with the JSHint tool, such as the following:

Basic documentation for the JSHint tool:

http://jshint.com/docs/

List and brief description of the options useable with the JSHint tool:

http://jshint.com/docs/

JSHint Homepage (About):

http://jshint.com/about/