sourcemapsupport.md

Back to README.md

supporting sourcemaps

Sourcemap support by

• the plugin
• node.js
• mocha.js
• nyc

Finally: How to get sourcemap support working with grunt-nyc-mocha

the plugin

grunt-nyc-mocha plugin is a tool which does less more then spawning node processes and passing on configuration data. As such, grunt-nyc-mocha is not directly involved in creating, providing or consuming sourcemaps.

node.js

In v12.12.0, Node.js introduced the flag --enable-source-maps. During the process of evaluating sourcemaps for nyc and mocha, nodes commandline option has turned out to be irrelevant. You are free to to pass it to the spawning process by using the node.opts property, but by the time of writing, this will not change sourcemap usage for any other framework part of the process.

// extract of nyc_mocha.js for package load-grunt-config

module.exports = function ( grunt, options ) {
  return {
    options: {
      node: {
        opts: [ "--enable-source-maps" ]
      }
    },
    mytarget: {
        // ... whatever ...
    }
  }
};

mocha.js

Mocha seems to provide sourcemap support. Somehow. Although not being listed by mocha --help, you can read about a --enable-source-maps on the mocha.js site.

If you want/need to give it a try, you may pass the flag to mocha by using the plugins mocha.opts property as shown below.

// extract of nyc_mocha.js for package load-grunt-config

module.exports = function ( grunt, options ) {
  return {
    options: {
      mocha: {
        opts: [ "--enable-source-maps" ]
      }
    },
    mytarget: {
        // ... whatever ...
    }
  }
};

During my tests, I actually could not change sourcemap behaviour by setting this flag. Please drop me a line, if you manage to force mocha using sourcemaps generated by nyc(s) instrumentation, without using package source-map-support.

nyc istanbul.js

Although nyc provides sourcemap support and you may find commandline options pretty quickly, it turns out ... sourcemap support is not that simple.

Check nyc --help, scroll down and find

• --produce-source-map and
• --source-map

Be aware of sourcemap creation and usage defaulting to true! So there is no need to pass any sourcemap specific settings to grunt-nyc-mocha.

In case you want to switch it off, you can do like so:

// extract of nyc_mocha.js for package load-grunt-config

module.exports = function ( grunt, options ) {
  return {
    options: {
      nyc: {
        opts: [ "--any-valid-nyc-option" ],  // you already know this...
        sourcemap: {
          create: false,
          use:    false
        }
      }
    },
    mytarget: {
        // ... whatever ...
    }
  }
};

Finally

In fact, up to now, I am unable to get sourcemaps up and running by simply using commandline options from node, nyc and mocha - which is rather frustrating.

Finally I found out about source-map-support and how to use it. Thanx to Corey Farrell!

node-tooling.slack.com - Corey Farrell:
... the nyc docs are inaccurate here, --require source-map-support/register does not work.  
to get it working you need to create a script in your project with
require('source-map-support').install({hookRequire: true}); and --require that file.

To avoid polluting each and any of my projects with a script, that simply requires "source-map-support" in the above manner, grunt-nyc-mocha comes bundled with such script, and enables full blown sourcemap support by adding it to "nyc.requires" option like below.

// extract of nyc_mocha.js for package load-grunt-config

module.exports = function ( grunt, options ) {
  return {
    test_and_coverage: {
      src: `./src/test/**/*.spec.js`,                 // test suite to run...
      options: {
        nyc: {
          coverage: {                                 // report nyc coverage results
            dir:          "dist/coverage",            // ... to folder
            reporter:     [ "html", "text-summary" ], // ... using reporters
            check:        true,
            perfile:      true,
            branches:     100,
            functions:    100,
            lines:        100,
            statements:   100
          },
          excludes:       [ "**/*.spec.js" ],         // files and directories to exclude from coverage
          requires:       [ "grunt-nyc-mocha/scripts/sourcemapsupport" ]
        },
        mocha: {
          color:          true                        // force colored output
        }
      }
    }
  }
};