JavaScript Code Inspection Server-Side

JetBrains

If you use one of our intelligent IDE’s such as Intellij IDEA Ultimate Edition, WebStorm or PhpStorm, for any kind of Web development, then you might be familiar with the powerful JavaScript inspections they offer. With over 130 validation rules, ranging from “Code style issues” to “Probable bugs” as well as built-in JSLint/JSHint integration, they constitute a powerful barrier against certain errors creeping into your JavaScript code.

Did you also know that you can have these inspections server-side as part of a continuous build process? With TeamCity you can run the same set of inspections on the server, and have the build fail, based on the criteria you define. This can be critical errors or even too many warnings.

Let’s see how it’s done. In this guide we’ll be using WebStorm, but the same process applies to any of our other platforms based on IDEA that support JavaScript.

1 – Defining a Scope

The first thing we need to do is specify a scope. Scopes define a set of sources (from all available in a project) to be inspected. Projects often contain third-party JavaScript libraries and/or minified scripts that in principle shouldn’t be analysed. As such, defining a scope allows us to specify what we do want to focus on.

Under File -> Settings in WebStorm, locate the Scope entry (you can type Scope in the search box for quick access). Click the + button and choose Add Scope -> Local, then specify its name, JavaScript in our case.

Once you do so you’ll see project’s files on the right (click the image to see a larger version).

Select JavaScript files intended for inspection (you can hold Ctrl button to select multiple files at once) and click the Include button on the right as can be seen on the screenshot below. Alternatively, you can select a directory and click the Include Recursively button. When you’re done make sure Share scope checkbox is checked. Doing so creates .idea/scopes/JavaScript.xml file containing the definition of the scope we’ve just created. This file should be committed to source control, a point we’ll get back to later in the process.

2 – Creating an Inspection Profile

The next step is to create a JavaScript-only inspection profile if you don’t want to deal with all kinds of validations at the same time. It is best to separate them and concentrate on one thing at a time – this will allow creating a dedicated TeamCity build configuration as we’re about to see.

Go back to File -> Settings and find the Inspections entry. Create a new inspection profile JS Inspection and remember that name, we’ll need it at step 6.

Uncheck all inspections except JavaScript.

Attach the scope defined at step 1 to rules you’re interested in.

3 – Defining Warnings and Errors

Every inspection rule can have a varying degree of severity, ranging from simple typos to critical errors. It is important to differentiate between warnings and errors since TeamCity allows us to treat them differently when specifying build failure conditions.

Some teams may consciously decide to pay attention (and hence fail the build) only to actual errors, which might cause browser misbehaviours at run-time. Examples include the famous last comma in array or object literal in IE issue. Other teams may treat errors and warnings equally so that neither of them ever make it to release. Whatever your preferences are, make sure inspection rules are in sync with them.

4 – Sharing and Locking Inspection Profile

When scopes and inspection profiles are defined the default location for IDE to keep this data is .idea/workspace.xml. However, this file is intended for keeping your local IDE settings and is therefore should never be committed to source control. If this file is not committed how can TeamCity read the definitions required for running server-side JavaScript inspections? That’s where sharing scopes and profiles comes into play. When you tick the corresponding Share scope or Share profile checkbox a separate file is created with your definitions: .idea/scopes/<scopeName>.xml for scopes and .idea/inspectionProfiles/<profileName>.xml for inspection profiles. These files can now be committed to source control for TeamCity to read them.

Locking inspection profile is a different story. Your IDE may have certain plugins disabled which will consequently make their inspections disappear from inspection profile screen. However, when TeamCity runs server-side code inspections it does so by firing up its own Intellij IDEA instance. This instance comes bundled with a default set of plugins and, therefore, a default set of inspections applied to your code in addition to those specified by you. As a result, it may be surprising to see TeamCity running inspections that were never part of the profile. So locking it means “Run only explicitly enabled inspections”.

As a result, you need to share and lock your inspection profile as shown on the following screenshot.

5 – Committing “.idea” directory to source control

After inspection profile is configured, shared and locked you need to check in an .idea directory into source control for TeamCity to read inspection definitions from there. Once again, the only file that should not be committed and is excluded by default is .idea/workspace.xml since it only contains your personal project settings.

6 – Configuring TeamCity Build Configuration

Once we have the inspections ready and committed to source control, we can now do the set up on the server-side. To do so, add a new Build Step and select Inspections (Java).

Configure this step similarly to the screenshot below (click the image to see a larger version).

The only thing that needs to be specified on this screen is Inspection profile name from step 2. You can now try to run your build configuration to see if there are any build errors. When all goes well you can navigate to inspection results from TeamCity “Overview” screen.

When browsing inspection result, you can open the offending line right in your IDE if you have TeamCity IDE plugin installed and logged in to your TeamCity instance.

7 – Configuring TeamCity Build Failure Conditions

Now that we can run inspections on the server, we can define build failure conditions using “Fail build on metric change” introduced in TeamCity 7. As mentioned in Step 3, inspection errors and warnings are treated as two separate metrics so we can define each of them in its own way.

The project we are using as an example contains no severe JavaScript errors, but it does contain a number of warnings which now make the build fail, and loudly!

As mentioned previously, we may decide to fail the build only in the case of actual errors to avoid the extra noise, and thus avoiding dealing with builds failing due to minor JavaScript warnings or nuances.

Summary

The process of running JavaScript inspections in TeamCity relies on the project definitions set in the IDE, that is why it is necessary to configure the previous steps and commit these to source control. Once done, the remaining steps on TeamCity are straight-forward. All you need to remember is the inspection profile name and from there on, it is up to you to define the build failure conditions.

Happy JavaScript coding!

Subscribe to TeamCity Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!