start-local should switch Node itself, and there should be a script for running the test suites #140

New Issue

2026-08-23T08:54:21-05:00

bermudalamb commented

2026-08-23 08:54:21 -05:00

scripts/start-local.ps1 knows exactly what is wrong when the Node version is too old, and then makes the developer fix it by hand. Assert-NodeVersion reads node --version, finds a major below 20, and throws a message telling you to run nvm use 24.13.1 and start again in a new shell. It is a good error, but it is an error for a problem the script could simply solve — and on this machine nvm's default is 18.16.1, so it is hit on every fresh shell.

The reason it matters is documented in the script itself: node-pg-migrate pulls in an lru-cache that calls diagnostics_channel.tracingChannel(), which does not exist before Node 19.9, so on Node 18 migrations die inside minified library code with (0 , U.tracingChannel) is not a function — a message that says nothing about versions.

start-local.ps1 should run nvm use latest itself, then confirm the version it landed on is actually new enough rather than assuming the switch worked. -Stop should put the machine back to nvm use 18.16.1.

Worth being explicit about the tradeoff, because it is not obvious: nvm use rewrites a machine-global symlink, so this changes the Node version for every shell on the box, not just this project's. That is the intended behaviour here, but the script should say so when it switches rather than changing the developer's environment silently.

Running the tests

There is no script for the test suites, so running them means remembering which directory each lives in, that the integration suite needs npm run db:test:up first, and that the e2e suite needs a backend and a dev server already up. Each suite also needs Node 20+, for the same reason start-local does.

Add a PowerShell script that runs them: run-tests.ps1 -Suite unit|integration|e2e|all. One script with a parameter rather than three, so the Node version switch, the database bring-up and the TEST_PGPORT handling live in one place instead of being repeated and drifting.

Acceptance criteria

start-local.ps1 switches to the latest installed Node itself and verifies the result is 20 or newer, failing clearly if it is not
start-local.ps1 -Stop reverts to 18.16.1
Both say plainly that the switch is machine-wide
A reverting path exists for a start that fails partway, so an interrupted run does not leave the machine switched
run-tests.ps1 -Suite unit|integration|e2e|all runs each suite, bringing up whatever that suite needs first
The scripts are documented in the README beside the existing instructions

`scripts/start-local.ps1` knows exactly what is wrong when the Node version is too old, and then makes the developer fix it by hand. `Assert-NodeVersion` reads `node --version`, finds a major below 20, and throws a message telling you to run `nvm use 24.13.1` and start again in a new shell. It is a good error, but it is an error for a problem the script could simply solve — and on this machine nvm's default is 18.16.1, so it is hit on every fresh shell. The reason it matters is documented in the script itself: `node-pg-migrate` pulls in an `lru-cache` that calls `diagnostics_channel.tracingChannel()`, which does not exist before Node 19.9, so on Node 18 migrations die inside minified library code with `(0 , U.tracingChannel) is not a function` — a message that says nothing about versions. `start-local.ps1` should run `nvm use latest` itself, then confirm the version it landed on is actually new enough rather than assuming the switch worked. `-Stop` should put the machine back to `nvm use 18.16.1`. Worth being explicit about the tradeoff, because it is not obvious: `nvm use` rewrites a machine-global symlink, so this changes the Node version for every shell on the box, not just this project's. That is the intended behaviour here, but the script should say so when it switches rather than changing the developer's environment silently. ### Running the tests There is no script for the test suites, so running them means remembering which directory each lives in, that the integration suite needs `npm run db:test:up` first, and that the e2e suite needs a backend and a dev server already up. Each suite also needs Node 20+, for the same reason `start-local` does. Add a PowerShell script that runs them: `run-tests.ps1 -Suite unit|integration|e2e|all`. One script with a parameter rather than three, so the Node version switch, the database bring-up and the `TEST_PGPORT` handling live in one place instead of being repeated and drifting. ### Acceptance criteria - `start-local.ps1` switches to the latest installed Node itself and verifies the result is 20 or newer, failing clearly if it is not - `start-local.ps1 -Stop` reverts to 18.16.1 - Both say plainly that the switch is machine-wide - A reverting path exists for a start that fails partway, so an interrupted run does not leave the machine switched - `run-tests.ps1 -Suite unit|integration|e2e|all` runs each suite, bringing up whatever that suite needs first - The scripts are documented in the README beside the existing instructions

bermudalamb commented

2026-08-23 08:54:34 -05:00

Clarifying questions and answers, recorded here so the decisions are not only in a chat log.

Q: nvm use changes the Node version machine-wide rather than per-shell. Switch globally as asked, prepend to PATH within the script only, or switch globally with a revert on any exit?

A: Switch globally, as asked, and revert on any exit rather than only on -Stop. The global switch is the point — the developer wants their other terminals on the new version too while the stack is up, which a PATH prepend inside the script would not give them, and a PATH prepend would also leave -Stop with nothing to undo. The revert-on-any-exit is the safe form of the same behaviour: without it, a start that fails partway through migrations leaves the machine switched with nothing having been started, and the -Stop that would put it back is never run. Both paths say plainly that the change is machine-wide, so it is never silent.

Q: How should the test runner scripts be split — one script with a suite parameter, one per suite, or a fast/full split?

A: One script, run-tests.ps1 -Suite unit|integration|e2e|all. The Node version switch, the db:test:up bring-up and the TEST_PGPORT handling are shared by more than one suite, and three scripts would each carry a copy to drift out of step. A fast/full split was considered and rejected for the same reason — it still duplicates the setup across two files while making the suite names less obvious than naming them directly.

Clarifying questions and answers, recorded here so the decisions are not only in a chat log. **Q: `nvm use` changes the Node version machine-wide rather than per-shell. Switch globally as asked, prepend to PATH within the script only, or switch globally with a revert on any exit?** A: Switch globally, as asked, and revert on any exit rather than only on `-Stop`. The global switch is the point — the developer wants their other terminals on the new version too while the stack is up, which a PATH prepend inside the script would not give them, and a PATH prepend would also leave `-Stop` with nothing to undo. The revert-on-any-exit is the safe form of the same behaviour: without it, a start that fails partway through migrations leaves the machine switched with nothing having been started, and the `-Stop` that would put it back is never run. Both paths say plainly that the change is machine-wide, so it is never silent. **Q: How should the test runner scripts be split — one script with a suite parameter, one per suite, or a fast/full split?** A: One script, `run-tests.ps1 -Suite unit|integration|e2e|all`. The Node version switch, the `db:test:up` bring-up and the `TEST_PGPORT` handling are shared by more than one suite, and three scripts would each carry a copy to drift out of step. A fast/full split was considered and rejected for the same reason — it still duplicates the setup across two files while making the suite names less obvious than naming them directly.

bermudalamb added this to the Code Quality and Hardening 2 project 2026-08-23 09:01:46 -05:00

bermudalamb self-assigned this 2026-08-23 09:01:52 -05:00

bermudalamb removed their assignment 2026-08-23 09:06:28 -05:00

bermudalamb referenced this issue from a commit

2026-08-23 09:35:38 -05:00

feat(scripts): switch Node automatically, and add a test runner (#140)

bermudalamb referenced a pull request that will close this issue

2026-08-23 09:36:01 -05:00

feat(scripts): switch Node automatically, and add a test runner (#140) #144

bermudalamb added reference feature/140-node-scripts

2026-08-23 09:36:21 -05:00

bermudalamb referenced this issue from a commit