0
# Testling
1

2
Testling is a command-line tool for running browser-based tests locally in a headless environment. It provides the same functionality as the testling-ci service, allowing developers to test browser JavaScript code locally with TAP (Test Anything Protocol) output and proper exit codes for CI/CD integration.
3

4
## Package Information
5

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

11
## Core Imports
12

13
For the single programmatic API:
14

15
```javascript
16
const unglob = require('testling/lib/unglob');
17
```
18

19
## Basic Usage
20

21
Primary usage is through the command-line interface:
22

23
```bash
24
# Run tests from package.json testling configuration
25
testling
26

27
# Run tests from stdin
28
browserify test.js | testling
29

30
# Run tests from specific directory
31
testling ./test-directory
32

33
# Generate HTML output instead of running browser
34
testling --html
35

36
# Print URL instead of launching browser
37
testling -u
38

39
# Use custom browser command
40
testling -x "chromium --headless"
41
```
42

43
Example test file setup:
44

45
```javascript
46
// test.js
47
var test = require('tape');
48

49
test('example test', function (t) {
50
    t.plan(2);
51
    t.equal(1+1, 2);
52
    t.ok(true);
53
});
54
```
55

56
Example package.json configuration:
57

58
```json
59
{
60
  "testling": {
61
    "files": ["test/*.js"],
62
    "scripts": ["lib/*.js"],
63
    "browsers": ["chrome/latest", "firefox/latest"],
64
    "harness": "tape"
65
  }
66
}
67
```
68

69
## Architecture
70

71
Testling operates through several key components:
72

73
- **CLI Interface**: Primary entry point through `testling` command
74
- **HTTP Server**: Local server for serving test files and handling browser communication
75
- **Browser Integration**: Automatic browser launching and headless execution
76
- **Browserify Integration**: Bundling of test files for browser execution
77
- **TAP Processing**: Test result parsing and formatting
78
- **XHR Communication**: Real-time communication between browser and test runner
79

80
## Capabilities
81

82
### Command Line Interface
83

84
Primary interface for running browser tests locally with various configuration options.
85

86
```bash { .api }
87
testling {DIRECTORY|-} {OPTIONS}
88

89
# OPTIONS:
90
# --html       Generate HTML output instead of launching browser
91
# --no-show    Disable console.log() rendering to document body
92
# -u           Print URL instead of launching browser
93
# -x COMMAND   Launch browser with explicit command
94
# --bcmd COMMAND  Alias for -x (launch browser with explicit command)
95
# --host HOST  Set hostname (default: localhost)  
96
# --port PORT  Set port number
97
# --harness HARNESS  Override test harness from package.json
98
# -h, --help   Show help text
99
```
100

101
**Input Sources:**
102
- Directory path containing package.json with "testling" field
103
- Stdin (when DIRECTORY is "-" or stdin is not a TTY)
104
- Current working directory (default)
105

106
**Output:** TAP (Test Anything Protocol) formatted results to stdout with proper exit codes (0 for success, 1 for failure)
107

108
### Glob Pattern Expansion
109

110
Utility function for expanding glob patterns from testling configuration into resolved file paths.
111

112
```javascript { .api }
113
/**
114
 * Expands glob patterns from testling configuration into resolved file paths
115
 * @param {string} dir - Base directory path
116
 * @param {Object} params - Configuration object with file/script glob patterns
117
 * @param {Array|string} params.files - Glob patterns for files to browserify
118
 * @param {Array|string} params.scripts - Glob patterns for script files
119
 * @param {Function} callback - Callback function (err, expanded)
120
 * @returns {void}
121
 */
122
function unglob(dir, params, callback);
123
```
124

125
**Callback Result:**
126
```javascript { .api }
127
interface ExpandedFiles {
128
  file: string[];        // Resolved file paths for browserifying
129
  script: string[];      // Resolved script file paths  
130
  postScript: string[];  // Reserved for post-script files (unused)
131
}
132
```
133

134
**Usage Example:**
135

136
```javascript
137
const unglob = require('testling/lib/unglob');
138

139
const params = {
140
  files: ['test/*.js', 'spec/*.js'],
141
  scripts: ['lib/*.js']
142
};
143

144
unglob('/path/to/project', params, function(err, expanded) {
145
  if (err) throw err;
146
  
147
  console.log('Files to browserify:', expanded.file);
148
  console.log('Script files:', expanded.script);
149
});
150
```
151

152
### Configuration Schema
153

154
Configuration through package.json "testling" field for test setup and browser specifications.
155

