test_runner: add cwd option and update documentation

Author: pmarchini

doc/api/test.md

@@ -1239,6 +1239,9 @@ added:
  - v18.9.0
  - v16.19.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/54225
+ description: Added the `cwd` option.
  - version: v22.6.0
  pr-url: https://github.com/nodejs/node/pull/53866
  description: Added the `globPatterns` option.
@@ -1263,6 +1266,9 @@ changes:
  parallel.
  If `false`, it would only run one test file at a time.
  **Default:** `false`.
+ * `cwd`: {string} Specifies the current working directory (cwd) to be used by the test runner.
+ The cwd serves as the base path for resolving files according to the [test runner execution model][].
+ **Default:** `process.cwd()`.
  * `files`: {Array} An array containing the list of files to run.
  **Default** matching files from [test runner execution model][].
  * `forceExit`: {boolean} Configures the test runner to exit the process once

lib/internal/test_runner/runner.js

@@ -50,6 +50,7 @@ const {
  validateFunction,
  validateObject,
  validateInteger,
+ validateString,
 } = require('internal/validators');
 const { getInspectPort, isUsingInspector, isInspectorMessage } = require('internal/util/inspector');
 const { isRegExp } = require('internal/util/types');
@@ -87,8 +88,7 @@ const kCanceledTests = new SafeSet()
 
 let kResistStopPropagation;
 
