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

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. 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:

# 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:

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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}