Skip to content

Commit 431fddf

Browse files
boneskulladuh95
authored andcommitted
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 2c4bf72 commit 431fddf

2 files changed

Lines changed: 45 additions & 0 deletions

File tree

doc/api/test.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1954,6 +1954,10 @@ changes:
19541954
If the number of assertions run in the test does not match the number
19551955
specified in the plan, the test will fail.
19561956
**Default:** `undefined`.
1957+
* `fn` {Function|AsyncFunction} The function under test. If provided, it will take
1958+
precedence over the `fn` parameter.
1959+
* `name` {string} The name of the test. If provided, it will take precedence over the
1960+
`name` parameter.
19571961
* `fn` {Function|AsyncFunction} The function under test. The first argument
19581962
to this function is a [`TestContext`][] object. If the test uses callbacks,
19591963
the callback function is passed as the second argument. **Default:** A no-op
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff 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

Comments
 (0)