Skip to content

doc(proposal): un/break --test #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JakobJingleheimer wants to merge 2 commits into
base: main
Choose a base branch
from
Open

doc(proposal): un/break --test #13

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
86af8d6
doc(proposal): un/break `--test`
JakobJingleheimer Feb 1, 2026
f34de60
add "option 3"
JakobJingleheimer Feb 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
340 changes: 340 additions & 0 deletions proposals/proposal - unbreak test cli arg.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,340 @@
# Proposal: un/break `--test`

Currently, this flag's behaviour is very unexpected, often resulting in silent-failure footguns, and precludes command nesting, as demonstrated in a very simple and typical CI setup:

```yaml title="unit & e2e tests"
- name: tests with coverage
run: node --run test -- --test-reporter lcov
```

That results in

```sh
node --test --test-reporter lcov
```

In most cases, `--test-reporter` gets lost (the `lcov` reporter is not enabled); in a worse case, this unexpectedly causes tests within a directory named `lcov` to be run.

## More info

Currently (since always):

`--test` receives everything after it (space-delimited).

`--test` currently does 2 things:

* enables the test runner
* accepts paths for the runner to consume

This is similar to another existing feature with which we want to improve interop: `watch` mode.

`--watch` currently does 2 things:

* enables `watch` mode
* optionally accepts 1 value to override the entrypoint
Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* optionally accepts 1 value to override the entrypoint
* optionally accepts 1 value to override the entrypoint
* and the `--watch-path` option is used for any additional paths to include besides the entrypoint

Copy link
Member Author

@JakobJingleheimer JakobJingleheimer Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: those bullet-points are about --watch, so i think --watch-path should be separate

Suggested change
* optionally accepts 1 value to override the entrypoint
* optionally accepts 1 value to override the entrypoint
`--watch-path` sets additional paths (can be set multiple times) to include as well as the entrypoint.


```sh
node
--watch
--watch-path ./src/**/*.ts
--watch-path ./test/**/*.ts
```

## Proposed options

### Option: n-number of `--test`s + `--watch-path`

`--test` is no-longer positional, accepting 1 value per occurrance of the flag. Supplying any value will override the default glob path.

When combined with test mode, `--watch`'s value is ignored (treated as an "on" flag)

`--watch-path` supplies additional paths to trigger the test-runner to re-run.

<table>
<thead>
<tr>
<th>Description</th>
<th>Code sample</th>
<th>Resulting <code>--test</code> value</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Test & watch modes enabled with defaults
</td>
<td>

```sh
node
--test
--watch
```

</td>
<td>

`**/*.test.{cjs,cts,mjs,mts,js,ts}`
etc

https://nodejs.org/api/test.html#running-tests-from-the-command-line

</td>
</tr>

<tr>
<td>
Test & watch modes enabled, overriding default
</td>
<td>

```sh
node
--test ./src/foo/*.test.js
--watch
```

</td>
<td>

`./src/foo/*.test.js`

</td>
</tr>

<tr>
<td>
Test & watch modes enabled, multiple test paths & additional watch paths
</td>
<td>

```sh
node
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
--watch
--watch-path ./src/quz/fixt.json
```

</td>
<td>

`./src/foo/*.test.js`
`./src/bar/*.test.js`

In addition to changes within the graph of those test, tests will also re-run if `./src/quz/fixt.json` changes.

</td>
</tr>

</tbody>
</table>

### Option: Break all the things

Currently `watch` has 2 flags (which are redundant):

```sh title='reads "main" etc from package.json'
node --watch
```
```sh
node --watch ./src/not-pjson-main.js
```
```sh
node
--watch ./src/not-pjson-main.js
--watch-path ./src/**/*.js
```

This could be simplified into just 1 `--watch` flag (where the default value is a single-element array of the derived entrypoint).

```sh title='reads "main" etc from package.json'
node --watch
```
```sh title='override derived entrypoint'
node --watch ./src/not-pjson-main.js
```
```sh title='package.json "main" + an additional path'
node --watch ./src/**/*.js
```
```sh title='explicit entrypoint + additional paths'
node
--watch ./assets/**
--watch ./src/**/*.js
./src/not-pjson-main.js
```

