Add test categories to mocha (BDD style) and jasmine tests.
Install the library to your project (usually as a dev dependency).
npm install js-testcat --save-dev
To use the library simply import or require it, then use cdescribe or cit instead of describe or it:
import { cdescribe, cit } from 'js-testcat';
// A regular mocha/jasmine test suite/spec
describe('Some Spec', () => {
// A suite/spec with a single test category
cdescribe('Spec with test category', 'MyCategory', () => {
it('Test case', () => {
// .. test code
});
});
// A test case with multiple test categories.
cit('Test case with test categories', ['SomeCategory', 'SomeOtherCategory'], () => {
});
});You can find more samples in the js-testcat-samples repo.
The cdescribe specs/suites and cit test cases are executed depending on the test categories you pass to the test run:
- Neither includes nor excludes
Js-testcat will execute all test suites/specs and test cases as if you had used describe and it instead of cdescribe and cit. - Includes only
When you provide only test category includes to the test run, js-testcat only executes test cases and suites/specs that are associated with at least one of the included categories. - Excludes only
When passing only test category excludes to the test run, js-testcat executes all suites/specs and test cases that are not associated with any of the excluded categories. - Includes and excludes
If you pass both included and excluded test categories to the test run, js-testcat only executes test suites/specs and test cases that are associated with at least one of the included, but not associated with any of the excluded categories.
Note: Test category comparison is done case-sensitive!
Js-testcat uses the following APIs to let you define and configure test categories:
Use the cdescribe function instead of mocha's or jasmine's describe function to create a test suite/spec that is associated with one or more test categories. In addition to the regular description and callback parameters, js-testcat adds the parameter categories that takes either a single category (string) or a list of categories (string[]) and associates the suite/spec with the given test categories.
Use the cit function instead of mocha's or jasmine's it function to create a test case that is associated with one or more test categories. In addition to the regular description and callback parameters, js-testcat adds the parameter categories that takes either a single category (string) or a list of categories (string[]) and associates the suite/spec with the given test categories.
The addTestcatFile and removeTestcatFile functions provide a way of adding or removing test category includes and excludes from a js-testcat file (see below) directly in your test code. Both methods throw an error if the file does not exist.
The addIncludes, removeIncludes, and removeAllIncludes functions provide a way of adding or removing test category includes directly in your test code. Similar to the categories parameter of the cdescribe and cit functions, you may either pass a single include (string) or a list of includes (string[]);
If you want to access the currently included or excluded test categories, you can use the getIncludes and getExcludes functions both of which return a string[].
The addExcludes, removeExcludes, and removeAllExcludes functions provide a way of adding or removing test category excludes directly in your test code. Similar to the categories parameter of the cdescribe and cit functions, you may either pass a single exclude (string) or a list of excludes (string[]);
Resets js-testcat to its uninitialized state. This forces js-testcat to re-initialize test categories from environment variables.
Since neither mocha nor jasmine provide an easy way of passing arbitrary parameters to the test execution, js-testcat uses the following environment variables to configure included and excluded test categories.
Set JSTESTCAT_INCLUDE to a comma-separated list of category names to include them in the test execution and set JSTESTCAT_EXCLUDE to a comma-separated list of category names to exclude them from the test execution.
Set JSTESTCAT_FILE to the path to a js-testcat file that contains the test categories you want to include and exclude.
The easiest way to quickly switch between different sets of test categories is to use js-testcat files. A js-testcat file is a simple JSON file containing included and excluded test categories. The below sample file configures js-testcat to run all unit and integration tests but not UI tests.
{
"includes": [
"Unit",
"Integration"
],
"excludes": [
"UI"
]
}Make sure to have gulp (npm install -g gulp) and typescript (npm install -g typescript) globally installed, then clone the repo and run npm install.
Once all packages have been restored, run npm test to build and test js-testcat or simply run tsc to just transpile the code to JavaScript. With the included launch.json you can also easily debug the tests using Visual Studio Code.