Debian Codegraph @

nyc/docs/profiling.md

raw
1 # Profiling:
2
3 The self-coverage tool can provide a [fairly interesting information on how nyc performs](https://github.com/bcoe/nyc/pull/101#issuecomment-165337057) in real world test suites. Doing this is a bit involved, detailed steps follow.
4
5 *Note:* This assumes your locally cloned development version of `nyc` is in `/user/dev/nyc`, and that you are profiling against the AVA test suite in `/user/dev/ava`. Adapt as required.
6
7 ## Initial Setup (NYC)
8
9 We must use `npm link`, and ensure we have fresh "self-coverage" scripts generated.
10
11 ```sh
12 # Go to the local clone of nyc
13 cd /user/dev/nyc
14
15 # Link the local clone globally
16 npm link
17
18 # Create the self-coverage instrumented files
19 node ./build-self-coverage
20 ```
21
22 ## Initial Setup (Test Project)
23
24 ```sh
25 # CD to the real world test suite you want to profile against
26 cd /user/dev/ava
27
28 # Link the globally linked nyc into your local node_modules
29 npm link nyc
30 ```
31
32 This will likely not work with `tap --coverage`, since tap will try to use it's own older copy of nyc instead of your globally linked one. Modify the test script in your test project so it uses the `nyc` binary directly, and disable `tap`s version with the `--no-cov` flag:
33
34 `package.json`:
35
36 ```json
37 {
38 "scripts" : {
39 "test": "nyc tap --no-cov test/*.js"
40 }
41 }
42 ```
43
44 ## Each Run
45
46 ```sh
47 # Clear existing self coverage (`trash` ~== `rm -rf`)
48 cd /user/dev/nyc
49 trash ./.self_coverage
50
51 # Clear the `.nyc_cache` folder in your test project
52 cd /user/dev/ava
53 trash ./.nyc_cache
54
55 # Run your test suite
56 npm test
57
58 # Go back to the `nyc` folder and create a self-coverage report
59 cd /user/dev/nyc
60 npm run report
61 ```
62
63 A detailed profile of your test run now exists in `/user/dev/nyc/coverage/lcov-report`
64
65 *Note:* `trash` is a safer version of `rm -rf`. Install via `npm i -g trash-cli`. [More info](https://github.com/sindresorhus/guides/blob/master/how-not-to-rm-yourself.md).
66
67 ## WARNING: Self coverage can cause some confusing problems.
68
69 If `index.covered.js` exists, it will be used instead of the normal file. This means your changes to `index.js` will not have an effect until you recreate or delete the self coverage files. Unless you are trying to do some profiling, you should probably delete them so the regular files are used.
70
71 You can delete the self coverage scripts and use the regular ones as follows:
72
73 ```sh
74 # Go to nyc directory and remove the self coverage scripts
75 cd /user/dev/nyc
76 npm run clean
77 ```
78
79 You can rerun `node ./build-self-coverage` scripts as desired to re-enable self-coverage.