Global setup file for native node test runner

[jamm3e3333]

What is the problem this feature will solve?

I'm sorry if there's already such a feature and I haven't found a way how to solve this. Basically what I'm looking for is to run some function that would run beofre all the tests and setup the environment. So far the only way how to setup some environment is doing it with the run function but that is only limited for each test suite from what I've tried. I would love to have the have some setup file in the way how does it work for example in jest or mocha or other testing framework.

What is the feature you are proposing to solve the problem?

Have a setup.js/setup.ts file that will run before all the tests, you would somehow specify in command that starts the tests this setup file.

What alternatives have you considered?

node version: v20.6.1
npm version: 9.8.1

I've tried this setup file

setup.ts

import { performance } from 'perf_hooks'
import { run } from 'node:test'

run({
    files: ['src/node-test-runner/suite.test.ts'],
    setup: () => {
        let memStats: Record<string | number, number> = {};
        const perf = performance;

        const start = perf.now();
        const cpuUsage = process.cpuUsage()

        process.nextTick(() => {
            const current = process.memoryUsage();
            for (const key in current) {
              memStats[key] = Math.max(memStats[key] ?? 0, current[key as keyof ReturnType<typeof process.memoryUsage>]);
            }
          });

          process.on("exit", () => {
            logger.info({
              memStats,
              timeMilliseconds: perf.now() - start,
              cpuUsage: process.cpuUsage(cpuUsage),
              pid: process.pid,
            });
          });
    },
})

suite.test.ts

import { describe, it } from 'node:test'
import {equal} from 'node:assert'
import { testBody } from '../index'
import { logger } from '../logger'

const TEST_ITERATIONS = Number(process.env.TEST_ITERATIONS);

describe(__filename, () => {
    it(`${__filename}`, async () => {
            equal(true, true)
    })
})

and I'm running this command to execute tests: node --require ts-node/register --test

but neither the setup.ts file is executed nor the suite.test.ts file is executed

[Twipped]

I think the issue I'm having is related to this.

I'm writing an internal utility for our tests that is built around the native test-runner. I need to make sure a module executes inside each test process before the test file is actually run. The --import flag works for this if invoking node --test directly, but I haven't found a way to do this when using the run function. Simply importing the module before invoking run doesn't do the job, because the tests all execute in separate child processes. Is there some way to programmatically inject an --import flag?

edit:
I solved it by pushing to execArgv, but it'd be nice if there was an official API for this.

process.execArgv.push('--import', path.resolve(__dirname, 'index.js'));

[koshic]

I solved it by pushing to execArgv, but it'd be nice if there was an official API for this.

It's always been here - https://nodejs.org/dist/latest-v21.x/docs/api/cli.html#node_optionsoptions. Just set that variable in process.env before run call.

[Twipped]

@koshic I'd still consider that a hack compared to explicitly having a means of specifying flags and env on the run options.

[fvictorio]

Thanks for sharing the workaround @Twipped!

I agree it feels like a hack, especially because both using process.execArgv.push and process.env.NODE_OPTIONS are passed down to the tests. This means that if the tests also start child processes for some reason, then those will also load the setup module (probably not important in practice, but it feels wrong).

I guess a way to fix that is to start your setup module with process.execArgv.splice(-2). But having some sort of builtin solution would be great.

[mdrobny]

My use cases for global setup file is to e.g. start a database container or create local cloud resources before running integration tests.
All integration tests run in parallel and use the same database or cloud resource so it needs to be executed only once.
I prefer not to use run function because e.g. it doesn't cooperate well with running or debugging selected tests directly from editor

This functionality is supported by popular test runners:

• Jest: globalSetup and globalTeardown files defined in config
• Mocha: global setup and teardown fixtures file defined via CLI flag (--require) or in config
• Vitest: globalSetup file defined in config
• Playwright: globalSetup and globalTeardown files defined in config
• Bun: preload file with hooks defined via CLI flag or in config

