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?

Ballenger

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...

Ide

This explains the problem I am currently having. Then I saw the option --instrument of nyc with the doc-string should nyc handle instrumentation and thought that should help to get on-the-fly instrumentation, but it does not seem to be the case. Any idea what that is good then for? – Maximomaximum

I haven't dug into the nyc source, but I believe your statement "then mocha is instrumenting your code for you behind the scenes" is false. Mocha does not know what instrumenting is. Since your edit queue is full I've added my own answer. – Fairchild

Answer 2

In the nyc v15.1.0, we can create the report without instrumented file, just run

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

is worked !!

But i think we if we want to get the running time report, we still need the instrumented file to run

Pedropedrotti

Hi, I have tried what you said, but it returns 0 for file. – Manriquez

Answer 3

Instrumentation in this context means adding some code in between the original code. You can see this with a simple nyc instrument example.js. The output looks but confusing but is just valid javascript that still does the same things as the original program.

The important thing to know is that the added code has some side-effects. In the case of nyc the added code modifies the global.__coverage__ object (thanks Ray Perea).

Confusingly, nyc only instruments code that is tested (it knows about some testing frameworks such as mocha). To override this behavior, pass the --all flag to nyc.

A simple example running instrumented javascript:

nyc --all node example.js

Where example.js contains some uninstrumented javascript (e.g. console.log("Hello world"). This will instrument all javascript files (nested) in the current directory and report their coverage when running node example.js.

P.S. I would have edited Ray Perea's answer but their edit queue is full.

Fairchild