test_runner: describe it only shorthand

Author: richiemccoll

doc/api/test.md

@@ -808,6 +808,11 @@ 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])`
+
+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
@@ -832,6 +837,11 @@ 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])`
+
+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

@@ -184,7 +184,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');
-const test = 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,49 @@ test('only = true, with subtests', { only: true }, async (t) => {
   await t.test('skipped subtest 3', { only: false });
   await t.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('desribe only = true, with a mixture of subtests', () => {
+  it.only('`it` subtest 1', () => {});
+
+  it.only('`it` async subtest 1', async () => {});
+
+  it('`it` subtest 2 only=false', { only: false }, () => {
+    throw new Error('This should not run');
+  });
+
+  it.skip('`it` subtest 3 skip', () => {
+    throw new Error('This should not run');
+  });
+
+  it.todo('`it` subtest 4 todo', { only: false }, () => {
+    throw new Error('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 }, () => {});
+});
+
+// These two scenarios *should* work but don't as the parent
+// has no `only` flag set.
+describe('describe only - false with only subtest', () => {
+  it.only('`it` subtest should run', () => {
+    throw new Error('This should throw');
+  });
+});
+
+describe('describe only - false with only subtest', () => {
+  test.only('subtest should run', () => {
+    throw new Error('This should throw');
+  });
+});

test/message/test_runner_only_tests.out

@@ -116,11 +116,73 @@ 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: desribe 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=false
+    ok 3 - `it` subtest 2 only=false # SKIP 'only' option not set
+      ---
+      duration_ms: *
+      ...
+    # Subtest: `it` subtest 3 skip
+    ok 4 - `it` subtest 3 skip # SKIP
+      ---
+      duration_ms: *
+      ...
+    # Subtest: `it` subtest 4 todo
+    ok 5 - `it` subtest 4 todo # SKIP 'only' option not set
+      ---
+      duration_ms: *
+      ...
+    1..5
+ok 13 - desribe only = true, with a mixture of subtests
+  ---
+  duration_ms: *
+  ...
+# Subtest: subtest should run
+ok 14 - subtest should run # SKIP 'only' option not set
+  ---
+  duration_ms: *
+  ...
+# Subtest: async subtest should run
+ok 15 - async subtest should run # SKIP 'only' option not set
+  ---
+  duration_ms: *
+  ...
+# Subtest: subtest should be skipped
+ok 16 - subtest should be skipped # SKIP 'only' option not set
+  ---
+  duration_ms: *
+  ...
+1..19
+# tests 19
+# pass 4
 # fail 0
 # cancelled 0
-# skipped 10
+# skipped 15
 # todo 0
 # duration_ms *