Using --require or --import CLI flag is similar but it will run the "setup file" for every test file, instead of doing it just once. I could manage to use it if there would be a straightforward way of sharing info between different test child processes to know if setup was already started or finished.
But beside that, it doesn't provide a way to do a teardown as it was mentioned in the comments.

[bukowa]

Landed here looking for a global setup. Ideally in such a way that each of my tests receives the context I created in the global setup function.

globalSetup(context) {
    context.driver = something
}

test("Can ....", context){
    context.driver.do()
}

[mdrobny]

I have some ideas how to define globalSetup and globalTeardown functions but I don't know if they are possible to implement.
I am trying to avoid adding new command-line options

1. Use --import or --require option and new hooks

User defines a file, for example setup.js

import { globalSetup, globalTeardown } from 'node:test'

globalSetup(async () => {
  await prepareSomething()
})

globalTeardown(async () => {
  await cleanupSomething()
})

Then user runs tests like this

node --import setup.js --test

Challenges:

• setup.js will be executed for each test file but globalSetup and globalTeardown functions must be executed only once.
  So first globalSetup to execute, must register an async function to be executed before running test files
  First globalTeardown to execute, must register an async function to be executed after all tests completed (or failed).
• I am not sure if such communication between test file process and main process is possible

2. Use --import or --require option and export hooks

User defines a file, for example setup.js

export const globalSetup = async () => {
  await prepareSomething()
}

export const globalTeardown = async () => {
  await cleanupSomething()
}

Then user runs tests like this

node --import setup.js --test

Challenges:

• how to import from setup.js and execute globalSetup and globalTeardown functions in the main test runner process only

Pros:

• setup and teardown functions are not executed in every test file

3. Add new command-line options --test-setup and --test-teardown

User defines a file, for example setup.js

import { globalSetup } from 'node:test'

globalSetup(async () => {
  await prepareSomething()
})

and teardown.js

import { globalTeardown } from 'node:test'

globalTeardown(async () => {
  await cleanupSomething()
})

Then user runs tests like this

node --test-setup setup.js --test-teardown teardown.js --test

Challenges:

• how hard it is to import/require file provided via command-line option

Pros:

• run function in test runner already has setup option. teardown would need to be added

[cjihrig]

I think option 1 or 2 sound the best (they honestly sound like the same thing just a difference of where the hook function lives). A few things to note are:

• I believe --import and --require will run for each test file as well as the main runner process.
• node:test knows if the current process is the main runner or a test file. I think that would simplify some things such as needing to communicate between processes. It would also allow the test runner to "no-op" hooks in the appropriate places.
• Since the test files are all separate processes, users will need to know that a one time global setup will not be reflected in each child process. That's fine if you are doing something like starting a database, but will not work if you are doing something like defining a global variable.
• In the future, I'd really like to make it possible to run the test files in the same process. Any solution we come up with should keep that future use case in mind. For example, the limitation I listed above would no longer apply if everything were in the same process. Maybe that is fine to just document.
• We also need to keep the use case of running a single file without --test in mind. I think the solutions proposed here would work in that case, but wanted to point it out.

run function in test runner already has setup option. teardown would need to be added

We should probably add this anyway.

EDIT: After thinking a bit, option 1 is probably better. With option 2 the test runner will have to search for the exported functions in all cases, which slows things down.

[mdrobny]

So as mentioned in #54675, in Node 22.9 I managed to achieve globalSetup and globalTeardown feature by using test isolation none and before hook

node --import ./globalHooks.mjs --experimental-test-isolation=none --test 'src/**/*.test.js'`

globalHooks.mjs

import { after, before } from 'node:test';

before(async () => {
    await startDockerContainers();
});

after(async () => {
    await closeDatabaseConnections();
    await stopDockerContainers();
});

Works as expected 🎉 also with TypeScript (I need to test TS with ESM more though)

---

Does it mean that adding globalSetup and globalTeardown hooks to node:test is not needed anymore?
I would say not necessarily. Since process is the default isolation mode, I guess people may still have a need for them.
What do you think?

[benjamingr]

I'm wondering if we can do something like isMainRunner in test_runner like worker.isMainThread exists. That would let us do:

node --import ./globalHooks.mjs --test 'src/**/*.test.js'`

