CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ts-mocha

Mocha thin wrapper that allows running TypeScript tests with TypeScript runtime (ts-node) to get rid of compilation complexity

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

TS-Mocha

TS-Mocha is a lightweight wrapper around Mocha that simplifies running TypeScript tests with ts-node runtime. It eliminates the complexity of manually configuring TypeScript test environments by automatically handling ts-node registration and providing TypeScript-specific options for path mapping, type checking, and project configuration.

Package Information

  • Package Name: ts-mocha
  • Package Type: npm
  • Language: JavaScript (TypeScript enabled)
  • Installation: npm install -D ts-mocha mocha ts-node
  • Peer Dependencies: mocha, ts-node, tsconfig-paths (optional)

Core Imports

For programmatic usage:

// Set configuration via environment variables before requiring
process.env.TS_NODE_PROJECT = "./tsconfig.json";
process.env.TS_CONFIG_PATHS = true; // optional
require("ts-mocha");

Basic Usage

CLI Usage

# Basic usage - runs TypeScript tests
ts-mocha test/**/*.spec.ts

# With specific tsconfig
ts-mocha -p src/tsconfig.json src/**/*.spec.ts

# With path mapping support
ts-mocha --paths -p src/tsconfig.json src/**/*.spec.ts

# With type checking enabled
ts-mocha --type-check test/**/*.spec.ts

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

Programmatic Usage

// Basic programmatic usage
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);
  });
});

Architecture

TS-Mocha is built around a simple yet effective two-layer architecture:

  • CLI Wrapper (bin/ts-mocha): Command-line interface that parses TypeScript-specific arguments (-p, --paths, --type-check) and sets corresponding environment variables, then spawns Mocha with the registration module preloaded
  • Registration Module (src/index.js): Handles ts-node registration and tsconfig-paths integration based on environment variables, executed before Mocha runs user tests
  • Environment Configuration: Configuration system using environment variables for communication between CLI and registration layers
  • Process Management: Signal handling and exit code forwarding between parent CLI process and child Mocha process
  • Dependency Integration: Seamless integration with ts-node for TypeScript transpilation and optional tsconfig-paths for path mapping resolution

Capabilities

CLI Interface

Command-line wrapper that spawns Mocha with TypeScript support.

ts-mocha [mocha-options] [files...]

# TypeScript-specific options:
# -p, --project <path>    Path to tsconfig.json (default: ./tsconfig.json)
# --paths                 Enable tsconfig-paths integration
# --type-check           Enable TypeScript type checking

Programmatic Interface

Module registration for TypeScript transpilation in Node.js environment.

// Configuration via environment variables
process.env.TS_NODE_PROJECT = string;     // Path to tsconfig.json
process.env.TS_CONFIG_PATHS = any;        // Enable tsconfig-paths when truthy
process.env.TS_TYPE_CHECK = any;          // Enable type checking when truthy

// Registration (side-effect only)
require("ts-mocha");

Environment Configuration

Environment variables that control ts-node behavior.

// Primary configuration variables
TS_NODE_PROJECT: string;        // TypeScript project configuration file path
TS_CONFIG_PATHS: any;           // Enable tsconfig-paths integration (truthy)
TS_TYPE_CHECK: any;             // Enable type checking instead of transpile-only (truthy)

// Deprecated
_TS_PROJECT_PATH__: string;     // Deprecated alias for TS_NODE_PROJECT

Configuration Options

TypeScript Project Configuration

The package reads TypeScript configuration from the specified tsconfig.json file:

  • Default Path: ./tsconfig.json
  • CLI Override: -p or --project flag
  • Programmatic Override: TS_NODE_PROJECT environment variable

Path Mapping Support

Enable TypeScript path mapping resolution:

  • CLI Flag: --paths
  • Environment Variable: TS_CONFIG_PATHS=true
  • Requires: tsconfig-paths package (optional peer dependency)

Type Checking Control

Control TypeScript type checking behavior:

  • Default: Transpile-only mode (faster, no type checking)
  • CLI Flag: --type-check to enable type checking
  • Environment Variable: TS_TYPE_CHECK=true

Error Handling

The package handles ts-node registration errors:

// Error handling pattern (internal)
try {
  const project = process.env.TS_NODE_PROJECT || 
                  process.env._TS_PROJECT_PATH__ || 
                  './tsconfig.json';
  const transpileOnly = !process.env.TS_TYPE_CHECK;
  require('ts-node').register({
    project,
    transpileOnly,
  });
  if (process.env.TS_CONFIG_PATHS) {
    require('tsconfig-paths/register');
  }
} catch (error) {
  console.log('[ERROR] ' + error.message);
  process.exit(1);
}

Common error scenarios:

  • Missing ts-node or tsconfig-paths dependencies
  • Invalid TypeScript configuration
  • TypeScript compilation errors (when type checking enabled)

Integration Patterns

With Mocha Programmatically

// Full programmatic setup
process.env.TS_NODE_PROJECT = "./test/tsconfig.json";
process.env.TS_CONFIG_PATHS = true;
require("ts-mocha");

const Mocha = require("mocha");
const path = require("path");

const mocha = new Mocha();
mocha.addFile(path.resolve(__dirname, "app.spec.ts"));
mocha.run((failures) => {
  process.on("exit", () => {
    process.exit(failures);
  });
});

With Package Scripts

{
  "scripts": {
    "test": "ts-mocha test/**/*.spec.ts",
    "test:watch": "ts-mocha test/**/*.spec.ts -w --watch-files '**/*.ts'",
    "test:typecheck": "ts-mocha --type-check test/**/*.spec.ts"
  }
}

With Different TypeScript Configurations

# Different configs for different test suites
ts-mocha -p test/unit/tsconfig.json test/unit/**/*.spec.ts
ts-mocha -p test/integration/tsconfig.json test/integration/**/*.spec.ts

docs

index.md

tile.json