From 97cee056f8b9aac9eafd908079214aaeca648168 Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Thu, 21 Mar 2019 16:11:19 +1100 Subject: [PATCH 1/7] [skip ci] Rough draft for `nyc instrument` docs Adds basic usage and key limitations --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 84c0ef157..41d573e2e 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,18 @@ Install custom reporters as a development dependency and you can use the `--repo nyc report --reporter= ``` +## Producing instrumented source + +nyc can produce a set of instrumented source files, suitable for client side deployment, by running: + +```bash +nyc instrument [output] +``` + +Where `input` can be any file or directory within the project root directory. +The `output` directory is optional and can be located anywhere, if it is not set the instrumented code with be sent to `stdout`. + + ## Setting the project root directory nyc runs a lot of file system operations relative to the project root directory. From d4aa9456f726d261a7dc80566bdf0aae4d4fd54a Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Tue, 2 Apr 2019 15:50:42 +1100 Subject: [PATCH 2/7] [skip ci]Update instrument command description, and other relevant doc --- README.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 41d573e2e..8dd89f1e8 100644 --- a/README.md +++ b/README.md @@ -197,14 +197,20 @@ nyc report --reporter= ## Producing instrumented source -nyc can produce a set of instrumented source files, suitable for client side deployment, by running: +The nyc `instrument` command can produce a set of instrumented source files, suitable for client side deployment in end to end testing. +You can create an instrumented version of your source code by running: ```bash nyc instrument [output] ``` -Where `input` can be any file or directory within the project root directory. -The `output` directory is optional and can be located anywhere, if it is not set the instrumented code with be sent to `stdout`. +`` can be any file or directory within the project root directory. +The `[output]` directory is optional and can be located anywhere, if it is not set the instrumented code will be sent to `stdout`. +For example, `nyc instrument . ./output` will copy all files from `.` to `./output` and produce instrumented versions of any source files it finds along the way. + +Run `nyc instrument --help` to display a list of available command options. + +**Note:** `nyc instrument` will not copy the contents of a `.git` folder to the output directory. ## Setting the project root directory @@ -232,7 +238,7 @@ It does this by watching for files that are `require()`'d during the test. When a file is `require()`'d, nyc creates and returns an instrumented version of the source, rather than the original. Only source files that are visited during a test will appear in the coverage report and contribute to coverage statistics. -nyc will instrument all files if the `--all` flag is set. +nyc will instrument all files if the `--all` flag is set or if running `nyc instrument`. In this case all files will appear in the coverage report and contribute to coverage statistics. nyc will only collect coverage for files that are located under `cwd`, and then only `*.js` files or files with extensions listed in the `extension` array. @@ -275,8 +281,8 @@ The `exclude` option has the following defaults settings: These settings exclude `test` and `__tests__` directories as well as `test.js`, `*.test.js`, and `test-*.js` files. Specifying your own exclude property completely replaces these defaults. -**Note:** The exclude list always implicitly contains `**/node_modules/**`, even if not explicitly specified in an overriding `exclude` array. -To reverse this you must add the negated exclude rule `!**/node_modules/`. +**Note:** We always add `**/node_modules/**` to the exclude list, even if not specified in the config. +You can override this by setting the `!**/node_modules/` negated exclude rule. For example, the following config will collect coverage for every file in the `src` directory regardless of whether it is `require()`'d in a test. It will also exclude any files with the extension `.spec.js`. From 0e0a166de73d4e12ae189d53bd4c6dd2e8040e93 Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Thu, 4 Apr 2019 13:38:15 +1100 Subject: [PATCH 3/7] Add `--exclude-node-modules` doc, a few other changes --- README.md | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8dd89f1e8..00db4d227 100644 --- a/README.md +++ b/README.md @@ -197,7 +197,8 @@ nyc report --reporter= ## Producing instrumented source -The nyc `instrument` command can produce a set of instrumented source files, suitable for client side deployment in end to end testing. +The `nyc instrument` command can produce a set of instrumented source files. +These files are suitable for client side deployment in end to end testing. You can create an instrumented version of your source code by running: ```bash @@ -212,13 +213,12 @@ Run `nyc instrument --help` to display a list of available command options. **Note:** `nyc instrument` will not copy the contents of a `.git` folder to the output directory. - ## Setting the project root directory nyc runs a lot of file system operations relative to the project root directory. During startup nyc will look for the *default* project root directory. The *default* project root directory is the first directory found that contains a `package.json` file when searching from the current working directory up. -If nyc fails to find a directory containing a `package.json` file, it will use current working directory as the *default* project root directory. +If nyc fails to find a directory containing a `package.json` file, it will use the current working directory as the *default* project root directory. You can change the project root directory with the `--cwd` option. nyc uses the project root directory when: @@ -281,9 +281,6 @@ The `exclude` option has the following defaults settings: These settings exclude `test` and `__tests__` directories as well as `test.js`, `*.test.js`, and `test-*.js` files. Specifying your own exclude property completely replaces these defaults. -**Note:** We always add `**/node_modules/**` to the exclude list, even if not specified in the config. -You can override this by setting the `!**/node_modules/` negated exclude rule. - For example, the following config will collect coverage for every file in the `src` directory regardless of whether it is `require()`'d in a test. It will also exclude any files with the extension `.spec.js`. @@ -304,6 +301,35 @@ It will also exclude any files with the extension `.spec.js`. **Note:** Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI. To prevent this, wrap each glob in single quotes. +### Including files within `node_modules` + +We always add `**/node_modules/**` to the exclude list, even if not specified in the config. +You can override this by setting `--exclude-node-modules=false`. + +For example, the following config will instrument everything in `lib/` and `node_modules/@my-org/`, except for `node_modules/@my-org/something/unwanted.js`. +All other files in `node_modules` are filtered out by the include rules. +The exclude rules prevent nyc instrumenting test files and `node_modules/@my-org/something/unwanted.js` + +```json +{ + "nyc": { + "all": true, + "include": [ + "lib/**", + "node_modules/@my-org/**" + ], + "exclude": [ + "node_modules/@my-org/something/unwanted.js", + "**/test/**" + ], + excludeNodeModules: false + } +} +``` + +**Note:** You can also include `node_modules` files with a negated exclude rule `!**/node_modules/@my-org`. +However you won't be able to use any further exclude rules such as `node_modules/@my-org/something/unwanted.js` with this method. + ## Require additional modules The `--require` flag can be provided to `nyc` to indicate that additional From 7ea21b3056e0a01d1aecb67a166121a86ccc3790 Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Thu, 4 Apr 2019 13:39:45 +1100 Subject: [PATCH 4/7] [skip ci]Update instrument doc to reflect lack of full copy --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 00db4d227..48d01b788 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,8 @@ nyc instrument [output] `` can be any file or directory within the project root directory. The `[output]` directory is optional and can be located anywhere, if it is not set the instrumented code will be sent to `stdout`. -For example, `nyc instrument . ./output` will copy all files from `.` to `./output` and produce instrumented versions of any source files it finds along the way. +For example, `nyc instrument . ./output` will produce instrumented versions of any source files it finds in `.` and store them in `./output`. + Run `nyc instrument --help` to display a list of available command options. From 7a115215138ea46a6aab0b57fcd143cd91cc3055 Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Thu, 4 Apr 2019 13:58:04 +1100 Subject: [PATCH 5/7] [skip ci]mention the `--delete` option --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 48d01b788..3b3a49d78 100644 --- a/README.md +++ b/README.md @@ -209,8 +209,8 @@ nyc instrument [output] The `[output]` directory is optional and can be located anywhere, if it is not set the instrumented code will be sent to `stdout`. For example, `nyc instrument . ./output` will produce instrumented versions of any source files it finds in `.` and store them in `./output`. - -Run `nyc instrument --help` to display a list of available command options. +Any existing output can be removed by specifying the `--delete` option. +Run `nyc instrument --help` to display a full list of available command options. **Note:** `nyc instrument` will not copy the contents of a `.git` folder to the output directory. From 096d111d77cc88bd54325a1be59b604de75f5c59 Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Fri, 5 Apr 2019 10:29:01 +1100 Subject: [PATCH 6/7] [skip ci] documentation fixes --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3b3a49d78..c45c3146e 100644 --- a/README.md +++ b/README.md @@ -307,9 +307,9 @@ To prevent this, wrap each glob in single quotes. We always add `**/node_modules/**` to the exclude list, even if not specified in the config. You can override this by setting `--exclude-node-modules=false`. -For example, the following config will instrument everything in `lib/` and `node_modules/@my-org/`, except for `node_modules/@my-org/something/unwanted.js`. -All other files in `node_modules` are filtered out by the include rules. -The exclude rules prevent nyc instrumenting test files and `node_modules/@my-org/something/unwanted.js` +For example, in the following config, `"excludeNodeModules: false"` will prevent `node_modules` from being added to the exclude rules. +The set of include rules then restrict nyc to only consider instrumenting files found under the `lib/` and `node_modules/@my-org/` directories. +The exclude rules then prevent nyc instrumenting anything in a `test` folder and the file `node_modules/@my-org/something/unwanted.js`. ```json { @@ -323,7 +323,7 @@ The exclude rules prevent nyc instrumenting test files and `node_modules/@my-org "node_modules/@my-org/something/unwanted.js", "**/test/**" ], - excludeNodeModules: false + "excludeNodeModules": false } } ``` From 5ace41b958d2033bc582b64138dd7bc45a370468 Mon Sep 17 00:00:00 2001 From: Andrew Finlay Date: Fri, 5 Apr 2019 11:37:45 +1100 Subject: [PATCH 7/7] [skip ci] don't encourage using neg excludes for `node_modules` inclusion --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index c45c3146e..ee2b8810e 100644 --- a/README.md +++ b/README.md @@ -328,9 +328,6 @@ The exclude rules then prevent nyc instrumenting anything in a `test` folder and } ``` -**Note:** You can also include `node_modules` files with a negated exclude rule `!**/node_modules/@my-org`. -However you won't be able to use any further exclude rules such as `node_modules/@my-org/something/unwanted.js` with this method. - ## Require additional modules The `--require` flag can be provided to `nyc` to indicate that additional