tessl/npm-jest-util

Collection of utility functions for Jest testing framework

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Global Environment Management

Name: tessl/npm-jest-util
Author: tessl

Utilities for setting up and managing Jest's global test environment, including process object creation and global property management. These functions enable Jest to create isolated test environments with proper global object setup.

Capabilities

Install Common Globals

Sets up Jest's global environment with necessary polyfills and globals, creating a sandboxed environment for test execution.

/**
 * Sets up Jest global environment with necessary polyfills and globals
 * @param globalObject - Target global object to enhance
 * @param globals - Jest configuration globals to install
 * @param garbageCollectionDeletionMode - Optional GC deletion mode for cleanup
 * @returns Enhanced global object with Jest globals
 */
function installCommonGlobals(
  globalObject: typeof globalThis,
  globals: Config.ConfigGlobals,
  garbageCollectionDeletionMode?: DeletionMode
): typeof globalThis & Config.ConfigGlobals;

Usage Examples:

import { installCommonGlobals } from "jest-util";
import type { Config } from "@jest/types";

// Set up Jest globals in a test environment
const testGlobals: Config.ConfigGlobals = {
  __DEV__: true,
  __TEST__: true,
  process: { env: { NODE_ENV: "test" } }
};

// Install globals with garbage collection cleanup
const enhancedGlobal = installCommonGlobals(
  globalThis, 
  testGlobals, 
  'soft' // Enable soft deletion mode
);

// Now the global object has Jest-specific enhancements:
// - Sandboxed process object
// - Jest-specific symbols for native functions
// - DTRACE API forwarding
// - Garbage collection utilities if specified

Features:

Process Object Creation: Creates sandboxed process object using createProcessObject()
Symbol Setup: Establishes Jest-specific symbols for native function preservation
DTRACE Integration: Forwards DTRACE APIs for performance monitoring
Garbage Collection: Initializes GC utilities when deletion mode is specified
Global Merging: Safely merges Jest globals with existing global object

Set Global

Sets a property on the global object with optional protection from garbage collection during test teardown.

/**
 * Sets a property on global object with optional GC protection
 * @param globalToMutate - Global object to modify
 * @param key - Property key (string or symbol)
 * @param value - Property value
 * @param afterTeardown - Whether to protect from GC after teardown ('clean' | 'retain')
 */
function setGlobal(
  globalToMutate: typeof globalThis | Global.Global,
  key: string | symbol,
  value: unknown,
  afterTeardown: 'clean' | 'retain' = 'clean'
): void;

Usage Examples:

import { setGlobal } from "jest-util";

// Set test-specific globals
setGlobal(globalThis, "__JEST_VERSION__", "30.0.5");
setGlobal(globalThis, "mockDatabase", mockDb);

// Set globals that should persist after test teardown
setGlobal(globalThis, "__PERSISTENT_CONFIG__", config, 'retain');

// Set globals that should be cleaned up (default behavior)
setGlobal(globalThis, "__TEMP_TEST_DATA__", testData, 'clean');

// Using symbols as keys
const testSymbol = Symbol("jest-test-marker");
setGlobal(globalThis, testSymbol, true);

Teardown Behavior:

'clean' (default): Property will be cleaned up during garbage collection after test teardown
'retain': Property will be protected from garbage collection and persist

Types

// From @jest/types
interface Config.ConfigGlobals {
  [key: string]: any;
}

interface Global.Global {
  [key: string]: any;
}

// From garbage-collection-utils
type DeletionMode = 'soft' | 'off' | 'on';

Integration with Garbage Collection:

The global environment utilities work closely with Jest's garbage collection system:

import { installCommonGlobals, setGlobal } from "jest-util";

// Install globals with garbage collection enabled
const globals = installCommonGlobals(globalThis, testConfig, 'soft');

// Set globals that will be managed by the GC system
setGlobal(globals, "testData", data, 'clean'); // Will be cleaned up
setGlobal(globals, "persistentConfig", config, 'retain'); // Will persist