ts-mocha

What is ts-mocha?

The ts-mocha package is a TypeScript test runner for Mocha, allowing you to write and run Mocha tests in TypeScript without needing to compile your TypeScript files beforehand. It simplifies the process of testing TypeScript code by integrating directly with Mocha.

What are ts-mocha's main functionalities?

Running TypeScript Tests

This feature allows you to run Mocha tests written in TypeScript directly. The code sample demonstrates a simple test case using Mocha's `describe` and `it` functions to test an array's `indexOf` method.

const assert = require('assert');

describe('Array', function() {
  describe('#indexOf()', function() {
    it('should return -1 when the value is not present', function() {
      assert.strictEqual([1, 2, 3].indexOf(4), -1);
    });
  });
});

Integration with TypeScript

This feature highlights the ability to use TypeScript-specific features such as type annotations within your tests. The code sample shows a test case using Chai's `expect` assertion library to validate a TypeScript variable.

import { expect } from 'chai';

describe('TypeScript Test', () => {
  it('should support TypeScript features', () => {
    const result: number = 5;
    expect(result).to.equal(5);
  });
});

Configuration via tsconfig.json

This feature allows you to configure TypeScript compilation settings using a `tsconfig.json` file. The code sample shows a basic `tsconfig.json` configuration that specifies compiler options and includes/excludes certain files.

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es6",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

Other packages similar to ts-mocha

mocha

Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple and fun. While Mocha itself does not support TypeScript out of the box, it can be used with TypeScript by using additional tools like ts-node or by pre-compiling TypeScript files.

jest

Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It works with projects using Babel, TypeScript, Node.js, React, Angular, Vue.js, and Svelte. Jest has built-in support for TypeScript, making it a popular choice for testing TypeScript projects.

ava

AVA is a test runner for Node.js with a concise API, detailed error output, and process isolation. It supports TypeScript through the use of additional configuration and tools like ts-node, similar to how ts-mocha operates.

README

TS-Mocha

ts-mocha is a wrapper on top of mocha to allow running tests written in TypeScript without setting up a complicated setup in your project, it just works.

All mocha features are available without any limitation because ts-mocha is passing all the params to original mocha behind the scenes.

Why?

To setup Mocha with TypeScript you need to figure out how to set it up together, it's not an easy task and require some time and effort to setup correctly. Moreover this setup will stop working whenever mocha or ts-node introduce breaking changes, so you'll have to fix it and waste your time again.

This package handles all that concerns for you and let you use ts-mocha in the same way as a regular mocha while supporting TypeScript.

Also we added some useful options to make your life easier specifically for TypeScript projects, you can find them below.

How?

TS-Mocha has one only dependency - ts-node, which is used as a TypeScript runtime to execute tests that can import and run imported TypeScript source files as well. It is a thin wrapper that run node process with mocha and set up ts-node environment to handle .ts and .tsx files. To speed up TypeScript tests execution type-checking is disabled, using only transpile mode.

NOTE: This package does not include Mocha - Mocha is set as peer dependency, so I don't lock the consumer to a specific Mocha version and I don't have to update this package when Mocha is updated.

PRO TIP: To make your developer experience better I recommend to run type-checking in a separate process by starting TSC compiler (preferably in watch mode) in you terminal with --noEmit and --project flags.

Installation

# remember to install mocha if you don't have it already (npm i -D mocha)

npm i -D ts-mocha

# install recent Mocha and Expect @types packages for best DX
npm i -D @types/mocha @types/expect

Usage

- CLI Usage

CLI options consist of all the options of regular Mocha plus extra options below:

-p, --project <value> - relative or absolute path to a tsconfig.json file (equivalent of tsc -p <value>) [default: "./tsconfig.json"]

Example:

ts-mocha -p src/tsconfig.json src/**/*.spec.ts

--paths - feature toggle flag to enable tsconfig-paths integration [default: false]

tsconfig-paths is an optional dependency, make sure to install it locally in your project

When using path mapping via the paths compiler option in tsconfig.json this library utilizes the tsconfig-paths package, allowing for automatic resolution of aliased modules locations during test execution.

Check our test suite for a reference implementation: Link

Example:

ts-mocha --paths -p src/ src/**/*.spec.ts

--type-check - feature toggle flag to enable type checking in ts-node [default: false]

By default ts-mocha uses the --transpile-only option of ts-node to make tests run faster. Use the --type-check option to enable type checking in ts-node.

Example:

ts-mocha --type-check -p src/ src/**/*.spec.ts

Watch Mode

If you want your tests to be automatically rerun when your code changes, add both the -w flag and the --watch-files flag telling it to watch for typescript files.

Example:

ts-mocha test/**/*.spec.ts -w --watch-files '**/*.ts'

- Programmatic usage

In code you can use ts-mocha by adding a single require at the beginning of your script:

// set env variable to the `tsconfig.json` path before loading mocha (default: './tsconfig.json')
process.env.TS_NODE_PROJECT = './src/tsconfig.json'

// Optional: set env variable to enable `tsconfig-paths` integration
process.env.TS_CONFIG_PATHS = true;

// register mocha wrapper
require('ts-mocha');

For example:

process.env.TS_NODE_PROJECT = './src/tsconfig.json';
require('ts-mocha');
const Mocha = require('mocha');

const mocha = new Mocha();
mocha.addFile(`./src/file.spec.ts`);
mocha.run((failures) => {
  process.on('exit', () => {
    process.exit(failures); // exit with non-zero status if there were failures
  });
});