Using the Chutzpah.json Settings File

The Chutzpah settings file is an .json file that you can place anywhere in your testing directories to inform Chutzpah of test specific settings. The Chuzpah settings file is completely optional and if the file or any of its properties are omitted Chutzpah will use the default values.

When Chutzpah is run on a file (lets say test.js) it scans the current directory for a file named chutzpah.json. If it does not find one it will recursively traverse up the directory chain looking for one. This behavior provides a lot of flexibility since you can provide multiple chutzpah.json files in your tree and each one will work over its sub-folder. This lets you have different settings for different groups of tests.

Important: The deserializer Chutzpah uses is is restrictive about what you put in your chutzpah.json file. To make sure it parses correctly make sure you surround all properties in quotes and do not put comments in the file.

The settings file is a text file with json content of the following format:


The chutzpah.json file supports the following properties

Framework– Determines what testing framework to use. This will override the other detection methods. This is helpful if Chutzpah is having trouble figuring out what your intended framework is. If left out Chutzpah will automatically try to detect the framework.

FrameworkVersion - Tells Chutzpah if it should use a different version of on of the test frameworks than the default one. Currently, the only framework this works for is Jasmine. As of the 3.1.0 release Chutzpah default to Jasmine 2.0 but if you want to use the 1.0 line for Jasmine still pass "1" for FrameworkVersion.

TestFileTimeout - The time to wait for tests in a file to finish in milliseconds

TestHarnessLocationMode– Determines where to place the generated html test harness files. The default mode is TestFileAdjacent which means the harness is placed in the same directory as the test file. SettingsFileAdjacent means it is placed in the same directory as the chutzpah.json file. Custom mode lets you specify a custom path to the directory.

TestHarnessDirectory– When TestHarnessLocationMode is set to Custom this is either the relative or absolute path to the directory where to place the test harness.

TypeScriptCodeGenTarget– When running on a TypeScript file this property will tell the TypeScript compiler what type of code to generate. ES3 is for ECMAScript 3 and ES5 is for ECMAScript 5.

RootReferencePathMode– This property determines what directory a rooted reference path refers to. In a test file Chutzpah parses the <reference path="" /> tags to determine your test dependencies. By default (the DriveRoot setting) if you write <reference path="\a.js" /> Chutzpah will look for a.js under C:\ (assuming you are running your test in the C drive). However, if you set this property to SettingsFileDirectory Chutpah will now look for a.js relative to the location of the chutzpah.json file. This is useful if you have a large project and want to minimize the number of long reference paths.

CodeCoverageIncludes - The collection code coverage file patterns to include in coverage. These are in glob format. If you specify none all files are included.

CodeCoverageExcludes - The collection code coverage file patterns to exclude in coverage. These are in glob format. If you specify none no files are excluded.

CustomTestHarnessPath - The CustomTestHarnessPath setting allows you to override the default template Chutzpah uses for the HTML test harness. This is an advanced feature which should only be used as a last resort. Read how to use it in Customizable HTML harness generation.

CoffeeScriptBareMode - The CoffeeScriptBareMode indicates if you want CoffeeScript compilation to output scripts in bare mode or not. In bare mode CoffeeScript won’t wrap the generated JavaScript in a function to protect the scope. The default value is true.

References - The references setting allows you to specify which files/folders to use/scan to find references. This is useful since it replaces the need to the ///<reference comments. This setting is a list of path entries each which can contain the following arguments:

Path	The path to either a file or a folder. If given a folder, it will be scanned recursively. This path can be relative to the location of the chutzpah.json file.
Include	This is an optional include glob pattern. This is used when the Path is a folder. Only files matching the Include pattern will be added.
Exclude	This is an optional exclude glob pattern. This is used when the path is a folder. All files matching the exclude pattern will not be added.
IncludeInTestHarness	This determines if the reference should be injected into the test harness. When referencing files like .d.ts or files that you plan to load using require.js you should set this to false. Defaults to true.
IsTestFrameworkFile	Indicated that this references should be placed directly after the test framework files (like QUnit.js) in the test harness. This ensures that this file is injected into the test harness before almost all other files. Defaults to false.

Examples:

This file tells Chutzpah to use QUnit and to place the test harness next to the chutzpah.json file:

This file tells Chutzpah to convert TypeScript to ES5 code and to place the test harness in a custom directory:

When run with Code Coverage this file tells Chutzpah to exclude files named jquery.js and include files that have a suffix of query.js or are named dogs.js:

Include files named a.js and b.js:

Include all .js files in a folder unless their name contains the word Resource:



Tests - The tests setting allows you to specify which files/folders to use as test files. The tests setting section can be used in two ways: discovery or filtering.

For discovery you can tell chutzpah.console.exe to execute a chutzpah.json file. Chutzpah will evaluate the tests settings and use it to find all files it describes.

chutzpah.console.exe path/to/chutzpah.json

For filtering Chutzpah will skip test files which don’t match the tests setting. This is a much needed feature for the Visual Studio integration. By default the test adapter plugin will look at all *.js files and try to see if they are test files. Often Chutzpah is able to use heuristics to quickly tell if a file is a test file. If the heuristics fails it then needs to actually execute that file. This can be very slow especially if Chutzpah is doing this with a large JS library. With this tests setting feature you can help Chutzpah out by placing a chutzpah.json at the root of your project and indicate which files are the test files. This can be a big performance boost and is the recommendation for all projects.

Path	The path to either a file or a folder. If given a folder, it will be scanned recursively. This path can be relative to the location of the chutzpah.json file.
Include	This is an optional include glob pattern. This is used when the Path is a folder. Only files matching the Include pattern will be added.
Exclude	This is an optional exclude glob pattern. This is used when the path is a folder. All files matching the exclude pattern will not be added.

Example:

This file shows a few different ways you can write the test settings.

• Line #3 – Includes all tests that contain test1 in its path. This is in glob format.
• Line #4 – Includes the file Dir3/test.js (relative to the chtuzpah.json path).
• Line #5 – Includes all *.js files in the folder Dir1 except test4.js. (Include/Exclude in glob format)
• Line #6 – Includes all files in Dir2