0
# Testem
1

2
Testem is a test-framework agnostic JavaScript testing runner that makes unit testing easy and enjoyable. It supports running tests across multiple browsers, Node.js, and other environments with both interactive TDD (Test-Driven Development) workflows and automated CI (Continuous Integration) execution.
3

4
## Package Information
5

6
- **Package Name**: testem
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install testem -g`
10

11
## Core Imports
12

13
For programmatic usage:
14

15
```javascript
16
const Api = require('testem/lib/api');
17
const Config = require('testem/lib/config');
18
```
19

20
For CLI usage, testem provides a global binary:
21

22
```bash
23
testem
24
```
25

26
## Basic Usage
27

28
### CLI Development Mode (TDD)
29

30
```bash
31
# Start interactive development mode
32
testem
33

34
# With specific configuration file
35
testem -f testem.json
36

37
# Launch specific browsers
38
testem -l Chrome,Firefox
39
```
40

41
### CLI CI Mode
42

43
```bash
44
# Run tests in CI mode
45
testem ci
46

47
# With specific reporter
48
testem ci -R xunit
49

50
# Parallel execution
51
testem ci -P 5
52
```
53

54
### Programmatic API
55

56
```javascript
57
const Api = require('testem/lib/api');
58

59
// Development mode
60
const api = new Api();
61
api.startDev({
62
  port: 7357,
63
  launch: ['Chrome', 'Firefox']
64
});
65

66
// CI mode
67
api.startCI({
68
  reporter: 'tap',
69
  parallel: 3
70
}, (exitCode, error) => {
71
  console.log('Tests completed with exit code:', exitCode);
72
});
73
```
74

75
## Architecture
76

77
Testem is built around several key components:
78

79
- **CLI Interface**: Commander.js-based command line interface with multiple modes (dev, ci, server, launchers)
80
- **Configuration System**: Flexible configuration via JSON, YAML, or JavaScript files with environment-specific options
81
- **Launcher System**: Pluggable browser and process launchers with built-in support for major browsers
82
- **Test Runners**: Framework-agnostic test execution with support for browser and Node.js environments
83
- **Reporter System**: Multiple output formats (TAP, XUnit, dot, TeamCity) for different integration needs
84
- **Server Component**: Express-based server for serving test files and managing client connections via Socket.IO
85

86
## Capabilities
87

88
### Command Line Interface
89

90
Complete CLI for development and CI workflows with support for multiple test modes, browser launching, and configuration options.
91

92
```bash { .api }
93
testem [options]                    # Development mode
94
testem ci [options]                 # Continuous integration mode
95
testem server [options]             # Server-only mode
96
testem launchers                    # List available launchers
97
```
98

99
[Command Line Interface](./cli.md)
100

101
### Configuration Management
102

103
Comprehensive configuration system supporting multiple file formats and extensive customization options for test execution, browser launching, and reporting.
104

105
```javascript { .api }
106
// Configuration file formats supported
107
testem.json      // JSON configuration
108
testem.yml       // YAML configuration
109
testem.js        // JavaScript configuration
110
.testem.json     // Hidden JSON configuration
111
.testem.yml      // Hidden YAML configuration
112
.testem.js       // Hidden JavaScript configuration
113
```
114

115
[Configuration](./configuration.md)
116

117
### Programmatic API
118

119
JavaScript API for integrating testem into build tools, custom workflows, and automated systems.
120

121
```javascript { .api }
122
class Api {
123
  startDev(options, finalizer): void;
124
  startCI(options, finalizer): void;
125
  startServer(options): void;
126
  restart(): void;
127
  setDefaultOptions(defaultOptions): void;
128
}
129

130
class Config {
131
  constructor(appMode, progOptions, config);
132
  read(callback): void;
133
  get(key): any;
134
  set(key, value): void;
135
}
136

137
class Server extends EventEmitter {
138
  constructor(config);
139
  start(callback): Promise<void>;
140
  stop(callback): Promise<void>;
141
}
142
```
143

144
[Programmatic API](./programmatic-api.md)
145

146
### Launcher System
147

148
Pluggable system for launching browsers and processes with built-in support for major browsers and custom launcher definitions.
149

150
```javascript { .api }
151
class Launcher {
152
  constructor(name, settings, config);
153
  start(): Promise<void>;
154
  kill(): Promise<void>;
155
  isProcess(): boolean;
156
  protocol(): string;
157
}
158

159
class LauncherFactory {
160
  constructor(name, settings, config);
161
  create(options): Launcher;
162
}
163
```
164

165
[Launchers](./launchers.md)
166

167
### Test Reporters
168

169
Multiple output formats for test results including TAP, XUnit, dot notation, and TeamCity integration.
170

171
```javascript { .api }
172
// Available reporters
173
const reporters = {
174
  tap: TapReporter,        // Test Anything Protocol
175
  xunit: XUnitReporter,    // XUnit XML format
176
  dot: DotReporter,        // Dot progress indicator
177
  teamcity: TeamCityReporter, // TeamCity integration
178
  dev: DevReporter         // Interactive development UI
179
};
180
```
181

182
[Reporters](./reporters.md)
183

184
## Core Types
185

186
```javascript { .api }
187
interface TestemOptions {
188
  file?: string;              // Configuration file path
189
  port?: number;              // Server port (default: 7357)
190
  host?: string;              // Server host (default: localhost)
191
  launch?: string[];          // Launchers to use
192
  skip?: string[];            // Launchers to skip
193
  debug?: boolean | string;   // Debug mode or log file
194
  test_page?: string | string[]; // Custom test page(s)
195
  growl?: boolean;            // Enable notifications
196
  timeout?: number;           // Browser timeout
197
  parallel?: number;          // Parallel runners (CI mode)
198
  reporter?: string;          // Test reporter
199
  bail_on_uncaught_error?: boolean; // Exit on uncaught errors
200
}
201

202
interface ConfigOptions extends TestemOptions {
203
  framework?: string;         // Test framework (jasmine, qunit, mocha)
204
  src_files?: string[];       // Source files to include
205
  src_files_ignore?: string[]; // Files to exclude
206
  serve_files?: string[];     // Files to serve to browser
207
  watch_files?: string[];     // Files to watch for changes
208
  css_files?: string[];       // CSS files to include
209
  cwd?: string;              // Working directory
210
  config_dir?: string;       // Config directory
211
  launchers?: object;        // Custom launcher definitions
212
  launch_in_dev?: string[];  // Dev mode launchers
213
  launch_in_ci?: string[];   // CI mode launchers
214
  routes?: object;           // Custom routes
215
  proxies?: object;          // Proxy configuration
216
  middleware?: Function[];   // Express middleware
217
  browser_args?: object;     // Browser-specific arguments
218
  browser_paths?: object;    // Custom browser paths
219
  browser_exes?: object;     // Custom browser executables
220
}
221
```