0
# TS-Mocha
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: ts-mocha
7
- **Package Type**: npm
8
- **Language**: JavaScript (TypeScript enabled)
9
- **Installation**: `npm install -D ts-mocha mocha ts-node`
10
- **Peer Dependencies**: mocha, ts-node, tsconfig-paths (optional)
11

12
## Core Imports
13

14
For programmatic usage:
15

16
```javascript
17
// Set configuration via environment variables before requiring
18
process.env.TS_NODE_PROJECT = "./tsconfig.json";
19
process.env.TS_CONFIG_PATHS = true; // optional
20
require("ts-mocha");
21
```
22

23
## Basic Usage
24

25
### CLI Usage
26

27
```bash
28
# Basic usage - runs TypeScript tests
29
ts-mocha test/**/*.spec.ts
30

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

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

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

40
# Watch mode
41
ts-mocha test/**/*.spec.ts -w --watch-files '**/*.ts'
42
```
43

44
### Programmatic Usage
45

46
```javascript
47
// Basic programmatic usage
48
process.env.TS_NODE_PROJECT = "./src/tsconfig.json";
49
require("ts-mocha");
50

51
const Mocha = require("mocha");
52
const mocha = new Mocha();
53
mocha.addFile("./src/file.spec.ts");
54
mocha.run((failures) => {
55
  process.on("exit", () => {
56
    process.exit(failures);
57
  });
58
});
59
```
60

61
## Architecture
62

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

65
- **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
66
- **Registration Module** (`src/index.js`): Handles ts-node registration and tsconfig-paths integration based on environment variables, executed before Mocha runs user tests  
67
- **Environment Configuration**: Configuration system using environment variables for communication between CLI and registration layers
68
- **Process Management**: Signal handling and exit code forwarding between parent CLI process and child Mocha process
69
- **Dependency Integration**: Seamless integration with ts-node for TypeScript transpilation and optional tsconfig-paths for path mapping resolution
70

71
## Capabilities
72

73
### CLI Interface
74

75
Command-line wrapper that spawns Mocha with TypeScript support.
76

77
```bash { .api }
78
ts-mocha [mocha-options] [files...]
79

80
# TypeScript-specific options:
81
# -p, --project <path>    Path to tsconfig.json (default: ./tsconfig.json)
82
# --paths                 Enable tsconfig-paths integration
83
# --type-check           Enable TypeScript type checking
84
```
85

86
### Programmatic Interface
87

88
Module registration for TypeScript transpilation in Node.js environment.
89

90
```javascript { .api }
91
// Configuration via environment variables
92
process.env.TS_NODE_PROJECT = string;     // Path to tsconfig.json
93
process.env.TS_CONFIG_PATHS = any;        // Enable tsconfig-paths when truthy
94
process.env.TS_TYPE_CHECK = any;          // Enable type checking when truthy
95

96
// Registration (side-effect only)
97
require("ts-mocha");
98
```
99

100
### Environment Configuration
101

102
Environment variables that control ts-node behavior.
103

104
```javascript { .api }
105
// Primary configuration variables
106
TS_NODE_PROJECT: string;        // TypeScript project configuration file path
107
TS_CONFIG_PATHS: any;           // Enable tsconfig-paths integration (truthy)
108
TS_TYPE_CHECK: any;             // Enable type checking instead of transpile-only (truthy)
109

110
// Deprecated
111
_TS_PROJECT_PATH__: string;     // Deprecated alias for TS_NODE_PROJECT
112
```
113

114
## Configuration Options
115

116
### TypeScript Project Configuration
117

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

120
- **Default Path**: `./tsconfig.json`
121
- **CLI Override**: `-p` or `--project` flag
122
- **Programmatic Override**: `TS_NODE_PROJECT` environment variable
123

124
### Path Mapping Support
125

126
Enable TypeScript path mapping resolution:
127

128
- **CLI Flag**: `--paths`
129
- **Environment Variable**: `TS_CONFIG_PATHS=true`
130
- **Requires**: tsconfig-paths package (optional peer dependency)
131

132
### Type Checking Control
133

134
Control TypeScript type checking behavior:
135

136
- **Default**: Transpile-only mode (faster, no type checking)
137
- **CLI Flag**: `--type-check` to enable type checking
138
- **Environment Variable**: `TS_TYPE_CHECK=true`
139

140
## Error Handling
141

142
The package handles ts-node registration errors:
143

144
```javascript { .api }
145
// Error handling pattern (internal)
146
try {
147
  const project = process.env.TS_NODE_PROJECT || 
148
                  process.env._TS_PROJECT_PATH__ || 
149
                  './tsconfig.json';
150
  const transpileOnly = !process.env.TS_TYPE_CHECK;
151
  require('ts-node').register({
152
    project,
153
    transpileOnly,
154
  });
155
  if (process.env.TS_CONFIG_PATHS) {
156
    require('tsconfig-paths/register');
157
  }
158
} catch (error) {
159
  console.log('[ERROR] ' + error.message);
160
  process.exit(1);
161
}
162
```
163

164
Common error scenarios:
165
- Missing ts-node or tsconfig-paths dependencies
166
- Invalid TypeScript configuration
167
- TypeScript compilation errors (when type checking enabled)
168

169
## Integration Patterns
170

171
### With Mocha Programmatically
172

173
```javascript
174
// Full programmatic setup
175
process.env.TS_NODE_PROJECT = "./test/tsconfig.json";
176
process.env.TS_CONFIG_PATHS = true;
177
require("ts-mocha");
178

179
const Mocha = require("mocha");
180
const path = require("path");
181

182
const mocha = new Mocha();
183
mocha.addFile(path.resolve(__dirname, "app.spec.ts"));
184
mocha.run((failures) => {
185
  process.on("exit", () => {
186
    process.exit(failures);
187
  });
188
});
189
```
190

191
### With Package Scripts
192

193
```json
194
{
195
  "scripts": {
196
    "test": "ts-mocha test/**/*.spec.ts",
197
    "test:watch": "ts-mocha test/**/*.spec.ts -w --watch-files '**/*.ts'",
198
    "test:typecheck": "ts-mocha --type-check test/**/*.spec.ts"
199
  }
200
}
201
```
202

203
### With Different TypeScript Configurations
204

205
```bash
206
# Different configs for different test suites
207
ts-mocha -p test/unit/tsconfig.json test/unit/**/*.spec.ts
208
ts-mocha -p test/integration/tsconfig.json test/integration/**/*.spec.ts
209
```