What is instrumentation in nyc istanbul?

Question

What is instumentation used in nyc?

nyc's instrument command can be used to instrument source files outside of the context of your unit-tests:

I assume it will do coverage outside unit-testing. I tried it with

nyc instrument src coverage/instrument

then run the application and tries hitting an endpoint

npm start

but when I do above, it doesn't generate a file in nyc_output thus can't report anything.

Do I have to finish the nyc instrument command? how to do so?

Answer 1

nyc instrument is used to instrument your code. It produces output that, when ran, will gather coverage data. This is useless unless you actually do something with that data... like report it or use it somehow. When you run a file that has been instrumented, it will store coverage data in global.__coverage__ I believe. You can then do what you want with that data. So, you could create a reporter that will run the instrumented file, then take a look at global.__coverage__ to see what the coverage is like. Simply running an instrumented file won't generate any output

To see what the coverage is of a file that has been instrumented, you can either create your own reporter where you require the instrumented file, then take a look at global.__coverage__ or you could run the nyc command to generate coverage data like normal.

Here are a few examples:

Let's say you have a file file.js that you want to check the coverage of and you've run the command:

nyc instrument file.js > file_instrumented.js

Now, you'll have a file named file_instrumented.js that has all the code necessary to generate code coverage.

If I run that file with node file_instumented.js nothing happens... other than the file executes same as file.js

But, if I create a file named coverage.js with this code:

require("./file_instrumented.js");
console.log(global.__coverage__)

Then, I run node coverage.js you'll be able to see coverage data. You can then output whatever data you want. It's sort of a lower level access to the coverage data

If you want to generate a report in nyc_output you'll need to use the nyc command against the instrumented file. For example, something like this:

nyc --reporter=text --report-dir=./nyc_output node file_instrumented.js

A command like this would work too if you made the file_instrumented.js file executable:

nyc --reporter=text --report-dir=./nyc_output file_instrumented.js

However, if we try to run that same command against the original file.js like this:

nyc --reporter=text --report-dir=./nyc_output node file.js

You'll see that we get a report that shows no coverage. And this is because the file.js file isn't instrumented and therefore doesn't give the nyc reporter any data to report

You are correct that using nyc instrument will do coverage outside unit-testing frameworks as I've demonstrated above. It's a bit confusing because the docs aren't as clear as they should be. There are no good examples that I could find on how to get coverage of files outside of test frameworks so I figured this all out by looking at the source code for nyc as well as some of the testing frameworks.

The thing is that the testing frameworks instrument the file for you so when you run a command like this using the Mocha testing framework for example:

nyc --reporter=text mocha --ui bdd test.js

What's happening is:

• nyc is executing mocha...
• then mocha is instrumenting your code for you behind the scenes (correction - as per @Dining Philosopher - it looks like it’s not actuallymocha that is instrumenting your code. It’s actually nyc that instruments the code because it knows about mocha. Note: I haven’t verified this in code)
• then mocha is running that instrumented code
• which runs tests while collecting coverage data
• which gives nyc the global.__coverage__ that it needs to generate a report
• finally, nyc uses that data to output a report in your nyc_output folder

Hope this all makes sense...