or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Grunt Mocha Test

A Grunt plugin that provides a task for running server-side Mocha tests as part of your build process. It offers comprehensive configuration options for test execution including custom reporters, output capture, require cache management, and coverage reporting integration.

Package Information

Package Name: grunt-mocha-test
Package Type: npm
Language: JavaScript
Installation: npm install grunt-mocha-test --save-dev

Core Imports

// Load the plugin into your Gruntfile.js
grunt.loadNpmTasks('grunt-mocha-test');

Basic Usage

module.exports = function(grunt) {
  // Load the grunt-mocha-test plugin
  grunt.loadNpmTasks('grunt-mocha-test');

  grunt.initConfig({
    // Configure a mochaTest task
    mochaTest: {
      test: {
        options: {
          reporter: 'spec',
          captureFile: 'results.txt', // Optionally capture the reporter output to a file
          quiet: false, // Optionally suppress output to standard out (defaults to false)
          clearRequireCache: false // Optionally clear the require cache before running tests (defaults to false)
        },
        src: ['test/**/*.js']
      }
    }
  });

  grunt.registerTask('default', 'mochaTest');
};

Capabilities

Task Registration

The plugin registers a Grunt multi-task that can be configured and executed as part of your build process.

/**
 * Main module export - function that registers the 'mochaTest' task with Grunt
 * @param {Object} grunt - The Grunt instance
 */
function(grunt) {
  // Registers 'mochaTest' as a multi-task with Grunt
  grunt.registerMultiTask('mochaTest', 'Run node unit tests with Mocha', function() {
    // Task implementation handles options, file processing, and Mocha execution
  });
}

Configuration Options

Plugin-Specific Options

Options that are specific to grunt-mocha-test (not standard Mocha options):

interface PluginOptions {
  // Specify a file to capture all output to (will include any output from console.log)
  captureFile?: string;
  
  // true to not output anything to console (normally used with captureFile option)
  quiet?: boolean;
  
  // true to clear the require cache before each test run (useful with watch)
  clearRequireCache?: boolean;
  
  // function to determine which files should remain in cache (only works with clearRequireCache: true)
  clearCacheFilter?: (key: string) => boolean;
  
  // true to prevent the task failing on failed tests (will still fail on other errors)
  noFail?: boolean;
}

Supported Mocha Options

Standard Mocha options that have been tested and are supported:

interface MochaOptions {
  // Test filter pattern
  grep?: string | RegExp;
  
  // User interface (bdd, tdd, qunit, exports)
  ui?: string;
  
  // Test reporter (spec, json, html, etc.)
  reporter?: string;
  
  // Test timeout in milliseconds
  timeout?: number;
  
  // Invert grep matches
  invert?: boolean;
  
  // Ignore global variable leaks
  ignoreLeaks?: boolean;
  
  // Enable growl notifications
  growl?: boolean;
  
  // Acceptable global variables
  globals?: string[];
  
  // Modules to require before running tests
  require?: string | string[] | Function | Array<string | Function>;
  
  // Slow test threshold in milliseconds
  slow?: number;
  
  // Force colored output (use useColors, not colors)
  useColors?: boolean;
  
  // Options passed to the reporter
  reporterOptions?: any;
  
  // Force tests to be asynchronous (no sync tests allowed)
  asyncOnly?: boolean;
  
  // Bail after first test failure (note: not found in test scenarios but supported by Mocha)
  bail?: boolean;
}

Task Configuration Examples

Basic Configuration

Single test target with standard options:

mochaTest: {
  test: {
    options: {
      reporter: 'spec'
    },
    src: ['test/**/*.js']
  }
}

Multi-Target Configuration

Multiple test configurations for different purposes:

mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      require: 'coffee-script/register'
    },
    src: ['test/**/*.js']
  },
  coverage: {
    options: {
      reporter: 'html-cov',
      quiet: true,
      captureFile: 'coverage.html'
    },
    src: ['test/**/*.js']
  },
  'travis-cov': {
    options: {
      reporter: 'travis-cov'
    },
    src: ['test/**/*.js']
  }
}

Using with Compilers

Configuration for CoffeeScript or Babel support:

// CoffeeScript support
mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      require: 'coffee-script/register'
    },
    src: ['test/**/*.coffee']
  }
}

// Babel support
mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      require: 'babel-register'
    },
    src: ['test/**/*.js']
  }
}

// Multiple requires (files and functions)
mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      require: [
        'coffee-script/register',
        './globals.js',
        function() { testVar1 = require('./stuff'); },
        function() { testVar2 = 'other-stuff'; }
      ]
    },
    src: ['test/**/*.coffee']
  }
}

Watch Mode Configuration

Configuration for use with grunt-contrib-watch:

mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      clearRequireCache: true // Important for watch mode
    },
    src: ['test/**/*.js']
  }
},

watch: {
  js: {
    options: {
      spawn: false
    },
    files: '**/*.js',
    tasks: ['mochaTest']
  }
}

Advanced Mocha Options

Configuration for additional Mocha options:

// Reporter options configuration
mochaTest: {
  test: {
    options: {
      reporter: 'xunit',
      reporterOptions: {
        output: 'test-results.xml'
      }
    },
    src: ['test/**/*.js']
  }
}

// Async-only mode (forces all tests to be asynchronous)
mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      asyncOnly: true
    },
    src: ['test/**/*.js']
  }
}

// Colored output control
mochaTest: {
  test: {
    options: {
      reporter: 'spec',
      useColors: true
    },
    src: ['test/**/*.js']
  }
}

Task Execution

The task processes configuration options, manages file sources, handles output capture, and executes Mocha tests with proper error reporting:

// Task execution flow:
// 1. Process options and CLI parameters
// 2. Check for files to test
// 3. Set up output capture (if configured)
// 4. Execute Mocha via MochaWrapper
// 5. Handle results and failures
// 6. Report to Grunt task system

Error Handling

The plugin handles various error scenarios:

No test files: Completes successfully with a warning message
Mocha execution errors: Reports detailed error information
Test failures: Reports failure count and fails task (unless noFail: true)
Uncaught exceptions: Manages exception handlers during test execution

CLI Parameter Override

Command-line parameters can override configuration options:

# Override reporter option
grunt mochaTest --reporter=json

# Override timeout option  
grunt mochaTest --timeout=5000

# Override grep option
grunt mochaTest --grep="integration"

The following options support CLI override: grep, ui, reporter, timeout, invert, ignoreLeaks, growl, globals, require, colors, slow.

Note: For colored output, use the CLI parameter --colors but the configuration option name is useColors.