test_runner: enhance expectFailure with validation support

Update `expectFailure` to accept an object for detailed configuration.
- Support `message` property for TAP output directives.
- Support `with` property for error validation (RegExp or Object), similar to `assert.throws`.

Tests added in `test/parallel/test-runner-xfail.js`.

Author: Han5991

doc/api/test.md

@@ -246,7 +246,16 @@ it('should do the thing', { expectFailure: true }, () => {
   assert.strictEqual(doTheThing(), true);
 });
 
-it('should do the thing', { expectFailure: 'doTheThing is not doing the thing because ...' }, () => {
+it('should do the thing', { expectFailure: 'feature not implemented' }, () => {
+  assert.strictEqual(doTheThing(), true);
+});
+
+it('should fail with specific error', {
+  expectFailure: {
+    with: /error message/,
+    message: 'reason for failure',
+  },
+}, () => {
   assert.strictEqual(doTheThing(), true);
 });
 ```

lib/internal/test_runner/test.js

@@ -56,7 +56,8 @@ const {
   once: runOnce,
   setOwnProperty,
 } = require('internal/util');
-const { isPromise } = require('internal/util/types');
+const { isDeepStrictEqual } = require('internal/util/comparisons');
+const { isPromise, isRegExp } = require('internal/util/types');
 const {
   validateAbortSignal,
   validateFunction,
@@ -637,7 +638,7 @@ class Test extends AsyncResource {
     this.cancelled = false;
     if (expectFailure === undefined || expectFailure === false) {
       this.expectFailure = false;
-    } else if (typeof expectFailure === 'string') {
+    } else if (typeof expectFailure === 'string' || typeof expectFailure === 'object') {
       this.expectFailure = expectFailure;
     } else {
       this.expectFailure = true;
@@ -953,7 +954,40 @@ class Test extends AsyncResource {
       return;
     }
 
-    this.passed = this.expectFailure;
+    if (this.expectFailure) {
+      if (typeof this.expectFailure === 'object' &&
+          this.expectFailure.with !== undefined) {
+        const { with: validation } = this.expectFailure;
+        let match = false;
+
+        if (isRegExp(validation)) {
+          match = RegExpPrototypeExec(validation, err.message) !== null;
+        } else if (typeof validation === 'object' && validation !== null) {
+          match = true;
+          for (const prop in validation) {
+            if (!isDeepStrictEqual(err[prop], validation[prop])) {
+              match = false;
+              break;
+            }
+          }
+        } else if (validation === err) {
+          match = true;
+        }
+
+        if (!match) {
+          this.passed = false;
+          this.error = new ERR_TEST_FAILURE(
+            'The test failed, but the error did not match the expected validation',
+            kTestCodeFailure,
+          );
+          this.error.cause = err;
+          return;
+        }
+      }
+      this.passed = true;
+    } else {
+      this.passed = false;
+    }
 
     this.error = err;
   }
@@ -963,6 +997,20 @@ class Test extends AsyncResource {
       return;
     }
 
+    if (this.skipped || this.isTodo) {
+      this.passed = true;
+      return;
+    }
+
+    if (this.expectFailure) {
+      this.passed = false;
+      this.error = new ERR_TEST_FAILURE(
+        'Test passed but was expected to fail',
+        kTestCodeFailure,
+      );
+      return;
+    }
+
     this.passed = true;
   }
 
@@ -1352,7 +1400,10 @@ class Test extends AsyncResource {
     } else if (this.isTodo) {
       directive = this.reporter.getTodo(this.message);
     } else if (this.expectFailure) {
-      directive = this.reporter.getXFail(this.expectFailure);
+      const message = typeof this.expectFailure === 'object' ?
+        this.expectFailure.message :
+        this.expectFailure;
+      directive = this.reporter.getXFail(message);
     }
 
     if (this.reportedType) {

test/parallel/test-runner-xfail-message.js

@@ -0,0 +1,52 @@
+'use strict';
+const common = require('../common');
+const { test } = require('node:test');
+const { spawn } = require('child_process');
+const assert = require('node:assert');
+
+if (process.env.CHILD_PROCESS === 'true') {
+  test('fail with message string', { expectFailure: 'reason string' }, () => {
+    assert.fail('boom');
+  });
+
+  test('fail with message object', { expectFailure: { message: 'reason object' } }, () => {
+    assert.fail('boom');
+  });
+
+  test('fail with validation regex', { expectFailure: { with: /boom/ } }, () => {
+    assert.fail('boom');
+  });
+
+  test('fail with validation object', { expectFailure: { with: { message: 'boom' } } }, () => {
+    assert.fail('boom');
+  });
+
+  test('fail with validation error (wrong error)', { expectFailure: { with: /bang/ } }, () => {
+    assert.fail('boom'); // Should result in real failure because error doesn't match
+  });
+
+  test('unexpected pass', { expectFailure: true }, () => {
+    // Should result in real failure because it didn't fail
+  });
+
+} else {
+  const child = spawn(process.execPath, ['--test-reporter', 'tap', __filename], {
+    env: { ...process.env, CHILD_PROCESS: 'true' },
+    stdio: 'pipe',
+  });
+
+  let stdout = '';
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => { stdout += chunk; });
+
+  child.on('close', common.mustCall((code) => {
+    // We expect exit code 1 because 'unexpected pass' and 'wrong error' should fail the test run
+    assert.strictEqual(code, 1);
+
+    // Check outputs
+    assert.match(stdout, /# EXPECTED FAILURE reason string/);
+    assert.match(stdout, /# EXPECTED FAILURE reason object/);
+    assert.match(stdout, /not ok \d+ - fail with validation error \(wrong error\)/);
+    assert.match(stdout, /not ok \d+ - unexpected pass/);
+  }));
+}