Adding support for single file instrumentation via stdio

[JohnBuchanan]

Adding support for single file instrumentation via command line to stdio output. Adding NPE guards in jscoverage.js report viewer.

[tntim96]

Thanks. I'll take a look. I'll have to add a few things - feel free to help:

• Update for modified code-base (merge breaks compilation)
• Unit tests to keep the coverage up
• Acceptance test
• Documentation in the manual on how and why to use this
• An example (something like this)

[tntim96]

I've merged and the only tasks left are the documentation and an example. What's the use case so I can add an example and why this is useful? Without these I'll have to revert the changes.

[JohnBuchanan]

The use case is for a file based unit testing harness in a large, complicated codebase that is impractical or impossible to process in its entirety, or even a folder at a time.

Each target script file is requested and imported by the test file, and the import strategy determines whether or not to instrument the file based on configuration/input parameters to the runner. As these happen in the engine memory space, the effect is cumulative, and collects coverage statistics for every file imported by any tests run.

This provides a nice silo effect for run isolation: rather than reporting on all files in a folder, it reports only on files exercised by a subset of tests, making it easier to identify accidental versus intentional coverage.

[JohnBuchanan]

The example is:

java -jar JSCover.jar FileToInstrument.js -io

This outputs the instrumentation to stdio, which gives you shell/piping support for, e.g. integration with a command line automation/CI system with or without writing to file. You can, e.g.

java -jar JSCover.jar FileToInstrument.js -io > InstrumentedFile.js

Or read it directly into memory by any language or engine that can process std io; Or continue processing it with standard command tools, grep, sed, awk, etc.

[tntim96]

Sounds OK (I can leave in if it's required for you). Can you think of a small example that goes from instrumented file to a coverage report or JSON coverage file that demonstrates the usefulness to others?

This provides a nice silo effect for run isolation: rather than reporting on all files in a folder, it reports only on files exercised by a subset of tests, making it easier to identify accidental versus intentional coverage

That would be great to demonstrate. Would you be able to help create a sample or describe your test harness set-up that does this?

impossible to process in its entirety, or even a folder at a time

That can be probably be handled by the --only-instrument-reg=URL switch.

[JohnBuchanan]

You're probably correct that the paths could be handled with the regex pattern, but we have over 500 modules, each with their own patterns. It's much simpler and cleaner to deal with in-memory representations of each file, as it's requested.

I'll try to craft an example of isolating files, but it's difficult given our setup. The runner operates on files directly in each script engine, without a browser or web server. Isolating files, directories, or criteria-matching tests is built into the runner, so the value here is in being able to specify a single new flag that changes the dependency import behavior from non-instrumented to instrumented, and executing the same exact run, except with intent to capture coverage statistics instead of failures.

[tntim96]

It's much simpler and cleaner to deal with in-memory representations of each file, as it's requested.

OK.

I'll try to craft an example of isolating files, but it's difficult given our setup.

Thanks. I can leave it in with minimal documentation.