test_runner: add testNamePatterns to run api

Accept a `testNamePatterns` value in the `run` fn, and drill those
patterns to the spawned processes.
PR-URL: #47648
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Author: atlowChemi

doc/api/test.md

@@ -709,6 +709,10 @@ unless a destination is explicitly provided.
 
 <!-- YAML
 added: v18.9.0
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/47628
+ description: Add a testNamePatterns option.
 -->
 
 *`options` {Object} Configuration options for running tests. The following
@@ -734,6 +738,12 @@ added: v18.9.0
  number. If a nullish value is provided, each process gets its own port,
  incremented from the primary's `process.debugPort`.
 **Default:**`undefined`.
+*`testNamePatterns` {string|RegExp|Array} A String, RegExp or a RegExp Array,
+ that can be used to only run tests whose name matches the provided pattern.
+ Test name patterns are interpreted as JavaScript regular expressions.
+ For each test that is executed, any corresponding test hooks, such as
+`beforeEach()`, are also run.
+**Default:**`undefined`.
 * Returns: {TestsStream}
 
 ```mjs

lib/internal/test_runner/runner.js

@@ -1,10 +1,12 @@
 'use strict';
 const{
  ArrayFrom,
+ ArrayIsArray,
  ArrayPrototypeFilter,
  ArrayPrototypeForEach,
  ArrayPrototypeIncludes,
  ArrayPrototypeIndexOf,
+ ArrayPrototypeMap,
  ArrayPrototypePush,
  ArrayPrototypeSlice,
  ArrayPrototypeSome,
@@ -33,11 +35,13 @@ const { FilesWatcher } = require('internal/watch_mode/files_watcher');
 constconsole=require('internal/console/global');
 const{
 codes: {
+ERR_INVALID_ARG_TYPE,
 ERR_TEST_FAILURE,
 },
 }=require('internal/errors');
 const{ validateArray, validateBoolean, validateFunction }=require('internal/validators');
 const{ getInspectPort, isUsingInspector, isInspectorMessage }=require('internal/util/inspector');
+const{ isRegExp }=require('internal/util/types');
 const{ kEmptyObject }=require('internal/util');
 const{ createTestTree }=require('internal/test_runner/harness');
 const{
@@ -53,6 +57,7 @@ const { YAMLToJs } = require('internal/test_runner/yaml_to_js');
 const{ TokenKind }=require('internal/test_runner/tap_lexer');
 
 const{
+ convertStringToRegExp,
  countCompletedTest,
  doesPathMatchFilter,
  isSupportedFileType,
@@ -137,11 +142,14 @@ function filterExecArgv(arg, i, arr) {
 !ArrayPrototypeSome(kFilterArgValues,(p)=>arg===p||(i>0&&arr[i-1]===p)||StringPrototypeStartsWith(arg,`${p}=`));
 }
 
-functiongetRunArgs({ path, inspectPort }){
+functiongetRunArgs({ path, inspectPort, testNamePatterns}){
 constargv=ArrayPrototypeFilter(process.execArgv,filterExecArgv);
 if(isUsingInspector()){
 ArrayPrototypePush(argv,`--inspect-port=${getInspectPort(inspectPort)}`);
 }
+if(testNamePatterns){
+ArrayPrototypeForEach(testNamePatterns,(pattern)=>ArrayPrototypePush(argv,`--test-name-pattern=${pattern}`));
+}
 ArrayPrototypePush(argv,path);
 
 returnargv;
@@ -255,9 +263,9 @@ class FileTest extends Test {
 construnningProcesses=newSafeMap();
 construnningSubtests=newSafeMap();
 
-functionrunTestFile(path,root,inspectPort,filesWatcher){
+functionrunTestFile(path,root,inspectPort,filesWatcher,testNamePatterns){
 constsubtest=root.createSubtest(FileTest,path,async(t)=>{
-constargs=getRunArgs({ path, inspectPort });
+constargs=getRunArgs({ path, inspectPort, testNamePatterns});
 conststdio=['pipe','pipe','pipe'];
 constenv={ ...process.env,NODE_TEST_CONTEXT: 'child'};
 if(filesWatcher){
@@ -339,7 +347,7 @@ function runTestFile(path, root, inspectPort, filesWatcher) {
 returnpromise;
 }
 
-functionwatchFiles(testFiles,root,inspectPort){
+functionwatchFiles(testFiles,root,inspectPort,testNamePatterns){
 constfilesWatcher=newFilesWatcher({throttle: 500,mode: 'filter'});
 filesWatcher.on('changed',({ owners })=>{
 filesWatcher.unfilterFilesOwnedBy(owners);
@@ -353,7 +361,7 @@ function watchFiles(testFiles, root, inspectPort) {
 awaitonce(runningProcess,'exit');
 }
 awaitrunningSubtests.get(file);
-runningSubtests.set(file,runTestFile(file,root,inspectPort,filesWatcher));
+runningSubtests.set(file,runTestFile(file,root,inspectPort,filesWatcher,testNamePatterns));
 },undefined,(error)=>{
 triggerUncaughtException(error,true/* fromPromise */);
 }));
@@ -365,6 +373,7 @@ function run(options) {
 if(options===null||typeofoptions!=='object'){
 options=kEmptyObject;
 }
+let{ testNamePatterns }=options;
 const{ concurrency, timeout, signal, files, inspectPort, watch, setup }=options;
 
 if(files!=null){
@@ -376,20 +385,36 @@ function run(options) {
 if(setup!=null){
 validateFunction(setup,'options.setup');
 }
+if(testNamePatterns!=null){
+if(!ArrayIsArray(testNamePatterns)){
+testNamePatterns=[testNamePatterns];
+}
+validateArray(testNamePatterns,'options.testNamePatterns');
+testNamePatterns=ArrayPrototypeMap(testNamePatterns,(value,i)=>{
+if(isRegExp(value)){
+returnvalue;
+}
+constname=`options.testNamePatterns[${i}]`;
+if(typeofvalue==='string'){
+returnconvertStringToRegExp(value,name);
+}
+thrownewERR_INVALID_ARG_TYPE(name,['string','RegExp'],value);
+});
+}
 
 constroot=createTestTree({ concurrency, timeout, signal });
 consttestFiles=files??createTestFileList();
 
 letpostRun=()=>root.postRun();
 letfilesWatcher;
 if(watch){
-filesWatcher=watchFiles(testFiles,root,inspectPort);
+filesWatcher=watchFiles(testFiles,root,inspectPort,testNamePatterns);
 postRun=undefined;
 }
 construnFiles=()=>{
 root.harness.bootstrapComplete=true;
 returnSafePromiseAllSettledReturnVoid(testFiles,(path)=>{
-constsubtest=runTestFile(path,root,inspectPort,filesWatcher);
+constsubtest=runTestFile(path,root,inspectPort,filesWatcher,testNamePatterns);
 runningSubtests.set(path,subtest);
 returnsubtest;
 });

test/fixtures/test-runner/test/skip_by_name.cjs

@@ -0,0 +1,5 @@
+'use strict';
+consttest=require('node:test');
+
+test('this should be skipped');
+test('this should be executed');

test/parallel/test-runner-run.mjs

@@ -101,4 +101,20 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
 assert.strictEqual(result[11],'# todo 0\n');
 assert.match(result[12],/#duration_ms\d+\.?\d*/);
 });
+
+it('should skip tests not matching testNamePatterns - RegExp',async()=>{
+constresult=awaitrun({files: [join(testFixtures,'test/skip_by_name.cjs')],testNamePatterns: [/executed/]})
+.compose(tap)
+.toArray();
+assert.strictEqual(result[2],'ok 1 - this should be skipped # SKIP test name does not match pattern\n');
+assert.strictEqual(result[5],'ok 2 - this should be executed\n');
+});
+
+it('should skip tests not matching testNamePatterns - string',async()=>{
+constresult=awaitrun({files: [join(testFixtures,'test/skip_by_name.cjs')],testNamePatterns: ['executed']})
+.compose(tap)
+.toArray();
+assert.strictEqual(result[2],'ok 1 - this should be skipped # SKIP test name does not match pattern\n');
+assert.strictEqual(result[5],'ok 2 - this should be executed\n');
+});
 });