-function createTestFileList(patterns) {
- const cwd = process.cwd();
+function createTestFileList(patterns, cwd) {
  const hasUserSuppliedPattern = patterns != null;
  if (!patterns || patterns.length === 0) {
  patterns = [kDefaultPattern];
@@ -110,7 +110,7 @@ function createTestFileList(patterns) {
 
 function filterExecArgv(arg, i, arr) {
  return !ArrayPrototypeIncludes(kFilterArgs, arg) &&
-  !ArrayPrototypeSome(kFilterArgValues, (p) => arg === p || (i > 0 && arr[i - 1] === p) || StringPrototypeStartsWith(arg, `${p}=`));
+ !ArrayPrototypeSome(kFilterArgValues, (p) => arg === p || (i > 0 && arr[i - 1] === p) || StringPrototypeStartsWith(arg, `${p}=`));
 }
 
 function getRunArgs(path, { forceExit, inspectPort, testNamePatterns, testSkipPatterns, only }) {
@@ -167,7 +167,7 @@ class FileTest extends Test {
  if (firstSpaceIndex === -1) return false;
  const secondSpaceIndex = StringPrototypeIndexOf(comment, ' ', firstSpaceIndex + 1);
  return secondSpaceIndex === -1 &&
- ArrayPrototypeIncludes(kDiagnosticsFilterArgs, StringPrototypeSlice(comment, 0, firstSpaceIndex));
+  ArrayPrototypeIncludes(kDiagnosticsFilterArgs, StringPrototypeSlice(comment, 0, firstSpaceIndex));
  }
  #handleReportItem(item) {
  const isTopLevel = item.data.nesting === 0;
@@ -417,16 +417,19 @@ function watchFiles(testFiles, opts) {
  const watcherMode = opts.hasFiles ? 'filter' : 'all';
  const watcher = new FilesWatcher({ __proto__: null, debounce: 200, mode: watcherMode, signal: opts.signal });
  if (!opts.hasFiles) {
- watcher.watchPath(process.cwd()); // TODO: https://github.com/nodejs/node/issues/53867 before closing this MR
+ watcher.watchPath(opts.watchedDir);
  }
  const filesWatcher = { __proto__: null, watcher, runningProcesses, runningSubtests };
  opts.root.harness.watching = true;
  // Watch for changes in current filtered files
  watcher.on('changed', ({ owners, eventType }) => {
  if (!opts.hasFiles && (eventType === 'rename' || eventType === 'change')) {
- const updatedTestFiles = createTestFileList(opts.globPatterns);
+ const updatedTestFiles = createTestFileList(opts.globPatterns, opts.watchedDir);
 
  const newFileName = ArrayPrototypeFind(updatedTestFiles, (x) => !ArrayPrototypeIncludes(testFiles, x));
+ const previousFileName = ArrayPrototypeFind(testFiles, (x) => !ArrayPrototypeIncludes(updatedTestFiles, x));
+
+ testFiles = updatedTestFiles;
 
  // When file renamed (created / deleted) we need to update the watcher
  if (newFileName) {
@@ -437,8 +440,6 @@ function watchFiles(testFiles, opts) {
  if (!newFileName && previousFileName) {
  return; // Avoid rerunning files when file deleted
  }
-
- testFiles = updatedTestFiles;
  }
 
  watcher.unfilterFilesOwnedBy(owners);
@@ -491,6 +492,7 @@ function run(options = kEmptyObject) {
  setup,
  only,
  globPatterns,
+ cwd = process.cwd(),
  } = options;
 
  if (files != null) {
@@ -515,6 +517,10 @@ function run(options = kEmptyObject) {
  validateArray(globPatterns, 'options.globPatterns');
  }
 
+ if (cwd != null) {
+ validateString(cwd, 'options.cwd');
+ }
+
  if (globPatterns?.length > 0 && files?.length > 0) {
  throw new ERR_INVALID_ARG_VALUE(
  'options.globPatterns', globPatterns, 'is not supported when specifying \'options.files\'',
@@ -584,7 +590,7 @@ function run(options = kEmptyObject) {
  root.postRun();
  return root.reporter;
  }
- let testFiles = files ?? createTestFileList(globPatterns);
+ let testFiles = files ?? createTestFileList(globPatterns, cwd);
 
  if (shard) {
  testFiles = ArrayPrototypeFilter(testFiles, (_, index) => index % shard.total === shard.index - 1);
@@ -604,6 +610,7 @@ function run(options = kEmptyObject) {
  globPatterns,
  only,
  forceExit,
+ watchedDir: cwd,
  };
  if (watch) {
  filesWatcher = watchFiles(testFiles, opts);

test/parallel/test-runner-run-watch.mjs

@@ -4,10 +4,10 @@ import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
 import { spawn } from 'node:child_process';
 import { once } from 'node:events';
-import { writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+import { writeFileSync, renameSync, unlinkSync, existsSync, mkdtempSync } from 'node:fs';
 import util from 'internal/util';
 import tmpdir from '../common/tmpdir.js';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 
 if (common.isIBMi)
  common.skip('IBMi does not support `fs.watch()`');
@@ -222,4 +222,22 @@ describe('test runner watch mode', () => {
  it('should run new tests when a new file is created in the watched directory', async () => {
  await testWatch({ action: 'create', fileToCreate: 'new-test-file.test.js' });
  });
+
+ it('should run new tests when a new file is created in a different cwd', async () => {
+ const newTestWithoutDep = `
+ const test = require('node:test');
+ test('test without dep has ran');
+ `;
+ const differentCwd = mkdtempSync(`${tmpdir.path}/different-cwd`);
+ const testFileName = 'test-without-dep.js';
+ const newTestFilePath = join(differentCwd, testFileName);
+ writeFileSync(newTestFilePath, newTestWithoutDep);
+ const differentCwdTmpPath = basename(differentCwd);
+
+ await testWatch({
+ action: 'create',
+ fileToCreate: `${differentCwdTmpPath}/new-test-file.test.js`,
+ cwd: differentCwd
+ });
+ });
 });

test/parallel/test-runner-run.mjs

@@ -481,6 +481,13 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
  });
  });
 
+ it('should only allow a string in options.cwd', async () => {
+ [Symbol(), {}, [], () => {}, 0, 1, 0n, 1n, true, false]
+ .forEach((cwd) => assert.throws(() => run({ cwd }), {
+ code: 'ERR_INVALID_ARG_TYPE'
+ }));
+ });
+
  it('should only allow object as options', () => {
  [Symbol(), [], () => {}, 0, 1, 0n, 1n, '', '1', true, false]
  .forEach((options) => assert.throws(() => run(options), {

test/parallel/test-runner-watch-mode.mjs

@@ -4,9 +4,10 @@ import { describe, it, beforeEach } from 'node:test';
 import { once } from 'node:events';
 import assert from 'node:assert';
 import { spawn } from 'node:child_process';
-import { writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+import { writeFileSync, renameSync, unlinkSync, existsSync, mkdtempSync } from 'node:fs';
 import util from 'internal/util';
 import tmpdir from '../common/tmpdir.js';
+import { join, basename } from 'node:path';
 
 if (common.isIBMi)
  common.skip('IBMi does not support `fs.watch()`');
@@ -41,13 +42,14 @@ async function testWatch({
  fileToUpdate,
  file,
  action = 'update',
- fileToCreate
+ fileToCreate,
+ cwd = tmpdir.path
 }) {
  const ran1 = util.createDeferredPromise();
  const ran2 = util.createDeferredPromise();
  const child = spawn(process.execPath,
  ['--watch', '--test', file ? fixturePaths[file] : undefined].filter(Boolean),
- { encoding: 'utf8', stdio: 'pipe', cwd: tmpdir.path }
+ { encoding: 'utf8', stdio: 'pipe', cwd }
  );
  let stdout = '';
  let currentRun = '';
@@ -191,4 +193,22 @@ describe('test runner watch mode', () => {
  it('should run new tests when a new file is created in the watched directory', async () => {
  await testWatch({ action: 'create', fileToCreate: 'new-test-file.test.js' });
  });
+
+ it('should run new tests when a new file is created in a different cwd', async () => {
+ const newTestWithoutDep = `
+ const test = require('node:test');
+ test('test without dep has ran');
+ `;
+ const differentCwd = mkdtempSync(`${tmpdir.path}/different-cwd`);
+ const testFileName = 'test-without-dep.js';
+ const newTestFilePath = join(differentCwd, testFileName);
+ writeFileSync(newTestFilePath, newTestWithoutDep);
+ const differentCwdTmpPath = basename(differentCwd);
+
+ await testWatch({
+ action: 'create',
+ fileToCreate: `${differentCwdTmpPath}/new-test-file.test.js`,
+ cwd: differentCwd
+ });
+ });
 });