Commit 232287f
doc: formalize fn/name as part of TestOptions API
`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>1 parent 51d4131 commit 232287f
2 files changed
Lines changed: 45 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1944,6 +1944,10 @@ changes: | |||
| 1944 | 1944 | If the number of assertions run in the test does not match the number | |
| 1945 | 1945 | specified in the plan, the test will fail. | |
| 1946 | 1946 | **Default:** `undefined`. | |
| 1947 | + * `fn` {Function|AsyncFunction} The function under test. If provided, it will take | ||
| 1948 | + precedence over the `fn` parameter. | ||
| 1949 | + * `name` {string} The name of the test. If provided, it will take precedence over the | ||
| 1950 | + `name` parameter. | ||
| 1947 | 1951 | * `fn` {Function|AsyncFunction} The function under test. The first argument | |
| 1948 | 1952 | to this function is a [`TestContext`][] object. If the test uses callbacks, | |
| 1949 | 1953 | the callback function is passed as the second argument. **Default:** A no-op | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -0,0 +1,41 @@ | |||
| 1 | + 'use strict'; | ||
| 2 | + require('../common'); | ||
| 3 | + const { test, suite } = require('node:test'); | ||
| 4 | + | ||
| 5 | + suite('test runner option precedence', () => { | ||
| 6 | + test( | ||
| 7 | + 'overridden test name', | ||
| 8 | + { name: 'options.name overrides test name', plan: 1 }, | ||
| 9 | + (t) => { | ||
| 10 | + t.assert.strictEqual(t.name, 'options.name overrides test name'); | ||
| 11 | + }, | ||
| 12 | + ); | ||
| 13 | + | ||
| 14 | + test( | ||
| 15 | + 'options.fn overrides test function', | ||
| 16 | + { | ||
| 17 | + fn: (t) => { | ||
| 18 | + t.assert.ok(true); | ||
| 19 | + }, | ||
| 20 | + plan: 1, | ||
| 21 | + }, | ||
| 22 | + (t) => { | ||
| 23 | + t.assert.fail('should not be called'); | ||
| 24 | + }, | ||
| 25 | + ); | ||
| 26 | + | ||
| 27 | + test('options.fn only', { | ||
| 28 | + plan: 1, | ||
| 29 | + fn: (t) => { | ||
| 30 | + t.assert.ok(true); | ||
| 31 | + }, | ||
| 32 | + }); | ||
| 33 | + | ||
| 34 | + test({ | ||
| 35 | + name: 'single parameter options', | ||
| 36 | + plan: 1, | ||
| 37 | + fn: (t) => { | ||
| 38 | + t.assert.ok(true); | ||
| 39 | + }, | ||
| 40 | + }); | ||
| 41 | + }); | ||
0 commit comments