ts-mocha

library11.1.0jsnpmunverified

ts-mocha is a lightweight wrapper around the Mocha testing framework, designed to simplify the execution of TypeScript test files. It integrates with `ts-node` to compile TypeScript on the fly, eliminating the need for a separate compilation step prior to running tests. The package is currently at version 11.1.0 and maintains an active release cadence, frequently updating to support newer versions of Mocha, ts-node, and TypeScript itself. Its primary differentiator is the 'zero-config' approach to getting TypeScript tests running with Mocha, abstracting away complex `ts-node` and `tsconfig-paths` configurations. It also offers specific TypeScript-centric features like optional type-checking during test runs and path mapping resolution, which are crucial for larger TypeScript projects.

testing

npm install ts-mocha

github ↗package ↗

INSTALL

IMPORT

SIG · TS-MOCHA

ts-mocha

testingjavascriptv11.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ts-mocha

✓ ts-mocha --project tsconfig.json --paths test/**/*.spec.ts

✗ mocha --require ts-node/register --require tsconfig-paths/register test/**/*.spec.ts

Primary usage is via CLI; ts-mocha simplifies the complex mocha --require setup. No direct JavaScript import for the CLI runner.

Programmatic usage

✓ require('ts-mocha')

For programmatic usage in JavaScript or CommonJS environments. Typically used at the top of a test runner script. Ensure environment variables are set before requiring.

This quickstart demonstrates installing ts-mocha and its peer dependencies, creating a basic TypeScript test file using Mocha and Chai, and then running the tests from the command line, including an example with path mapping.

npm init -y npm i -D mocha ts-node tsconfig-paths @types/mocha @types/node ts-mocha mkdir test echo 'import { expect } from "chai";\n\ndescribe("My Test Suite", () => {\n it("should pass", () => {\n expect(true).to.be.true;\n });\n});' > test/example.spec.ts echo '{ "compilerOptions": { "module": "CommonJS", "target": "ES2016", "esModuleInterop": true, "strict": true, "baseUrl": ".", "paths": { "@lib/*": ["src/*"] } } }' > tsconfig.json mkdir src echo 'export const greet = (name: string) => `Hello, ${name}!`;' > src/index.ts echo 'import { expect } from "chai";\nimport { greet } from "@lib/index";\n\ndescribe("Greeting function", () => {\n it("should greet correctly", () => {\n expect(greet("World")).to.equal("Hello, World!");\n });\n});' > test/lib.spec.ts # Run tests without path mapping (will fail lib.spec.ts) # ts-mocha test/**/*.spec.ts # Run tests with path mapping ts-mocha --paths test/**/*.spec.ts # Or for watch mode # ts-mocha -w --watch-files '**/*.ts' test/**/*.spec.ts

ts-mocha --version

Debug

Known issues

breakingts-node moved from direct dependency to peer dependency in v11.0.0. This change requires users to explicitly install `ts-node` in their project, which was previously an indirect dependency. This allows for greater flexibility and better deduplication of `ts-node` versions.

fix

Ensure `ts-node` is installed as a direct `devDependency`: `npm install -D ts-node`.

affects: >=11.0.0

breakingtsconfig-paths moved from optional dependency to peer dependency in v11.1.0. If you use TypeScript's path mapping feature (`compilerOptions.paths` in `tsconfig.json`), you must now explicitly install `tsconfig-paths`.

fix

If you utilize path mapping in your `tsconfig.json`, install `tsconfig-paths` as a `devDependency`: `npm install -D tsconfig-paths`. Additionally, remember to enable it with the `--paths` flag during CLI execution.

affects: >=11.1.0

gotchaBy default, ts-mocha runs `ts-node` in `--transpile-only` mode for faster test execution. This means TypeScript type checking is disabled during the test run.

fix

To enable full type checking during tests, use the `--type-check` flag with the ts-mocha CLI: `ts-mocha --type-check test/**/*.spec.ts`.

affects: >=1.0.0

gotchaWhen using TypeScript's path mapping (`compilerOptions.paths` in `tsconfig.json`), `ts-mocha` requires the `--paths` flag to be enabled and `tsconfig-paths` installed to correctly resolve module aliases.

fix

Install `tsconfig-paths` (`npm i -D tsconfig-paths`) and pass the `--paths` flag to the ts-mocha CLI: `ts-mocha --paths test/**/*.spec.ts`.

affects: >=2.0.0

gotchaThe watch mode (`-w`) in ts-mocha requires the `--watch-files` flag to specify which files to monitor for changes, otherwise, it might not re-run tests as expected.

fix

When using watch mode, always include `--watch-files` with a glob pattern matching your TypeScript source and test files: `ts-mocha -w --watch-files '**/*.ts' test/**/*.spec.ts`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ts-node/register'

ts-node is not installed or not resolvable in the project's node_modules. This error became more common after ts-mocha v11.0.0 made ts-node a peer dependency.

fix

Install ts-node as a development dependency: `npm install -D ts-node`.

Error: Cannot find module '@alias/module' from 'path/to/test.ts'

TypeScript path mapping (compilerOptions.paths) is not being correctly resolved by ts-node, likely due to `tsconfig-paths` not being installed or enabled.

fix

Install `tsconfig-paths` (`npm install -D tsconfig-paths`) and ensure you pass the `--paths` flag to the ts-mocha CLI: `ts-mocha --paths test/**/*.spec.ts`.

Cannot read properties of undefined (reading 'register')

This error can occur if a version mismatch or conflict exists between `mocha` and `ts-mocha` or `ts-node`, particularly if `mocha` is too old or `ts-node` cannot be loaded correctly.

fix

Ensure `mocha` and `ts-node` meet the peer dependency requirements of your `ts-mocha` version. Update these packages if necessary (`npm update mocha ts-node`). Clean `node_modules` and reinstall: `rm -rf node_modules && npm install`.

Upgrade

Version history

11.1.0latest on npm

Audit

Dependencies

mocharequiredCore testing framework that ts-mocha wraps.

ts-noderequiredTypeScript runtime for on-the-fly compilation. Moved to peer dependency in v11.0.0.

tsconfig-pathsoptionalRequired for resolving TypeScript path aliases (compilerOptions.paths). Moved to peer dependency in v11.1.0 and is explicitly enabled via the --paths flag.

@types/mochaoptionalProvides TypeScript type definitions for Mocha.

@types/expectoptionalProvides TypeScript type definitions for the expect assertion library, commonly used with Mocha.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/piotrwitek/ts-mocha ↗

packagehttps://www.npmjs.com/package/ts-mocha ↗