test_runner: enhance expectFailure option

Update expectFailure to accept different types of values (RegExp, Function, Object) for error validation.

This change introduces a more flexible API:

- String: Acts as a failure label.

- Matcher (RegExp, Function, Error): Validates the thrown error.

- Object: Supports both 'label' and 'match' properties.

Author: Han5991

doc/api/test.md

@@ -252,12 +252,22 @@ it('should do the thing', { expectFailure: 'feature not implemented' }, () => {
 
 it('should fail with specific error', {
   expectFailure: {
-    with: /error message/,
-    message: 'reason for failure',
+    match: /error message/,
+    label: 'reason for failure',
   },
 }, () => {
   assert.strictEqual(doTheThing(), true);
 });
+
+it('should fail with regex', { expectFailure: /error message/ }, () => {
+  assert.strictEqual(doTheThing(), true);
+});
+
+it('should fail with function', {
+  expectFailure: (err) => err.code === 'ERR_CODE',
+}, () => {
+  assert.strictEqual(doTheThing(), true);
+});
 ```
 
 `skip` and/or `todo` are mutually exclusive to `expectFailure`, and `skip` or `todo`
@@ -1696,9 +1706,12 @@ changes:
     thread. If `false`, only one test runs at a time.
     If unspecified, subtests inherit this value from their parent.
     **Default:** `false`.
-  * `expectFailure` {boolean|string} If truthy, the test is expected to fail.
-    If a string is provided, that string is displayed in the test results as the
-    reason why the test is expected to fail. **Default:** `false`.
+  * `expectFailure` {boolean|string|Object} If truthy, the test is expected to
+    fail. If a string is provided, that string is displayed in the test results
+    as the reason why the test is expected to fail. If an object is provided,
+    it can contain a `label` property (string) for the failure reason and a
+    `match` property (RegExp, Function, Object, or Error) to validate the error
+    thrown. **Default:** `false`.
   * `only` {boolean} If truthy, and the test context is configured to run
     `only` tests, then this test will be run. Otherwise, the test is skipped.
     **Default:** `false`.

lib/internal/test_runner/test.js

@@ -13,6 +13,7 @@ const {
   MathMax,
   Number,
   NumberPrototypeToFixed,
+  ObjectKeys,
   ObjectSeal,
   Promise,
   PromisePrototypeThen,
@@ -40,6 +41,7 @@ const {
   AbortError,
   codes: {
     ERR_INVALID_ARG_TYPE,
+    ERR_INVALID_ARG_VALUE,
     ERR_TEST_FAILURE,
   },
 } = require('internal/errors');
@@ -57,7 +59,7 @@ const {
   setOwnProperty,
 } = require('internal/util');
 const assert = require('assert');
-const { isPromise } = require('internal/util/types');
+const { isPromise, isRegExp } = require('internal/util/types');
 const {
   validateAbortSignal,
   validateFunction,
@@ -488,6 +490,39 @@ class SuiteContext {
   }
 }
 
+function parseExpectFailure(expectFailure) {
+  if (expectFailure === undefined || expectFailure === false) {
+    return false;
+  }
+
+  if (typeof expectFailure === 'string') {
+    return { __proto__: null, label: expectFailure, match: undefined };
+  }
+
+  if (typeof expectFailure === 'function' || isRegExp(expectFailure)) {
+    return { __proto__: null, label: undefined, match: expectFailure };
+  }
+
+  if (typeof expectFailure !== 'object') {
+    return { __proto__: null, label: undefined, match: undefined };
+  }
+
+  const keys = ObjectKeys(expectFailure);
+  if (keys.length === 0) {
+    throw new ERR_INVALID_ARG_VALUE('options.expectFailure', expectFailure, 'must not be an empty object');
+  }
+
+  if (keys.every((k) => k === 'match' || k === 'label')) {
+    return {
+      __proto__: null,
+      label: expectFailure.label,
+      match: expectFailure.match,
+    };
+  }
+
+  return { __proto__: null, label: undefined, match: expectFailure };
+}
+
 class Test extends AsyncResource {
   reportedType = 'test';
   abortController;
@@ -637,13 +672,7 @@ class Test extends AsyncResource {
     this.plan = null;
     this.expectedAssertions = plan;
     this.cancelled = false;
-    if (expectFailure === undefined || expectFailure === false) {
-      this.expectFailure = false;
-    } else if (typeof expectFailure === 'string' || typeof expectFailure === 'object') {
-      this.expectFailure = expectFailure;
-    } else {
-      this.expectFailure = true;
-    }
+    this.expectFailure = parseExpectFailure(expectFailure);
     this.skipped = skip !== undefined && skip !== false;
     this.isTodo = (todo !== undefined && todo !== false) || this.parent?.isTodo;
     this.startTime = null;
@@ -957,11 +986,15 @@ class Test extends AsyncResource {
 
     if (this.expectFailure) {
       if (typeof this.expectFailure === 'object' &&
-          this.expectFailure.with !== undefined) {
-        const { with: validation } = this.expectFailure;
+          this.expectFailure.match !== undefined) {
+        const { match: validation } = this.expectFailure;
         try {
           const { throws } = assert;
-          throws(() => { throw err; }, validation);
+          const errorToCheck = (err?.code === 'ERR_TEST_FAILURE' &&
+            err?.failureType === kTestCodeFailure &&
+            err.cause) ?
+            err.cause : err;
+          throws(() => { throw errorToCheck; }, validation);
         } catch (e) {
           this.passed = false;
           this.error = new ERR_TEST_FAILURE(
@@ -1397,7 +1430,7 @@ class Test extends AsyncResource {
       directive = this.reporter.getTodo(this.message);
     } else if (this.expectFailure) {
       const message = typeof this.expectFailure === 'object' ?
-        this.expectFailure.message :
+        this.expectFailure.label :
         this.expectFailure;
       directive = this.reporter.getXFail(message);
     }

test/parallel/test-runner-xfail.js

@@ -9,30 +9,108 @@ if (process.env.CHILD_PROCESS === 'true') {
     assert.fail('boom');
   });
 
-  test('fail with message object', { expectFailure: { message: 'reason object' } }, () => {
+  test('fail with label object', { expectFailure: { label: 'reason object' } }, () => {
     assert.fail('boom');
   });
 
-  test('fail with validation regex', { expectFailure: { with: /boom/ } }, () => {
+  test('fail with match regex', { expectFailure: { match: /boom/ } }, () => {
     assert.fail('boom');
   });
 
-  test('fail with validation object', { expectFailure: { with: { message: 'boom' } } }, () => {
+  test('fail with match object', { expectFailure: { match: { message: 'boom' } } }, () => {
     assert.fail('boom');
   });
 
-  test('fail with validation class', { expectFailure: { with: assert.AssertionError } }, () => {
+  test('fail with match class', { expectFailure: { match: assert.AssertionError } }, () => {
     assert.fail('boom');
   });
 
-  test('fail with validation error (wrong error)', { expectFailure: { with: /bang/ } }, () => {
+  test('fail with match error (wrong error)', { expectFailure: { match: /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
   });
 
+  test('fail with empty string', { expectFailure: '' }, () => {
+    assert.fail('boom');
+  });
+
+  // 1. Matcher: RegExp
+  test('fails with regex matcher', { expectFailure: /expected error/ }, () => {
+    throw new Error('this is the expected error');
+  });
+
+  test('fails with regex matcher (mismatch)', { expectFailure: /expected error/ }, () => {
+    throw new Error('wrong error'); // Should fail the test
+  });
+
+  // 2. Matcher: Class
+  test('fails with class matcher', { expectFailure: RangeError }, () => {
+    throw new RangeError('out of bounds');
+  });
+
+  test('fails with class matcher (mismatch)', { expectFailure: RangeError }, () => {
+    throw new TypeError('wrong type'); // Should fail the test
+  });
+
+  // 3. Matcher: Object (Properties)
+  test('fails with object matcher', { expectFailure: { code: 'ERR_TEST' } }, () => {
+    const err = new Error('boom');
+    err.code = 'ERR_TEST';
+    throw err;
+  });
+
+  test('fails with object matcher (mismatch)', { expectFailure: { code: 'ERR_TEST' } }, () => {
+    const err = new Error('boom');
+    err.code = 'ERR_WRONG';
+    throw err; // Should fail
+  });
+
+  // 4. Configuration Object: Reason + Validation
+  test('fails with config object (label + match)', {
+    expectFailure: {
+      label: 'Bug #124',
+      match: /boom/
+    }
+  }, () => {
+    throw new Error('boom');
+  });
+
+  test('fails with config object (label only)', {
+    expectFailure: { label: 'Bug #125' }
+  }, () => {
+    throw new Error('boom');
+  });
+
+  test('fails with config object (match only)', {
+    expectFailure: { match: /boom/ }
+  }, () => {
+    throw new Error('boom');
+  });
+
+  // 5. Edge Case: Empty Object (Should throw ERR_INVALID_ARG_VALUE during creation)
+  try {
+    test('invalid empty object', { expectFailure: {} }, () => {});
+  } catch (e) {
+    console.log(`CAUGHT_INVALID_ARG: ${e.code}`);
+  }
+
+  // 6. Primitives and Truthiness
+  test('fails with boolean true', { expectFailure: true }, () => {
+    throw new Error('any error');
+  });
+
+  // 7. Unexpected Pass (Enhanced)
+  test('unexpected pass (reason string)', { expectFailure: 'should fail' }, () => {
+    // Pass
+  });
+
+  test('unexpected pass (matcher)', { expectFailure: /boom/ }, () => {
+    // Pass
+  });
+
 } else {
   const child = spawn(process.execPath, ['--test-reporter', 'tap', __filename], {
     env: { ...process.env, CHILD_PROCESS: 'true' },
@@ -47,10 +125,30 @@ if (process.env.CHILD_PROCESS === 'true') {
     // 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/);
+    assert.match(stdout, /ok \d+ - fail with message string # EXPECTED FAILURE reason string/);
+    assert.match(stdout, /ok \d+ - fail with label object # EXPECTED FAILURE reason object/);
+    assert.match(stdout, /ok \d+ - fail with match regex # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fail with match object # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fail with match class # EXPECTED FAILURE/);
+    assert.match(stdout, /not ok \d+ - fail with match error \(wrong error\) # EXPECTED FAILURE/);
+    assert.match(stdout, /not ok \d+ - unexpected pass # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fail with empty string # EXPECTED FAILURE/);
+
+    // New tests verification
+    assert.match(stdout, /ok \d+ - fails with regex matcher # EXPECTED FAILURE/);
+    assert.match(stdout, /not ok \d+ - fails with regex matcher \(mismatch\) # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fails with class matcher # EXPECTED FAILURE/);
+    assert.match(stdout, /not ok \d+ - fails with class matcher \(mismatch\) # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fails with object matcher # EXPECTED FAILURE/);
+    assert.match(stdout, /not ok \d+ - fails with object matcher \(mismatch\) # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fails with config object \(label \+ match\) # EXPECTED FAILURE Bug \\#124/);
+    assert.match(stdout, /ok \d+ - fails with config object \(label only\) # EXPECTED FAILURE Bug \\#125/);
+    assert.match(stdout, /ok \d+ - fails with config object \(match only\) # EXPECTED FAILURE/);
+    assert.match(stdout, /ok \d+ - fails with boolean true # EXPECTED FAILURE/);
+    assert.match(stdout, /not ok \d+ - unexpected pass \(reason string\) # EXPECTED FAILURE should fail/);
+    assert.match(stdout, /not ok \d+ - unexpected pass \(matcher\) # EXPECTED FAILURE/);
+
+    // Empty object error
+    assert.match(stdout, /CAUGHT_INVALID_ARG: ERR_INVALID_ARG_VALUE/);
   }));
 }