An explicit entrypoint, like all node commands, must come last and must be a relative or absolute path (not a glob/pattern).
Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this tracks for test. Many users will only want to pass a single glob pattern; at least I know that I do! What would the explicit entry point do for a test script?

Copy link
Member Author

@JakobJingleheimer JakobJingleheimer Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, okay, fair. So when watch mode is combined with test mode, shall we say that entry-point is not applicable—it's only applicable for watch mode separately?


`test` would then work the same way:

```sh title='reads "main" etc from package.json'
node --test
```
```sh title='package.json "main" + an additional path'
node --test ./src/**/*.test.js
```
```sh title='explicit entrypoint + an additional path'
node
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
./src/not-pjson-main.js
Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would the purpose of this be? The test runner runs for the two glob patterns and then does what with this entry point script? Executes it as a test too or just as a regular node script?

Copy link
Member Author

@JakobJingleheimer JakobJingleheimer Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, yes, true. Let's say there is no such thing as an entry-point for test mode (I think that doesn't exist currently either). If there's any "entry-point" when --test is present, throw.

I think in order to run an arbitrary script, it should be done with --import (and friends); otherwise, you get into inception.

node
  --import ./test/env.setup.js
  --import ./test/fix-snapshot-naming.js
  --test ./src/foo/*.test.js
  --test ./src/bar/*.test.js

Comment on lines +171 to +183
Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this section still needs to be updated, no? Test runs don't use main entrypoint or any entrypoint for that matter. It uses file patterns matching test files.

```

#### All together

`--watch` receives a clone of `--test`'s resolved value(s) **plus** `--watch`'s own values—with 1 exception: when both `test` and `watch` modes are enabled, `--watch` does not include a default entrypoint (it's irrelevant and it would likely result in perf waste at best, and unexpected behaviour at worst).

All examples are sequence-independent (all within the same heading behave the same).

##### Watch + test paths & main entrypoint:

```sh
node
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
--watch
./src/not-pjson-main.js
Comment on lines +198 to +199
Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't believe an newline character would change the CLI parsing here. This is the same as specifying a path for --watch. Or am I mistaken?

```
```sh
node
--watch
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
./src/not-pjson-main.js
```

##### Without an entrypoint (just paths):

```sh
node
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
--watch
```
```sh
node
--watch
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
```

##### _Additional_ watch paths

```sh
node
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
--watch ./src/**/*.js
```
```sh
node
--watch ./src/**/*.js
--test ./src/foo/*.test.js
--test ./src/bar/*.test.js
```

### Option: Apply `--watch`'s current design to `--test`

`--test` is optional and optionally accepts 1 value, whose value defaults to node's built-in glob defaults (`./src/**/*.test.(c|m)?(j|t)s`, etc). Additional paths are supplied via a new `--test-path` flag:

<table>
<thead>
<tr>
<th>Description</th>
<th>Code sample</th>
<th>Resulting <code>--test</code> value</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Override default
</td>
<td>

```sh
node --test ./src/foo/*.test.js
```

</td>
<td>

`./src/foo/*.test.js`

</td>
</tr>

<tr>
<td>
Override default & Set additional path
</td>
<td>

```sh
node
--test ./src/foo/*.test.js
--test-path ./src/bar/*.test.js
```

</td>
<td>

`./src/foo/*.test.js`
`./src/bar/*.test.js`

</td>
</tr>

<tr>
<td>
Defaults + Additional paths
</td>
<td>

```sh
node
--test
--test-path ./src/foo/*.test.js
--test-path ./src/bar/*.test.js
```

</td>
<td>

`./src/**/*.test.(c|m)?(j|t)s`
~`./src/foo/*.test.js`~
~`./src/bar/*.test.js`~

which reduces to only the default: `./src/**/*.test.(c|m)?(j|t)s`

</td>
</tr>

<tr>
<td>
No defaults & Additional paths
</td>
<td>

```sh
node
--test-path ./src/foo/*.test.js
--test-path ./src/bar/*.test.js
```

</td>
<td>

`./src/foo/*.test.js`
`./src/bar/*.test.js`

</td>
</tr>

</tbody>
</table>