doc: formalize TestOptions.fn and TestOptions.name as part of the public API by boneskull · Pull Request #64946 · nodejs/node

boneskull · 2026-08-02T01:20:36Z

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.:

consttestOptionsFactory=(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:

consttestParamsFactory=(opts={})=>{returnopts.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 · 2026-08-02T01:20:41Z

Review requested:

@nodejs/test_runner

`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.: ```js 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: ```js 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. Signed-off-by: Christopher Hiller <boneskull@boneskull.com>

Trott · 2026-08-02T03:09:41Z

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 · 2026-08-02T06:37:10Z

@Trott I could add a couple tests for it.

Just to confirm: this is existing, undocumented behavior.

This adds a test suite which proves the behavior of `test`/`it`'s options; specifically how the `name` and `fn` options take precedence over their associated parameters, and how a test can be named and run using only a single "options" parameter. Signed-off-by: Christopher Hiller <boneskull@boneskull.com>

boneskull · 2026-08-02T07:03:40Z

@Trott I've added a test suite.

codecov · 2026-08-02T08:43:11Z

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 · 2026-08-02T16:14:51Z

Marking it semver minor out of an abundance of caution.

Trott · 2026-08-02T16:18:26Z

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 · 2026-08-02T16:37:29Z

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

cjihrig

LGTM, thanks.

nodejs-github-bot · 2026-08-03T02:45:43Z

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

boneskull · 2026-08-03T04:49:35Z

@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 · 2026-08-03T05:10:37Z

@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?

cjihrig · 2026-08-03T11:28:17Z

I don't really have a preference here since there is no behavior change.

Trott · 2026-08-03T17:56:47Z

@nodejs/releasers Any chance one of you feels strongly about whether or not "we are now documenting a previously undocumented API" should be patch or minor?

nodejs-github-bot · 2026-08-04T01:45:10Z

Landed in cd78d08

`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.: ```js 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: ```js 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. Signed-off-by: Christopher Hiller <boneskull@boneskull.com> PR-URL: #64946 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruy Adorno <ruy@vlt.sh> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Notable changes: build: * (SEMVER-MINOR) perfetto-sdk (Chengzhong Wu) #64565 crypto: * (SEMVER-MINOR) support loading private keys through STORE loaders (Filip Skokan) #63949 * update root certificates to NSS 3.125 (Node.js GitHub Bot) #64746 doc: * (SEMVER-MINOR) formalize fn/name as part of TestOptions API (Christopher Hiller) #64946 lib: * (SEMVER-MINOR) add perfetto support (Chengzhong Wu) #64565 module: * (SEMVER-MINOR) implement Symbol.dispose in ModuleHooks (Remco Haszing) #63928 net: * (SEMVER-MINOR) add experimental net/promises API (Ethan Arrowood) #63965 src: * (SEMVER-MINOR) add perfetto trace agent (Chengzhong Wu) #64565 * (SEMVER-MINOR) rename legacy trace event headers (Chengzhong Wu) #64565 * (SEMVER-MINOR) fix trace macro compatibility (Chengzhong Wu) #64565 test_runner: * (SEMVER-MINOR) add support for --test-coverage-include-all (avivkeller) #64830 PR-URL: #65027

aduh95 · 2026-08-04T19:43:30Z

I think semver-patch makes more sense. Also, ideally we would document when it was introduced

`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.: ```js 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: ```js 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. Signed-off-by: Christopher Hiller <boneskull@boneskull.com> PR-URL: #64946 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruy Adorno <ruy@vlt.sh> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

nodejs-github-bot added doc Issues and PRs related to the documentations. test_runner Issues and PRs related to the test runner subsystem. labels Aug 2, 2026

boneskull force-pushed the testoptions-docs branch 2 times, most recently from 719711c to d561a84Compare August 2, 2026 01:32

boneskull force-pushed the testoptions-docs branch from d561a84 to 480711fCompare August 2, 2026 01:39

Trott approved these changes Aug 2, 2026
View reviewed changes

jasnell approved these changes Aug 2, 2026
View reviewed changes

ruyadorno approved these changes Aug 2, 2026
View reviewed changes

Trott added semver-minor PRs that contain new features and should be released in the next minor version. needs-ci PRs that need a full CI run. request-ci Add this label to start a Jenkins CI on a PR. labels Aug 2, 2026

Trott added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Aug 2, 2026

Trott requested a review from cjihrig August 2, 2026 16:20

github-actionsBot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 2, 2026

cjihrig approved these changes Aug 2, 2026
View reviewed changes

Trott added the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 2, 2026

Trott added the commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. label Aug 3, 2026

atlowChemi approved these changes Aug 3, 2026
View reviewed changes

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 4, 2026

nodejs-github-bot merged commit cd78d08 into nodejs:mainAug 4, 2026
86 checks passed

github-actionsBot mentioned this pull request Aug 4, 2026
2026-08-05, Version 26.7.0 (Current) #65027
Merged

aduh95 removed the semver-minor PRs that contain new features and should be released in the next minor version. label Aug 4, 2026

Uh oh!

Uh oh!

Conversation

boneskull commented Aug 2, 2026

Motivation

Next Steps

Uh oh!

nodejs-github-bot commented Aug 2, 2026

Uh oh!

Trott commented Aug 2, 2026

Uh oh!

boneskull commented Aug 2, 2026

Uh oh!

boneskull commented Aug 2, 2026

Uh oh!

codecovBot commented Aug 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Trott commented Aug 2, 2026

Uh oh!

Trott commented Aug 2, 2026

Uh oh!

nodejs-github-bot commented Aug 2, 2026

Uh oh!

cjihrig left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Aug 3, 2026

Uh oh!

boneskull commented Aug 3, 2026

Uh oh!

Trott commented Aug 3, 2026

Uh oh!

cjihrig commented Aug 3, 2026

Uh oh!

Trott commented Aug 3, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 4, 2026

Uh oh!

aduh95 commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

codecovBot commented Aug 2, 2026•
edited
Loading