import { after, before, isMainRunner } from 'node:test';

if (isMainRunner) {
  before(async () => {
    await startDockerContainers();
  });

  after(async () => {
    await closeDatabaseConnections();
    await stopDockerContainers();
  });
}

Which would work regardless of isolation mode.

[cjihrig]

I think we ultimately need something similar to Mocha's global fixtures, which is guaranteed to run once and only once no matter the isolation mode. Otherwise we're pushing work on to users (work that will be duplicated for all projects that want this functionality) when it would be significantly easier for us to do it in the test runner. That way, users also only need to remember that these hooks always run in the same process as the test runner itself.

[olingern]

Just wanted to add to the thread because I was searching for TypeScript support with global setup and couldn't quite figure it out. I finally did, so I thought this might be helpful for others.

Using tsx, what the Node v22.x.x docs reference, I was able to write a TypeScript setup and test with no configuration

tsx --import ./tests/node/globalHooks.ts --experimental-test-isolation=none --test './**/*.test.{js,ts}'

globalHooks.ts

import { after, before } from 'node:test';

before(async () => {
  console.log('before');
});

after(async () => {
  console.log('after');
});

Output

[torbjornvatn]

This is gold @olingern. Been struggling with this for so long myself 🙇🏼

[doberkofler]

@mdrobny

So as mentioned in #54675, in Node 22.9 I managed to achieve globalSetup and globalTeardown feature by using test isolation none and before hook

node --import ./globalHooks.mjs --experimental-test-isolation=none --test 'src/**/*.test.js' globalHooks.mjs`

import { after, before } from 'node:test';

before(async () => {
await startDockerContainers();
});

after(async () => {
await closeDatabaseConnections();
await stopDockerContainers();
});
Works as expected 🎉 also with TypeScript (I need to test TS with ESM more though)

Does it mean that adding globalSetup and globalTeardown hooks to node:test is not needed anymore? I would say not necessarily. Since process is the default isolation mode, I guess people may still have a need for them. What do you think?

Just what I needed!

[cjihrig]

FYI - Node has an experimental config file now. Someone could try integrating that with the test runner.

[Fenykepy]

So as mentioned in #54675, in Node 22.9 I managed to achieve globalSetup and globalTeardown feature by using test isolation none and before hook

node --import ./globalHooks.mjs --experimental-test-isolation=none --test 'src/**/*.test.js' globalHooks.mjs`

import { after, before } from 'node:test';

before(async () => {
await startDockerContainers();
});

after(async () => {
await closeDatabaseConnections();
await stopDockerContainers();
});
Works as expected 🎉 also with TypeScript (I need to test TS with ESM more though)

Does it mean that adding globalSetup and globalTeardown hooks to node:test is not needed anymore? I would say not necessarily. Since process is the default isolation mode, I guess people may still have a need for them. What do you think?

This doesn't work as expected with async setup when before is used in other tests modules:

tsx --import ./tests/node/globalHooks.ts --experimental-test-isolation=none --test './**/*.test.{js,ts}'

globalHooks.ts

import { after, before } from 'node:test';

async function setupDatabase() {
    // some async stuff
};

async function seedDatabase() {
  // some async stuff
};

async function closeDatabaseConnection() {
  // some async stuff
};

before(async () => {
  console.log('before all');
  await setupDatabase();
  await seedDatabase();
  console.log('database ready');
});

after(async () => {
  console.log('after all');
  await closeDatabaseConnection();
  console.log('connection closed');
});

someFunction.test.ts

import { after, before, suite, test } from 'node:test';

async function createSomeDatabaseObjects() {
  // async stuff, must run after resetDatabase()
};

before(async () => {
  console.log('before suite');
  await createSomeDatabaseObjects(); // fails, database isn't ready yet
  console.log('database objects created');
});

