istanbuljs / istanbuljs/istanbuljs.github.io
Document steps in nyc execution
- 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