0
# Global Environment Management
1

2
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.
3

4
## Capabilities
5

6
### Install Common Globals
7

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

10
```typescript { .api }
11
/**
12
 * Sets up Jest global environment with necessary polyfills and globals
13
 * @param globalObject - Target global object to enhance
14
 * @param globals - Jest configuration globals to install
15
 * @param garbageCollectionDeletionMode - Optional GC deletion mode for cleanup
16
 * @returns Enhanced global object with Jest globals
17
 */
18
function installCommonGlobals(
19
  globalObject: typeof globalThis,
20
  globals: Config.ConfigGlobals,
21
  garbageCollectionDeletionMode?: DeletionMode
22
): typeof globalThis & Config.ConfigGlobals;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { installCommonGlobals } from "jest-util";
29
import type { Config } from "@jest/types";
30

31
// Set up Jest globals in a test environment
32
const testGlobals: Config.ConfigGlobals = {
33
  __DEV__: true,
34
  __TEST__: true,
35
  process: { env: { NODE_ENV: "test" } }
36
};
37

38
// Install globals with garbage collection cleanup
39
const enhancedGlobal = installCommonGlobals(
40
  globalThis, 
41
  testGlobals, 
42
  'soft' // Enable soft deletion mode
43
);
44

45
// Now the global object has Jest-specific enhancements:
46
// - Sandboxed process object
47
// - Jest-specific symbols for native functions
48
// - DTRACE API forwarding
49
// - Garbage collection utilities if specified
50
```
51

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

59
### Set Global
60

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

63
```typescript { .api }
64
/**
65
 * Sets a property on global object with optional GC protection
66
 * @param globalToMutate - Global object to modify
67
 * @param key - Property key (string or symbol)
68
 * @param value - Property value
69
 * @param afterTeardown - Whether to protect from GC after teardown ('clean' | 'retain')
70
 */
71
function setGlobal(
72
  globalToMutate: typeof globalThis | Global.Global,
73
  key: string | symbol,
74
  value: unknown,
75
  afterTeardown: 'clean' | 'retain' = 'clean'
76
): void;
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
import { setGlobal } from "jest-util";
83

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

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

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

94
// Using symbols as keys
95
const testSymbol = Symbol("jest-test-marker");
96
setGlobal(globalThis, testSymbol, true);
97
```
98

99
**Teardown Behavior:**
100
- **'clean' (default)**: Property will be cleaned up during garbage collection after test teardown
101
- **'retain'**: Property will be protected from garbage collection and persist
102

103
## Types
104

105
```typescript { .api }
106
// From @jest/types
107
interface Config.ConfigGlobals {
108
  [key: string]: any;
109
}
110

111
interface Global.Global {
112
  [key: string]: any;
113
}
114

115
// From garbage-collection-utils
116
type DeletionMode = 'soft' | 'off' | 'on';
117
```
118

119
**Integration with Garbage Collection:**
120

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

123
```typescript
124
import { installCommonGlobals, setGlobal } from "jest-util";
125

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

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