after(async () => {
  console.log('after suite');
});

suite("Suite of someFunction", () => {
  test("someFunction should work as expected", () => {
    // some tests
  });
});

Output:

before all
before suite // should run after database ready
database ready
after all
connection closed
after suite // should run before after all

Any idea? (for moment, I'm avoid using before and after in tests modules but it's quite annoying...)

[Fenykepy]

I found that wrapping whole module in a main suite works, albeit it's nowhere written in docs that sub-suites are allowed.

someFunction.test.ts

import { after, before, suite, test } from 'node:test';

async function createSomeDatabaseObjects() {
  // async stuff, must run after resetDatabase()
};

suite("Suite of module someFunction", () => {
  before(async () => {
    console.log('before suite');
    await createSomeDatabaseObjects(); // fails, database isn't ready yet
    console.log('database objects created');
  });

  after(async () => {
    console.log('after suite');
  });

  suite("Suite of someFunction", () => {
    test("someFunction should work as expected", () => {
      // some tests
    });
  });

  // other suites and tests
});

Output:

before all
database ready
before suite // ok
after suite // ok
after all
connection closed

[github-actions]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Issues and PRs exempt from automated stale handling. label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.

[doberkofler]

@Fenykepy

I found that wrapping whole module in a main suite works, albeit it's nowhere written in docs that sub-suites are allowed.

This would clearly be be most convenient way to solve this if all tests are in a single source file but in my use case i have multiple files that expect some resources to be available and later be be disposed.

[doberkofler]

I resolved my use case by using something like node --import ./tests/global_hooks.ts --experimental-test-isolation=none --test --test-concurrency=1 "./tests/**/*.test.ts" but still believe that Node.js could offer a better DX by offering a configuration option to explicitly define setup and teardown like other test runner:

• Jest: globalSetup and globalTeardown
• Mocha: global setup and teardown fixtures
• Vitest: globalSetup file defined in config
• Playwright: globalSetup and globalTeardown files defined in config

[pmarchini]

I resolved my use case by using something like node --import ./tests/global_hooks.ts --experimental-test-isolation=none --test --test-concurrency=1 "./tests/**/*.test.ts" but still believe that Node.js could offer a better DX by offering a configuration option to explicitly define setup and teardown like other test runner:

• Jest: globalSetup and globalTeardown
• Mocha: global setup and teardown fixtures
• Vitest: globalSetup file defined in config
• Playwright: globalSetup and globalTeardown files defined in config

Hey @doberkofler actually we now provide https://nodejs.org/api/test.html#global-setup-and-teardown!

[Twipped]

@pmarchini that's great, thank you, but it also means yet another flag I'm having to include in my test command just to get the suite to work. Has anyone talked about a config file for all this stuff?

[pmarchini]

Hey @Twipped, we’ve introduced a new experimental feature: https://nodejs.org/api/cli.html#--experimental-config-fileconfig
.
With the experimental config file, it's possible to avoid setting all the flags via the CLI.

[Twipped]

@pmarchini excellent, thank you!

[alxmrtn]

@pmarchini I've been trying to get tests to run using the globalSetup and globalTeardown functions, and I've noticed that globalTeardown sometimes begins to execute before all test files are finished executing without--test-concurrency=1 set. Is this a known issue?

edit. adding example:

[pmarchini]

Hey @alxmrtn, thanks for reporting it!
Could I please ask you to verify whether it's only a matter of output, or if the teardown actually happens before all tests complete?

e.g., I would expect test failures if the DB really gets wiped before the completion of dependent tests.

(I've noticed issues with the order of the printed output before, so I'm wondering if that's the case!)

Note: I'm closing this issue, as the feature request has been completed.
If what you're reporting is actually a bug, I will ask you to open an issue with a minimal repro

[alxmrtn]

@pmarchini let me add some more db heavy tests and get back to you. if I keep seeing it I'll open up an issue - thanks!