test() — astro Function Reference

Architecture documentation for the test() function in test.js from the astro codebase.

Function javascript CoreAstro CoreMiddleware

Entity Profile

CoreAstro→ CoreMiddleware→ test() — astro Function Reference

Dependency Diagram

graph TD
  78ec99b6_674c_e423_4ad3_1e94e325af46["test()"]
  28f6891b_4087_59e7_aeca_d1972ad6d0b2["test.js"]
  78ec99b6_674c_e423_4ad3_1e94e325af46 -->|defined in| 28f6891b_4087_59e7_aeca_d1972ad6d0b2
  style 78ec99b6_674c_e423_4ad3_1e94e325af46 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

scripts/cmd/test.js lines 13–114

export default async function test() {
	const args = parseArgs({
		allowPositionals: true,
		options: {
			// aka --test-name-pattern: https://nodejs.org/api/test.html#filtering-tests-by-name
			match: { type: 'string', alias: 'm' },
			// aka --test-only: https://nodejs.org/api/test.html#only-tests
			only: { type: 'boolean', alias: 'o' },
			// aka --test-concurrency: https://nodejs.org/api/test.html#test-runner-execution-model
			parallel: { type: 'boolean', alias: 'p' },
			// experimental: https://nodejs.org/api/test.html#watch-mode
			watch: { type: 'boolean', alias: 'w' },
			// Test timeout in milliseconds (default: 30000ms)
			timeout: { type: 'string', alias: 't' },
			// Test setup file
			setup: { type: 'string', alias: 's' },
			// Test teardown file
			teardown: { type: 'string' },
			// Use tsx to run the tests,
			tsx: { type: 'boolean' },
			// Configures the test runner to exit the process once all known tests have finished executing even if the event loop would otherwise remain active
			'force-exit': { type: 'boolean' },
			// Test teardown file to include in the test files list
			'teardown-test': { type: 'string' },
		},
	});

	const pattern = args.positionals[1];
	if (!pattern) throw new Error('Missing test glob pattern');

	const files = await glob(pattern, {
		filesOnly: true,
		absolute: true,
		ignore: ['**/node_modules/**'],
	});

	if (args.values['teardown-test']) {
		files.push(path.resolve(args.values['teardown-test']));
	}

	// For some reason, the `only` option does not work and we need to explicitly set the CLI flag instead.
	// Node.js requires opt-in to run .only tests :(
	// https://nodejs.org/api/test.html#only-tests
	if (args.values.only) {
		process.env.NODE_OPTIONS ??= '';
		process.env.NODE_OPTIONS += ' --test-only';
	}

	if (args.values.tsx) {
		process.env.NODE_OPTIONS ??= '';
		process.env.NODE_OPTIONS += ' --import tsx';
	}

	if (!args.values.parallel) {
		// If not parallel, we create a temporary file that imports all the test files
		// so that it all runs in a single process.
		const tempTestFile = path.resolve('./node_modules/.astro/test.mjs');
		await fs.mkdir(path.dirname(tempTestFile), { recursive: true });
		await fs.writeFile(
			tempTestFile,
			files.map((f) => `import ${JSON.stringify(pathToFileURL(f).toString())};`).join('\n'),
		);

		files.length = 0;
		files.push(tempTestFile);
	}

	const teardownModule = args.values.teardown
		? await import(pathToFileURL(path.resolve(args.values.teardown)).toString())
		: undefined;

	const setupModule = args.values.setup
		? await import(pathToFileURL(path.resolve(args.values.setup)).toString())
		: undefined;

	// https://nodejs.org/api/test.html#runoptions
	run({
		files,
		testNamePatterns: args.values.match
			? args.values['teardown-test']
				? [args.values.match, 'Teardown']