test(e2e): stress native watcher with safeTime canary

.github/workflows/test.yml

@@ -232,6 +232,63 @@ jobs:
         if: matrix.test_script == 'test'
         run: pnpm run test:vscode
 
+  # ======== stress test with RSPACK_WATCHER_TRACE ========
+  # macOS polling=on × unique-dir on/off × 20 rounds × node 22/24 = 80 jobs.
+  # We focus on the residual nativeWatcher flake (polling=off failures are
+  # unrelated chokidar issues already explained). All jobs set
+  # RSPACK_WATCHER_TRACE=1 so failing jobs dump the full event pipeline log.
+  stress-restart:
+    needs: prepare
+    if: needs.prepare.outputs.changed == 'true'
+    runs-on: macos-14
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        node_version: ['22', '24']
+        round:
+          [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
+        unique_dir: ['on', 'off']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+
+      - name: Setup Node.js ${{ matrix.node_version }}
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node_version }}
+          cache: 'pnpm'
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+
+      - name: Stress all watch tests
+        env:
+          STRESS_NO_UNIQUE_DIR: ${{ matrix.unique_dir == 'off' && '1' || '' }}
+          RSPACK_WATCHER_TRACE_FILE: /tmp/rspack-watcher-trace.log
+        run: cd e2e && pnpm exec rstest run watch/
+
+      - name: Dump rspack-watcher trace on failure
+        if: failure()
+        run: |
+          if [ ! -f /tmp/rspack-watcher-trace.log ]; then
+            echo "(trace file not present)"
+            exit 0
+          fi
+          echo '===== trace stats ====='
+          wc -l /tmp/rspack-watcher-trace.log
+          echo '===== js_event_handle calls (Rust → JS dispatch boundary) ====='
+          grep -a "js_event_handle" /tmp/rspack-watcher-trace.log || true
+          echo '===== ALL fixture-scoped events (incl rstest-temp to inspect dispatch noise) ====='
+          grep -aE "fixtures-test-(0|dynamic)-module" /tmp/rspack-watcher-trace.log | grep -v "node_modules" || true
+          echo '===== END trace ====='
+
   # ======== codspeed ========
   # Temporarily disabled: CodSpeed runner quota exhausted.
   # Re-enable once quota resets.

e2e/filter/fixtures-related-dynamic/rstest.config.mts

@@ -1,11 +1,3 @@
 import { defineConfig } from '@rstest/core';
 
-export default defineConfig({
-  tools: {
-    rspack: {
-      watchOptions: {
-        aggregateTimeout: 10,
-      },
-    },
-  },
-});
+export default defineConfig({});

e2e/scripts/index.ts

@@ -241,6 +241,16 @@ export async function runRstestCli({
   };
 }
 
