From 04d9c459e080d8909c390f8650f143af39124224 Mon Sep 17 00:00:00 2001
From: cjihrig <cjihrig@gmail.com>
Date: Sun, 24 Mar 2024 12:44:10 -0400
Subject: [PATCH 1/2] test: add test for skip+todo combinations

This commit adds a regression test for the edge case where a
test runner test is marked as both todo and skip.

Refs: https://github.com/nodejs/node/issues/49013
---
 test/parallel/test-runner-todo-skip-tests.js | 32 ++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 test/parallel/test-runner-todo-skip-tests.js

diff --git a/test/parallel/test-runner-todo-skip-tests.js b/test/parallel/test-runner-todo-skip-tests.js
new file mode 100644
index 00000000000000..f4a22f5993ca85
--- /dev/null
+++ b/test/parallel/test-runner-todo-skip-tests.js
@@ -0,0 +1,32 @@
+'use strict';
+const common = require('../common');
+const { strictEqual } = require('node:assert');
+const { run, suite, test } = require('node:test');
+
+if (!process.env.NODE_TEST_CONTEXT) {
+  const stream = run({ files: [__filename] });
+
+  stream.on('test:fail', common.mustNotCall());
+  stream.on('test:pass', common.mustCall((event) => {
+    strictEqual(event.skip, true);
+    strictEqual(event.todo, undefined);
+  }, 4));
+} else {
+  test('test options only', { skip: true, todo: true }, common.mustNotCall());
+
+  test('test context calls only', common.mustCall((t) => {
+    t.todo();
+    t.skip();
+  }));
+
+  test('todo test with context skip', { todo: true }, common.mustCall((t) => {
+    t.skip();
+  }));
+
+  // Note - there is no test for the skip option and t.todo() because the skip
+  // option prevents the test from running at all. This is verified by other
+  // tests.
+
+  // Suites don't have the context methods, so only test the options combination.
+  suite('suite options only', { skip: true, todo: true }, common.mustNotCall());
+}

From 6ade087f1101ce9788c0e9f4189dea1fa72df2b7 Mon Sep 17 00:00:00 2001
From: cjihrig <cjihrig@gmail.com>
Date: Sun, 24 Mar 2024 12:00:03 -0400
Subject: [PATCH 2/2] doc: add section explaining todo tests

This commit adds a section to the test runner docs explaining
what a TODO test is.

Refs: https://github.com/nodejs/node/issues/49013
---
 doc/api/test.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/api/test.md b/doc/api/test.md
index cb386825048362..ac593565179190 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -162,6 +162,37 @@ test('skip() method with message', (t) => {
 });
 ```
 
+## TODO tests
+
+Individual tests can be marked as flaky or incomplete by passing the `todo`
+option to the test, or by calling the test context's `todo()` method, as shown
+in the following example. These tests represent a pending implementation or bug
+that needs to be fixed. TODO tests are executed, but are not treated as test
+failures, and therefore do not affect the process exit code. If a test is marked
+as both TODO and skipped, the TODO option is ignored.
+
+```js
+// The todo option is used, but no message is provided.
+test('todo option', { todo: true }, (t) => {
+  // This code is executed, but not treated as a failure.
+  throw new Error('this does not fail the test');
+});
+
+// The todo option is used, and a message is provided.
+test('todo option with message', { todo: 'this is a todo test' }, (t) => {
+  // This code is executed.
+});
+
+test('todo() method', (t) => {
+  t.todo();
+});
+
+test('todo() method with message', (t) => {
+  t.todo('this is a todo test and is not treated as a failure');
+  throw new Error('this does not fail the test');
+});
+```
+
 ## `describe()` and `it()` aliases
 
 Suites and tests can also be written using the `describe()` and `it()`