istanbuljs / istanbuljs/istanbuljs.github.io

Document steps in nyc execution

Open
#138 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
25
Forks
22
PR merge metrics
No merged PRs in 30d

Description

I'm using nyc to capture code coverage in my TypeScript project, and it's working well (excellent tool). However, now that I want to do more sophisticated things (e.g. merge multiple coverage captures into a single report) I'm finding that there's a total lack of documentation on just what steps nyc takes when it runs, and how to control them.

After a lot of sniffing around the various fragments of doc and `--help` output, I believe the default process is something like the following:

1. Delete contents of `.nyc_output`
2. Run node, loading target .js file
a. Whenever node loads a .js file, instrument it (default is to cache results)
b. Run target code, accumulating coverage data in `__coverage__` object
c. Continue until target project exits
3. Write captured coverage data to a single `.nyc_output/ReallyLongRandomHexFileName.json` file
4. Read `.nyc_output/*.json` files back in (?), merging all data into single representation of coverage
5. Generate each requested report

Did I get this right? If so, how can I control this sequence? For instance, I'd like to:

- Disable deletion of previous `.nyc_output/ReallyLongRandomHexFileName.json` files (`--clean=false` option, I believe, although I'm not sure of the syntax)
- Disable report generation (`--silent` option, I believe)
- Just generate reports from all merged `.nyc_output/ReallyLongRandomHexFileName.json` files (the `report` command, I believe)

If I got all this right, then please consider this a request for documentation; basic issues like this probably get in the way of a lot of potential nyc users. (In theory I could write the doc myself and submit a pull request, but I don't have a good feel for where in the doc tree it should be placed.)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the documented nyc workflow and the existing --help output, focusing on .nyc_output handling, coverage-file merging, cleanup options, silent reporting, and the report command. Compare the proposed sequence with nyc's actual behavior, then document the confirmed steps and controls in the appropriate documentation area; done means a user can understand and reproduce the workflow.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.