156
```javascript { .api }
157
interface TestlingConfig {
158
  /** Glob patterns for files to browserify and test */
159
  files?: string | string[];
160
  /** Script files to include directly in HTML */
161
  scripts?: string | string[];
162
  /** Custom HTML template file path */
163
  html?: string;
164
  /** Browser specifications (primarily for CI, not used locally) */
165
  browsers?: string[];
166
  /** Custom server command to run alongside tests */
167
  server?: string;
168
  /** Build command to run before testing */
169
  preprocess?: string;
170
  /** Test harness specification (e.g., "mocha-bdd", "tape") */
171
  harness?: string;
172
}
173
```
174

175
**Configuration Examples:**
176

177
```json
178
{
179
  "testling": {
180
    "files": ["test/*.js"],
181
    "harness": "tape"
182
  }
183
}
184
```
185

186
```json
187
{
188
  "testling": {
189
    "files": ["test/**/*.test.js"],
190
    "scripts": ["vendor/jquery.js"],
191
    "html": "test/custom.html",
192
    "harness": "mocha-bdd",
193
    "preprocess": "npm run build"
194
  }
195
}
196
```
197

198
### Test Framework Integration
199

200
Support for multiple test harnesses with automatic detection and TAP output generation.
201

202
```javascript { .api }
203
// Supported harness values:
204
// "tape" - Default/automatic detection
205
// "mocha-bdd" - Mocha with BDD interface
206
// "mocha-tdd" - Mocha with TDD interface  
207
// "mocha-qunit" - Mocha with QUnit interface
208
// Custom harnesses via configuration
209
```
210

211
**Harness Detection:**
212
- Automatic detection based on test code patterns
213
- Manual specification via package.json "testling.harness" field
214
- Dynamic UI configuration for Mocha variants
215

216
**TAP Output:**
217
All supported frameworks generate TAP (Test Anything Protocol) formatted output with proper test counts, assertions, and failure details.
218

219
## Error Handling
220

221
Testling handles various error conditions with appropriate exit codes and error messages:
222

223
- **Missing package.json**: Error message with link to quick start guide (no exit)
224
- **Missing testling field**: Error message explaining required configuration (no exit)
225
- **Browserify failures**: Exit code 1 if browserify process exits with non-zero code
226
- **Browser launch failures**: Exit code 1 with error message and available browser list
227
- **Test failures**: Exit code 1 when TAP results indicate failed tests
228
- **Preprocess failures**: Exit code 1 with error message from preprocess command
229
- **Test success**: Exit code 0 when all tests pass
230
- **Custom browser command failures**: Exit code 1 if custom browser command terminates with non-zero code
231

232
## Browser Environment
233

234
When tests run in the browser, testling creates a Node.js-like environment:
235

236
```javascript { .api }
237
// Global objects available in browser:
238
interface BrowserGlobals {
239
  /** Modified console object for test output */
240
  __testlingConsole: Console;
241
  /** Error handler function */
242
  __testlingErrorHandler: Function;
243
}
244

245
// Mock Node.js objects:
246
interface MockProcess {
247
  stdout: WritableStream;  // Stream for test output
248
  stderr: WritableStream;  // Stream for error output  
249
  exit: Function;          // Function to end test execution
250
  on: Function;            // No-op function
251
}
252
```
253

254
## Dependencies
255

256
Testling requires several external tools and packages:
257

258
**External Requirements:**
259
- **PhantomJS** (or other headless browser): For headless test execution
260
- **Browserify**: For bundling test files (must be globally installed or in node_modules)
261

262
**Note:** The package.json specifies `"browserify": "browser.js"` but this file doesn't exist; the actual browser prelude is at `browser/prelude.js`.
263

264
**Runtime Dependencies:**
265
- `@tapjs/tap-finished` - TAP result parsing
266
- `bouncy` - HTTP proxy server  
267
- `browser-launcher` - Browser detection/launching
268
- `browserify` - JavaScript bundling
269
- `concat-stream` - Stream concatenation
270
- `cross-spawn` - Cross-platform process spawning
271
- `ecstatic` - Static file server
272
- `glob` - File pattern matching
273
- `optimist` - Command-line argument parsing
274
- And others (see package.json for complete list)
275

276
## Platform Support
277

278
- **Node.js**: Requires Node.js >= 0.8
279
- **Browsers**: Supports any browser that browser-launcher can detect
280
- **Headless**: Prefers headless browsers on macOS/Darwin, any available browser on Linux/BSD
281
- **Custom Commands**: Supports custom browser launch commands via `-x` option