TeamCity JavaScript Inspections? Oh Yes.

If you use one of JetBrains intelligent IDEs such as Intellij IDEA Ultimate Edition, WebStorm or PhpStorm for any kind of Web development then you must be familiar with their powerful JavaScript inspections. With 130+ validation rules ranging from “Code style issues” to “Probable bugs” and built-in JSLint/JSHint integration that’s a powerful protection barrier stopping errors from creeping into your JavaScript code.

But can you take it to another level? Can you make TeamCity run the same set of inspections and fail the build if critical errors are found or there are way too many new warnings? Oh yes, absolutely, and I’m about to show you all the steps and details involved.

I’m going to use WebStorm in this demo setup but you can follow the same process using either Intellij IDEA Ultimate Edition or PhpStorm.

1 – Create Scope

The very first thing you need to specify is a scope. Scopes define an exact subset of sources (from all available in a project) to be inspected. When a project contains third-party JavaScript libraries or minified versions of your JavaScript code it doesn’t make much sense to analyse these: any warnings or errors produced are not going to be fixed anyway.

So specify first what is it you do want to analyze (click the image to see a larger version):

Note the “Share scope” checkbox which needs to be checked. Sharing "JavaScript" scope creates ".idea/scopes/JavaScript.xml" file with scope’s definition.

2 – Create Inspection Profile

Next step is creating a JavaScript-only inspection if you don’t want to deal with CSS and HTML 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 you’re about to see.

Create a new inspection profile named "JS Inspection". 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 – Error or Warning?

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

Some teams may consciously decide to pay attention (and hence fail the build) only to the actual errors, causing browser misbehavior at run-time, such as famous “Last comma in array or object literal” in IE. Other teams may treat errors and warnings equally so that none of them ever makes it to release. Whatever your preferences are, make sure inspection rules are in sync with them.

4 – “Share” and “Lock” Inspection Profile

Inspection profile needs to be “shared” and “locked”, as is shown on the screenshot below.

“Sharing” profile creates ".idea/inspectionProfiles/JS_Inspection.xml" and “locking” it writes out all rules selected and their scope into this file so TeamCity doesn’t apply any additional inspections you may not see due to IDE plugins being disabled.

5 – Commit “.idea” directory to VCS

".idea" directory needs to be checked in into VCS repository for TeamCity to read inspection definitions from there (that’s why it was important to “share” the scope and inspection profile in the previous steps). The only file that should not be committed and is therefore excluded by default is ".idea/workspace.xml" since it only contains your personal project settings.

6 – Configure TeamCity Build Configuration

Things get much easier when you switch over to setting up TeamCity build configuration. Add "Inspections (Java)" build step.

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

In fact, the only thing that needs to be specified on this screen is “Inspection profile name” from step 2. If in doubt, you can copy this name from ".idea/inspectionProfiles/<profile name>"

You can now try to run your build configuration to see if there are any build errors. TeamCity shouldn’t fail if scope (step 1) and inspection profile (step 2) definitions were “shared” and all ".idea" files were committed to VCS repository. When all goes well you can browse inspection results ..

.. and open the offending line right in your IDE if you have TeamCity IDE plugin installed and logged in to your TeamCity instance.

7 – Configure TeamCity Build Failure Conditions

Being able to run JavaScript inspections in TeamCity you may now want to define build failure conditions using “Fail build on metric change” introduced in TeamCity 7. As I have mentioned at step 3, inspection errors and warnings are treated as two separate metrics so you can define each of them in its own way.

The project I have taken as an example contains no severe JavaScript errors but it contains a number of warnings which now make my build fail loudly!

As I mentioned previously, you may decide to fail the build only in the case of actual errors to avoid the extra noise and having to deal with builds failing due to minor JavaScript warnings.

Summary

The process of running JavaScript inspections in TeamCity relies heavily on project definition in your IDE (IDEA, WebStorm or PhpStorm) so I have provided all required steps. Once IDE scope and inspection profile are properly specified and ".idea" directory is committed to VCS it is a straightforward process to setup a corresponding TeamCity build configuration. All you need to remember is inspection profile name and from there it is up to you to define build failure conditions based on amount of warnings and errors.

Happy JavaScript coding!