From fa59a8dd2949fb097f75f677c6c966cf7bd59fb0 Mon Sep 17 00:00:00 2001
From: umuoy1 <burningdian@gmail.com>
Date: Fri, 17 Apr 2026 01:04:34 +0800
Subject: [PATCH] doc: clarify filtered test behavior

- fix outdated `npm run unit` examples
- explain that `--filter` affects test execution, not compilation scope
- note that `npm test --filter=...` still triggers the default full rebuild
---
 CONTRIBUTING.md     | 29 +++++++++++++++++++----------
 unit-test/README.md | 22 ++++++++++++++++------
 2 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6485f4279..663fc2304 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,27 +70,37 @@ npm test --NAPI_VERSION=X
 
 where X is the version of Node-API you want to target.
 
-To run a specific unit test, filter conditions are available
+To run a subset of the test suite, filter conditions are available.
+The `--filter` option limits which JavaScript test modules are executed by
+`node test`. The default `pretest` step is still `node-gyp rebuild -C test`,
+so `npm test --filter=...` still performs a full rebuild of the test addon
+targets before the filtered tests run.
 
 **Example:**
-  compile and run only tests on objectwrap.cc and objectwrap.js
+  perform the default test rebuild, then run only the `objectwrap` test module
   ```
-    npm run unit --filter=objectwrap
+    npm test --filter=objectwrap
   ```
 
-Multiple unit tests cane be selected with wildcards
+Multiple test modules can be selected with wildcards.
 
 **Example:**
-compile and run all test files ending with "reference" -> function_reference.cc, object_reference.cc, reference.cc
+perform the default test rebuild, then run all test modules ending with
+`reference`:
+`function_reference`, `object_reference`, and `reference`
  ```
-    npm run unit --filter=*reference
+    npm test --filter=*reference
  ```
 
-Multiple filter conditions can be joined to broaden the test selection
+Multiple filter conditions can be joined to broaden the test selection.
 
 **Example:**
- compile and run all tests under folders threadsafe_function and typed_threadsafe_function and also the objectwrap.cc file
-    npm run unit --filter='*function objectwrap'
+ perform the default test rebuild, then run all tests under
+ `threadsafe_function` and `typed_threadsafe_function`, and also the
+ `objectwrap` test module
+ ```
+    npm test --filter='*function objectwrap'
+ ```
 
 As an alternative, `ninja` can be used to build the tests. Please
 follow the instructions in [Build with ninja](doc/contributing/build_with_ninja.md).
@@ -203,4 +213,3 @@ The downside of this approach is the following:
 authors might not find the right patterns and instead implement things themselves
 - There might be greater friction for the Node-API WG in evolving APIs since the
 ecosystem would have taken dependencies on the API shape of **node-addon-api**
-
diff --git a/unit-test/README.md b/unit-test/README.md
index e10b1c448..2dfd5abfb 100644
--- a/unit-test/README.md
+++ b/unit-test/README.md
@@ -1,11 +1,17 @@
 
 # Enable running tests with specific filter conditions:
 
+The `--filter` option limits which test modules are executed by `node test`.
+The default `pretest` step is still `node-gyp rebuild -C test`, so
+`npm test --filter=...` still performs a full rebuild of the test addon
+targets before the filtered tests run.
+
 ### Example:
 
-  - compile and run only tests on objectwrap.cc and objectwrap.js
+  - perform the default test rebuild, then run only the `objectwrap`
+    test module
 ```
-    npm run test --filter=objectwrap
+    npm test --filter=objectwrap
 ```
 
 
@@ -13,16 +19,20 @@
 
 ### Example:
 
-  - compile and run all tests files ending with reference -> function_reference.cc object_reference.cc reference.cc
+  - perform the default test rebuild, then run all test modules ending
+    with `reference`
+    (`function_reference`, `object_reference`, and `reference`)
 ```
-    npm run test --filter=*reference
+    npm test --filter=*reference
 ```
 
 # Multiple filter conditions are also allowed
 
 ### Example:
 
-  - compile and run all tests under folders threadsafe_function and typed_threadsafe_function and also the objectwrap.cc file
+  - perform the default test rebuild, then run all tests under
+    `threadsafe_function` and `typed_threadsafe_function`, and also the
+    `objectwrap` test module
 ```
-    npm run test --filter='*function objectwrap'
+    npm test --filter='*function objectwrap'
 ```