# How to Run Unit Tests for God's Eye View: Complete Guide to the Node.js Test Runner

> Learn to run unit tests for God's Eye View using Node's built-in test runner. Execute npm test to discover and run all test files automatically.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Execute `npm test` after installing dependencies to run the complete unit test suite, which automatically discovers all `*.test.mjs` files under `src/` and orchestrates both parallel tests and serialized allocation benchmarks using Node's built-in test runner.**

God's Eye View provides a sophisticated automated testing framework implemented in `scripts/run-unit-tests.mjs`. This system leverages Node.js's native test runner to discover, categorize, and execute tests without requiring external testing frameworks like Jest or Mocha. Understanding how to run unit tests for God's Eye View ensures you can validate changes to the codebase effectively while respecting the specific runtime requirements for allocation-sensitive benchmarks.

## Prerequisites and Node.js Version Requirements

Before executing tests, verify that your environment meets the engine constraints defined in [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json). The project requires Node.js version **≥24.14.0 <25** or **≥26 <27**. However, the allocation benchmark tests specifically depend on a calibrated Node.js 24 runtime and will skip automatically if you're running Node.js 26 or other versions.

## Running the Test Suite

### Basic Execution with npm

The standard method for running the entire test suite uses the npm script defined in the project's [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json):

```bash

# Install dependencies first

npm ci

# Execute the full test suite

npm test

```

This command invokes `node scripts/run-unit-tests.mjs`, which orchestrates test discovery and execution.

### Direct Script Invocation

Alternatively, run the test runner explicitly without npm:

```bash
node scripts/run-unit-tests.mjs

```

## How the Test Runner Works

The `scripts/run-unit-tests.mjs` file implements a three-phase pipeline for test execution.

### Phase 1: Test Discovery

The `discoverUnitTestFiles()` function recursively walks the `src/` directory tree and returns an array of all files ending with `.test.mjs`. This automated discovery eliminates the need to maintain a manual test manifest or import registry.

### Phase 2: Test Plan Construction

The `buildUnitTestPlan()` function splits the discovered files into two execution groups:

- **Parallel tests**: The majority of test files that can run concurrently for optimal performance.
- **Serialized allocations**: Two specific micro-benchmarks—`src/data/focusAllocations.test.mjs` and `src/overlays/worldOverlayAllocation.test.mjs`—that require sequential execution due to memory measurement calibration requirements.

### Phase 3: Test Execution

The `runTests()` function spawns child Node processes with appropriate flags for each group. Standard parallel tests execute with the `--test` flag. Allocation benchmarks require `--expose-gc` and `--test-concurrency=1` to expose garbage collection and force single-threaded execution, ensuring accurate memory measurements.

## Handling Allocation Benchmark Constraints

### Runtime Version Detection

If the current Node.js version is not the calibrated Node 24 runtime, the test runner automatically skips the two allocation benchmark tests with a warning message. Standard parallel tests continue to execute normally regardless of the Node version (provided it meets the general engine requirements).

### Forcing Strict Allocation Gate Behavior

To prevent silent skipping of allocation benchmarks and instead force a hard failure when running on incompatible Node versions, set the environment variable:

```bash
GEV_REQUIRE_ALLOCATION_GATE=1 npm test

```

When `GEV_REQUIRE_ALLOCATION_GATE=1` is present and the runtime isn't Node 24, the process exits with an error rather than skipping the allocation tests.

## Summary

- **Entry point**: Run `npm test` or `node scripts/run-unit-tests.mjs` to execute the complete suite.
- **Test discovery**: The `discoverUnitTestFiles()` function automatically locates all `*.test.mjs` files under `src/`.
- **Execution model**: Tests run in parallel groups, except for allocation benchmarks which serialize via `buildUnitTestPlan()`.
- **Node.js 24 requirement**: Allocation benchmarks in `src/data/focusAllocations.test.mjs` and `src/overlays/worldOverlayAllocation.test.mjs` require specifically Node.js 24.x.
- **Strict mode**: Set `GEV_REQUIRE_ALLOCATION_GATE=1` to enforce allocation test execution or fail the build.

## Frequently Asked Questions

### What file pattern does God's Eye View use for unit tests?

The test runner discovers any file ending with `.test.mjs` located within the `src/` directory tree. This convention allows the `discoverUnitTestFiles()` function in `scripts/run-unit-tests.mjs` to automatically locate and register tests without requiring manual imports or a configuration manifest.

### Why are my allocation benchmark tests being skipped?

The allocation benchmarks—specifically `src/data/focusAllocations.test.mjs` and `src/overlays/worldOverlayAllocation.test.mjs`—require a calibrated Node.js 24 runtime to ensure consistent memory measurements. If you're running Node.js 26 or another version, these tests skip automatically to prevent inaccurate benchmark results, while all parallel tests execute normally.

### How does the test runner handle memory-sensitive benchmarks?

The runner isolates allocation-sensitive tests via `buildUnitTestPlan()`, placing them in the `serializedAllocations` group. These execute with `--expose-gc` and `--test-concurrency=1` flags to expose garbage collection APIs and prevent concurrent execution that could skew memory measurements.

### What happens if I set GEV_REQUIRE_ALLOCATION_GATE=1 on Node 26?

If you set `GEV_REQUIRE_ALLOCATION_GATE=1` while running on Node.js 26 or any non-Node-24 runtime, the test suite fails with an error rather than skipping the allocation benchmarks. This environment variable acts as a strict gate for CI/CD pipelines that must validate allocation performance on the calibrated Node 24 runtime.