test_runner: add describe.only and it.only shorthands

PR-URL: #46604Fixes: #46562
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Author: richiemccoll

doc/api/test.md

@@ -824,6 +824,15 @@ Shorthand for skipping a suite, same as [`describe([name], { skip: true }[, fn])
 Shorthand for marking a suite as `TODO`, same as
 [`describe([name], { todo: true }[, fn])`][describe options].
 
+## `describe.only([name][, options][, fn])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Shorthand for marking a suite as `only`, same as
+[`describe([name], { only: true }[, fn])`][describe options].
+
 ## `it([name][, options][, fn])`
 
 *`name` {string} The name of the test, which is displayed when reporting test
@@ -848,6 +857,15 @@ same as [`it([name], { skip: true }[, fn])`][it options].
 Shorthand for marking a test as `TODO`,
 same as [`it([name], { todo: true }[, fn])`][it options].
 
+## `it.only([name][, options][, fn])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Shorthand for marking a test as `only`,
+same as [`it([name], { only: true }[, fn])`][it options].
+
 ## `before([fn][, options])`
 
 <!-- YAML

lib/internal/test_runner/harness.js

@@ -199,7 +199,7 @@ function runInParentContext(Factory) {
 run(name,options,fn);
 };
 
-ArrayPrototypeForEach(['skip','todo'],(keyword)=>{
+ArrayPrototypeForEach(['skip','todo','only'],(keyword)=>{
 cb[keyword]=(name,options,fn)=>{
 run(name,options,fn,{[keyword]: true});
 };

test/message/test_runner_only_tests.js

@@ -1,7 +1,7 @@
 // Flags: --no-warnings --test-only
 'use strict';
 require('../common');
-consttest=require('node:test');
+const{test, describe, it }=require('node:test');
 
 // These tests should be skipped based on the 'only' option.
 test('only = undefined');
@@ -46,3 +46,37 @@ test('only = true, with subtests', { only: true }, async (t) => {
 awaitt.test('skipped subtest 3',{only: false});
 awaitt.test('skipped subtest 4',{skip: true});
 });
+
+describe.only('describe only = true, with subtests',()=>{
+it('`it` subtest 1 should run',()=>{});
+
+it('`it` subtest 2 should run',async()=>{});
+});
+
+describe.only('describe only = true, with a mixture of subtests',()=>{
+it.only('`it` subtest 1',()=>{});
+
+it.only('`it` async subtest 1',async()=>{});
+
+it('`it` subtest 2 only=true',{only: true});
+
+it('`it` subtest 2 only=false',{only: false},()=>{
+thrownewError('This should not run');
+});
+
+it.skip('`it` subtest 3 skip',()=>{
+thrownewError('This should not run');
+});
+
+it.todo('`it` subtest 4 todo',{only: false},()=>{
+thrownewError('This should not run');
+});
+});
+
+describe.only('describe only = true, with subtests',()=>{
+test('subtest should run',()=>{});
+
+test('async subtest should run',async()=>{});
+
+test('subtest should be skipped',{only: false},()=>{});
+});

test/message/test_runner_only_tests.out

@@ -116,9 +116,82 @@ ok 11 - only = true, with subtests
  ---
  duration_ms: *
  ...
-1..11
-# tests 11
-# pass 1
+# Subtest: describe only = true, with subtests
+ # Subtest: `it` subtest 1 should run
+ ok 1 - `it` subtest 1 should run
+ ---
+ duration_ms: *
+ ...
+ # Subtest: `it` subtest 2 should run
+ ok 2 - `it` subtest 2 should run
+ ---
+ duration_ms: *
+ ...
+ 1..2
+ok 12 - describe only = true, with subtests
+ ---
+ duration_ms: *
+ ...
+# Subtest: describe only = true, with a mixture of subtests
+ # Subtest: `it` subtest 1
+ ok 1 - `it` subtest 1
+ ---
+ duration_ms: *
+ ...
+ # Subtest: `it` async subtest 1
+ ok 2 - `it` async subtest 1
+ ---
+ duration_ms: *
+ ...
+ # Subtest: `it` subtest 2 only=true
+ ok 3 - `it` subtest 2 only=true
+ ---
+ duration_ms: *
+ ...
+ # Subtest: `it` subtest 2 only=false
+ ok 4 - `it` subtest 2 only=false # SKIP 'only' option not set
+ ---
+ duration_ms: *
+ ...
+ # Subtest: `it` subtest 3 skip
+ ok 5 - `it` subtest 3 skip # SKIP
+ ---
+ duration_ms: *
+ ...
+ # Subtest: `it` subtest 4 todo
+ ok 6 - `it` subtest 4 todo # SKIP 'only' option not set
+ ---
+ duration_ms: *
+ ...
+ 1..6
+ok 13 - describe only = true, with a mixture of subtests
+ ---
+ duration_ms: *
+ ...
+# Subtest: describe only = true, with subtests
+ # Subtest: subtest should run
+ ok 1 - subtest should run
+ ---
+ duration_ms: *
+ ...
+ # Subtest: async subtest should run
+ ok 2 - async subtest should run
+ ---
+ duration_ms: *
+ ...
+ # Subtest: subtest should be skipped
+ ok 3 - subtest should be skipped # SKIP 'only' option not set
+ ---
+ duration_ms: *
+ ...
+ 1..3
+ok 14 - describe only = true, with subtests
+ ---
+ duration_ms: *
+ ...
+1..14
+# tests 14
+# pass 4
 # fail 0
 # cancelled 0
 # skipped 10