+// macOS only (gated by STRESS_NO_UNIQUE_DIR for the stress matrix):
+// give every prepareFixtures call a fresh sibling directory and expose it
+// via an in-repo symlink. Reusing the same distPath across retries makes
+// file watchers observe a Delete+Create batch on the same path, which the
+// macOS FSEvents per-path ring buffer can replay onto later watcher streams
+// as spurious change events. A fresh path has no FSEvents history.
+let fixtureRunCounter = 0;
+const uniqueSuffix = () =>
+  `-r${process.pid}-${++fixtureRunCounter}-${Date.now().toString(36)}`;
+
 export async function prepareFixtures({
   fixturesPath,
   fixturesTargetPath,
@@ -249,7 +259,14 @@ export async function prepareFixtures({
   fixturesTargetPath?: string;
 }) {
   const root = path.dirname(fixturesPath);
-  const distPath = fixturesTargetPath || path.resolve(`${fixturesPath}-test`);
+  const exposedPath =
+    fixturesTargetPath || path.resolve(`${fixturesPath}-test`);
+
+  const useUniqueDir =
+    process.platform === 'darwin' && process.env.STRESS_NO_UNIQUE_DIR !== '1';
+  const distPath = useUniqueDir
+    ? `${exposedPath}${uniqueSuffix()}`
+    : exposedPath;
 
   // Clean up any leftover fixtures from previous runs
   // On Windows, file handles may not be fully released, causing EBUSY errors
@@ -261,6 +278,14 @@ export async function prepareFixtures({
       maxRetries: 10,
       retryDelay: 500,
     });
+    if (distPath !== exposedPath) {
+      fs.rmSync(exposedPath, {
+        recursive: true,
+        force: true,
+        maxRetries: 10,
+        retryDelay: 500,
+      });
+    }
   } catch (err) {
     if (process.platform !== 'win32') {
       throw err;
@@ -278,6 +303,11 @@ export async function prepareFixtures({
     filter: (src) => !path.basename(src).startsWith('fixtures-test-'),
   });
 
+  if (distPath !== exposedPath) {
+    await fs.promises.mkdir(path.dirname(exposedPath), { recursive: true });
+    await fs.promises.symlink(distPath, exposedPath, 'dir');
+  }
+
   const update = (
     relativePath: string,
     content: string | ((raw: string) => string),

e2e/watch/fixtures-dynamic/rstest.config.mts

@@ -1,11 +1,3 @@
 import { defineConfig } from '@rstest/core';
 
-export default defineConfig({
-  tools: {
-    rspack: {
-      watchOptions: {
-        aggregateTimeout: 10,
-      },
-    },
-  },
-});
+export default defineConfig({});

e2e/watch/fixtures-setup/rstest.config.mts

@@ -4,11 +4,4 @@ export default defineConfig({
   passWithNoTests: true,
   setupFiles: ['./rstest.setup.ts'],
   exclude: ['**/node_modules/**', '**/dist/**'],
-  tools: {
-    rspack: {
-      watchOptions: {
-        aggregateTimeout: 10,
-      },
-    },
-  },
 });

e2e/watch/fixtures-shortcuts/rstest.config.mts

@@ -6,11 +6,4 @@ process.stdin.setRawMode = () => process.stdin;
 export default defineConfig({
   reporters: ['default'],
   disableConsoleIntercept: true,
-  tools: {
-    rspack: {
-      watchOptions: {
-        aggregateTimeout: 10,
-      },
-    },
-  },
 });

e2e/watch/fixtures/rstest.config.mts

@@ -1,11 +1,3 @@
 import { defineConfig } from '@rstest/core';
 
-export default defineConfig({
-  tools: {
-    rspack: {
-      watchOptions: {
-        aggregateTimeout: 10,
-      },
-    },
-  },
-});
+export default defineConfig({});

package.json

@@ -44,5 +44,10 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0",
     "pnpm": ">=10.34.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "@rspack/core": "npm:@rspack-canary/core@2.0.7-canary-a310bbfa-20260603233709"
+    }
   }
 }

packages/core/src/cli/commands.ts

@@ -784,7 +784,7 @@ export const runRest = async ({
         process.off('unhandledRejection', unexpectedlyExitHandler);
       });
 
-      watchFilesForRestart({
+      await watchFilesForRestart({
         rstest,
         options,
         filters,

packages/core/src/core/plugins/entry.ts

@@ -56,8 +56,14 @@ export const pluginEntryWatch: (params: {
         };
 
         config.watchOptions ??= {};
-        // FIXME: Temporarily default to 5 to debounce rerun in watch mode.
-        config.watchOptions.aggregateTimeout = 5;
+        // Default aggregate window for watch-mode rerun debouncing. On macOS
+        // with the rspack native watcher this also needs to be long enough
+        // for the FSEvent → vnode cache invalidation cycle to complete
+        // before rspack stats the changed file (otherwise the rebuild reads
+        // stale content and rstest reports "No test files need re-run").
+        // 100 ms is the minimum value that survives macos-14 GHA runners.
+        // User configs can override via `tools.rspack.watchOptions`.
+        config.watchOptions.aggregateTimeout = 100;
         // TODO: rspack should support `(string | RegExp)[]` type
         // https://github.com/web-infra-dev/rspack/issues/10596
         config.watchOptions.ignored = castArray(
@@ -79,6 +85,9 @@ export const pluginEntryWatch: (params: {
           '**/*.snap',
         );
 
+        config.experiments ??= {};
+        config.experiments.nativeWatcher = true;
+
         const configFilePath = context.projects.find(
           (project) => project.environmentName === environment.name,
         )?.configFilePath;

packages/core/src/core/restart.ts

@@ -88,11 +88,19 @@ export async function watchFilesForRestart({
   }
 
   const root = rstest.context.rootPath;
+  // STRESS_NO_POLLING is a temporary stress-test gate; default is polling ON.
+  const usePolling = process.env.STRESS_NO_POLLING !== '1';
   const watcher = await createChokidar(configFilePaths, root, {
     // do not trigger add for initial files
     ignoreInitial: true,
     // If watching fails due to read permissions, the errors will be suppressed silently.
     ignorePermissionErrors: true,
+    // chokidar v5 dropped fsevents and relies on Node's fs.watch(), which is
+    // unreliable for single-file watching on macOS (kqueue silently drops
+    // change events). Poll the small set of config files instead — 100ms is
+    // fast enough for restarts while adding negligible CPU.
+    usePolling,
+    interval: 100,
     ...watchOptions,
   });
 

packages/core/src/utils/watchFiles.ts

@@ -35,5 +35,10 @@ export async function createChokidar(
     }
   }
 
-  return chokidar.watch(Array.from(watchFiles), options);
+  const watcher = chokidar.watch(Array.from(watchFiles), options);
+  // Await the initial scan so callers can rely on events being emitted for
+  // subsequent modifications — chokidar may drop events before 'ready',
+  // especially on macOS where FSEvents setup is async.
+  await new Promise<void>((resolve) => watcher.once('ready', () => resolve()));
+  return watcher;
 }

packages/core/tests/core/__snapshots__/rsbuild.test.ts.snap

@@ -1738,6 +1738,9 @@ exports[`prepareRsbuild > should generate rspack config correctly in watch mode
   "context": "<ROOT>/packages/core",
   "devtool": "nosources-source-map",
   "entry": [Function],
+  "experiments": {
+    "nativeWatcher": true,
+  },
   "externals": [
     [Function],
     {
@@ -2301,7 +2304,7 @@ exports[`prepareRsbuild > should generate rspack config correctly in watch mode
   },
   "target": "node",
   "watchOptions": {
-    "aggregateTimeout": 5,
+    "aggregateTimeout": 100,
     "ignored": [
       "**/.git",
       "**/node_modules",