tap-spec

tap-spec is a TAP (Test Anything Protocol) output formatter that transforms plain TAP test results into a visually appealing, Mocha-style spec reporter format. It serves as a streaming transform tool that can be piped from TAP-producing test runners like tape, providing colored output with symbols, proper indentation, and timing information.

Package Information

• Package Name: tap-spec
• Package Type: npm
• Language: JavaScript
• Installation: npm install tap-spec --save-dev

Core Imports

const tapSpec = require('tap-spec');

For ES modules:

import tapSpec from 'tap-spec';

Basic Usage

Programmatic Usage

const tapSpec = require('tap-spec');
const test = require('tape');

// Create a formatter with default options
const formatter = tapSpec();

// Pipe TAP output through the formatter
test.createStream()
  .pipe(formatter)
  .pipe(process.stdout);

CLI Usage

# Via npm scripts in package.json
{
  "scripts": {
    "test": "tape test.js | tap-spec"
  }
}

# Direct command line usage
tape test/index.js | tap-spec
node test.js | tspec

# With testling
testling test/index.js | tap-spec

Capabilities

TAP Stream Formatter

Creates a transform stream that formats TAP input into spec-style output with colors, symbols, and proper indentation.

/**
 * Creates a TAP formatter transform stream
 * @param {Object} [spec] - Configuration options
 * @param {string} [spec.padding='  '] - String used for indenting output lines
 * @returns {Stream} Transform stream (duplex) that formats TAP input
 */
function tapSpec(spec) {
  // Returns a duplex stream with parser input and formatted output
}

⚠️ Important Note on Process Termination:

When used programmatically, tap-spec may call process.exit(1) directly in the following conditions:

• No test plans are found in the TAP input (likely upstream failure)
• No tests and no assertions are detected (empty test suite or parsing error)

This means the entire Node.js process will terminate. If you need to handle these conditions gracefully in your application, consider:

• Wrapping the stream usage in error handling
• Using the failed property to detect failures before process termination
• Ensuring your TAP input is valid and contains test plans

Configuration Options:

interface TapSpecOptions {
  /** String used for indenting output lines (default: '  ') */
  padding?: string;
}

Stream Properties:

interface TapSpecStream extends Stream {
  /** Set to true when test failures are encountered */
  failed?: boolean;
}

Usage Examples:

const tapSpec = require('tap-spec');

// Default formatting
const defaultFormatter = tapSpec();

// Custom padding
const customFormatter = tapSpec({ padding: '    ' });

// Check for failures
const formatter = tapSpec();
tapInput.pipe(formatter).pipe(process.stdout);

formatter.on('end', () => {
  if (formatter.failed) {
    process.exit(1);
  }
});

CLI Commands

Two equivalent command-line interfaces for formatting TAP output.

# Primary command
tap-spec

# Alias command  
tspec

Both commands:

• Read TAP input from stdin
• Write formatted output to stdout
• Exit with status code 1 on test failures
• Exit with status code 1 if no tests are found

Usage:

# Pipe from test runner
tape test.js | tap-spec
node test.js | tspec

# Via npm scripts
npm test | tap-spec

# With other TAP producers
tap test.js | tap-spec

Output Format

The formatter produces Mocha-style spec output with:

• Test names: Underlined section headers
• Passing assertions: Green checkmark (✓) with dimmed assertion name
• Failing assertions: Red X (✗) with assertion name and error details
• Skipped tests: Cyan dash (-) with test name (for TAP # SKIP directive)
• Comments: Yellow text for TAP comments
• Summary statistics: Total assertions, passing count, failing count, and duration
• Failure details: Detailed error information for failed assertions grouped by test

Example Output:

my test suite

    ✓ should pass this assertion
    ✓ should also pass this one
    ✗ should fail this assertion
    -------------------------
    Error details here...

  Failed Tests: There was 1 failure

    1) my test suite
      ✗ should fail this assertion

  total:     3
  passing:   2
  failing:   1
  duration:  125ms

Error Handling

Stream Behavior:

• Stream sets failed property to true when test failures occur
• Handles TAP parsing errors gracefully through the tap-out dependency

Process Termination (Both Programmatic and CLI):

• Calls process.exit(1) when no test plans are found (upstream failure)
• Calls process.exit(1) when no tests and no assertions are detected
• CLI additionally exits with status code 1 on any test failures

Failure Detection:

• Check the failed property on the returned stream to detect test failures
• Monitor stream events to handle errors before potential process termination

Dependencies

The package relies on several key dependencies that define its functionality:

• tap-out: TAP parser that emits structured events
• through2: Transform stream implementation
• duplexer: Combines readable and writable streams
• chalk: Terminal colors and formatting
• figures: Unicode symbols (checkmarks, X marks)
• lodash: Utility functions for data manipulation
• pretty-ms: Human-readable duration formatting
• repeat-string: String repetition utilities