Testling

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.

Package Information

• Package Name: testling
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -g testling

Core Imports

For the single programmatic API:

const unglob = require('testling/lib/unglob');

Basic Usage

Primary usage is through the command-line interface:

# Run tests from package.json testling configuration
testling

# Run tests from stdin
browserify test.js | testling

# Run tests from specific directory
testling ./test-directory

# Generate HTML output instead of running browser
testling --html

# Print URL instead of launching browser
testling -u

# Use custom browser command
testling -x "chromium --headless"

Example test file setup:

// test.js
var test = require('tape');

test('example test', function (t) {
    t.plan(2);
    t.equal(1+1, 2);
    t.ok(true);
});

Example package.json configuration:

{
  "testling": {
    "files": ["test/*.js"],
    "scripts": ["lib/*.js"],
    "browsers": ["chrome/latest", "firefox/latest"],
    "harness": "tape"
  }
}

Architecture

Testling operates through several key components:

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

Capabilities

Command Line Interface

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

testling {DIRECTORY|-} {OPTIONS}

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

Input Sources:

• Directory path containing package.json with "testling" field
• Stdin (when DIRECTORY is "-" or stdin is not a TTY)
• Current working directory (default)

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

Glob Pattern Expansion

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

/**
 * Expands glob patterns from testling configuration into resolved file paths
 * @param {string} dir - Base directory path
 * @param {Object} params - Configuration object with file/script glob patterns
 * @param {Array|string} params.files - Glob patterns for files to browserify
 * @param {Array|string} params.scripts - Glob patterns for script files
 * @param {Function} callback - Callback function (err, expanded)
 * @returns {void}
 */
function unglob(dir, params, callback);

Callback Result:

interface ExpandedFiles {
  file: string[];        // Resolved file paths for browserifying
  script: string[];      // Resolved script file paths  
  postScript: string[];  // Reserved for post-script files (unused)
}

Usage Example:

const unglob = require('testling/lib/unglob');

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

unglob('/path/to/project', params, function(err, expanded) {
  if (err) throw err;
  
  console.log('Files to browserify:', expanded.file);
  console.log('Script files:', expanded.script);
});

Configuration Schema

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

interface TestlingConfig {
  /** Glob patterns for files to browserify and test */
  files?: string | string[];
  /** Script files to include directly in HTML */
  scripts?: string | string[];
  /** Custom HTML template file path */
  html?: string;
  /** Browser specifications (primarily for CI, not used locally) */
  browsers?: string[];
  /** Custom server command to run alongside tests */
  server?: string;
  /** Build command to run before testing */
  preprocess?: string;
  /** Test harness specification (e.g., "mocha-bdd", "tape") */
  harness?: string;
}

Configuration Examples:

{
  "testling": {
    "files": ["test/*.js"],
    "harness": "tape"
  }
}

{
  "testling": {
    "files": ["test/**/*.test.js"],
    "scripts": ["vendor/jquery.js"],
    "html": "test/custom.html",
    "harness": "mocha-bdd",
    "preprocess": "npm run build"
  }
}

Test Framework Integration

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

// Supported harness values:
// "tape" - Default/automatic detection
// "mocha-bdd" - Mocha with BDD interface
// "mocha-tdd" - Mocha with TDD interface  
// "mocha-qunit" - Mocha with QUnit interface
// Custom harnesses via configuration

Harness Detection:

• Automatic detection based on test code patterns
• Manual specification via package.json "testling.harness" field
• Dynamic UI configuration for Mocha variants

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

Error Handling

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

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

Browser Environment

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

// Global objects available in browser:
interface BrowserGlobals {
  /** Modified console object for test output */
  __testlingConsole: Console;
  /** Error handler function */
  __testlingErrorHandler: Function;
}

// Mock Node.js objects:
interface MockProcess {
  stdout: WritableStream;  // Stream for test output
  stderr: WritableStream;  // Stream for error output  
  exit: Function;          // Function to end test execution
  on: Function;            // No-op function
}

Dependencies

Testling requires several external tools and packages:

External Requirements:

• PhantomJS (or other headless browser): For headless test execution
• Browserify: For bundling test files (must be globally installed or in node_modules)

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

Runtime Dependencies:

• @tapjs/tap-finished - TAP result parsing
• bouncy - HTTP proxy server
• browser-launcher - Browser detection/launching
• browserify - JavaScript bundling
• concat-stream - Stream concatenation
• cross-spawn - Cross-platform process spawning
• ecstatic - Static file server
• glob - File pattern matching
• optimist - Command-line argument parsing
• And others (see package.json for complete list)

Platform Support

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