[Back to README.md](../README.md)

## supporting sourcemaps ##

Sourcemap support by

* [the plugin](#the_plugin)
* [node.js](#node.js)
* [mocha.js](#mocha.js)
* [nyc](#nyc_istanbul.js)

[Finally: How to get sourcemap support working with grunt-nyc-mocha](#finally)

### 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](https://nodejs.org/dist/latest-v12.x/docs/api/cli.html#cli_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 <code>node.opts</code> property, but by the time of writing,
this will not change sourcemap usage for any other framework part of the process.

```javascript
// 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 <code>mocha --help</code>, you can read about a <code>--enable-source-maps</code>
on the [mocha.js site](https://mochajs.org/#-enable-source-maps).  

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

```javascript
// 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](https://www.npmjs.com/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 <code>nyc --help</code>, scroll down and find
* <code>--produce-source-map</code> and
* <code>--source-map</code>

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:  

```javascript
// 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](https://www.npmjs.com/package/source-map-support)
and how to use it. Thanx to <b>Corey Farrell</b>!  

```
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, <code>grunt-nyc-mocha</code> comes bundled
with such script, and enables full blown sourcemap support by adding it to
"nyc.requires" option like below.

```javascript
// 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
        }
      }
    }
  }
};
```