doc: formalize TestOptions.fn and TestOptions.name as part of the public API

[boneskull]

TestOptions as provided to node:test's test/it supports both name and fn as options per its implementation.

I'd like to formalize this as part of the public, documented API.

Motivation

I have a use-case for consuming both fields. I'd like to be able to return the result of a function to test/it without needing to spread the parameters; e.g.:

const testOptionsFactory = (opts = {}) => {
  return {
    fn: () => { /* .. */ },
    name: opts.name
  };
};

test(testOptionsFactory({name: 'foo'}));

If I cannot rely on this behavior, then I would need to instead return an array of parameters and spread them:

const testParamsFactory = (opts = {}) => {
  return opts.name !== undefined
    ? [opts.name, () => { /* .. */ }] : [() => { /* .. */ }];
};

test(...testParamsFactory({name: 'foo'}));

I don't think it's too terribly controversial that the former is more ergonomic than the latter.

Next Steps

Once this lands, I plan to propose the addition of these fields to @types/node. Since the fields are not currently publicly documented, I can't justify such a change.

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[Trott]

Would this be semver minor since we're committing to supporting an API that was previously undocumented?

Also, do we have test coverage for these newly-documented properties?

[boneskull]

@Trott I could add a couple tests for it.

Just to confirm: this is existing, undocumented behavior.

[boneskull]

@Trott I've added a test suite.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.29%. Comparing base (25c0c8e) to head (89a7728).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #64946      +/-   ##
==========================================
- Coverage   90.29%   90.29%   -0.01%     
==========================================
  Files         760      760              
  Lines      247104   247137      +33     
  Branches    46599    46605       +6     
==========================================
+ Hits       223130   223153      +23     
- Misses      15455    15456       +1     
- Partials     8519     8528       +9     

see 33 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Trott]

Marking it semver minor out of an abundance of caution.

[Trott]

Doc-only changes don't need CI, but this one adds tests so let's make sure the tests pass on all our Jenkins configurations.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/75393/

[cjihrig]

LGTM, thanks.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/75409/

[boneskull]

@Trott I'd push back against the minor flag because there's no new behavior. It's fundamentally a docs change. But I'm not gonna die on that hill.

Otherwise it doesn't look like I need to do anything else here, right? Unclear if I need to squash.

[Trott]

@boneskull No need to squash. The bot will take care of that.

I too am not prepared to die on the semver hill. @jasnell @ruyadorno @cjihrig Any chance one of you feels strongly about whether or not "we are now documenting a previously undocumented API" should be patch or minor?