0
# State Management
1

2
Low-level state management for controlling test execution state and accessing runtime information. The state system provides centralized tracking of test execution progress, errors, and configuration.
3

4
## Capabilities
5

6
### State Access Functions
7

8
Functions for getting, setting, and resetting the global circus state.
9

10
```typescript { .api }
11
/**
12
 * Get the current circus state
13
 * @returns Current state object
14
 */
15
function getState(): State;
16

17
/**
18
 * Set the circus state
19
 * @param state - New state object
20
 * @returns The state that was set
21
 */
22
function setState(state: State): State;
23

24
/**
25
 * Reset state to initial values
26
 */
27
function resetState(): void;
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import { getState, setState, resetState } from "jest-circus";
34

35
// Get current state
36
const currentState = getState();
37
console.log("Current test:", currentState.currentlyRunningTest);
38
console.log("Has focused tests:", currentState.hasFocusedTests);
39

40
// Modify state (advanced usage)
41
const state = getState();
42
const modifiedState = {
43
  ...state,
44
  testTimeout: 10000, // Set 10 second timeout
45
  maxConcurrency: 10  // Allow 10 concurrent tests
46
};
47
setState(modifiedState);
48

49
// Reset to initial state
50
resetState();
51
```
52

53
### Internal Event System
54

55
**Note:** The event dispatching functions (`dispatch`, `dispatchSync`, `addEventHandler`) are internal to jest-circus and not part of the public API. They are used internally by the framework and test environments. For custom event handling, see the [Event System](./event-system.md) documentation which covers how test environments can handle events via the `handleTestEvent` method.
56

57
## State Interface
58

59
```typescript { .api }
60
interface State {
61
  /** Currently executing describe block */
62
  currentDescribeBlock: DescribeBlock;
63
  /** Currently running test, null if none */
64
  currentlyRunningTest?: TestEntry | null;
65
  /** Root describe block containing all tests */
66
  rootDescribeBlock: DescribeBlock;
67
  /** Whether test execution has started */
68
  hasStarted: boolean;
69
  /** Whether any tests have .only modifier */
70
  hasFocusedTests: boolean;
71
  /** Whether to include test location in results */
72
  includeTestLocationInResult: boolean;
73
  /** Maximum number of concurrent tests */
74
  maxConcurrency: number;
75
  /** Parent process reference */
76
  parentProcess: NodeJS.Process | null;
77
  /** Random seed for test shuffling */
78
  seed: number;
79
  /** Pattern to match test names */
80
  testNamePattern?: RegExp | null;
81
  /** Default timeout for tests in milliseconds */
82
  testTimeout: number;
83
  /** Array of unhandled errors */
84
  unhandledErrors: Array<Exception>;
85
  /** Whether to expand snapshots */
86
  expand?: boolean;
87
  /** Whether to randomize test order */
88
  randomize?: boolean;
89
}
90

91
interface DescribeBlock {
92
  type: 'describeBlock';
93
  children: Array<DescribeBlock | TestEntry>;
94
  name: BlockName;
95
  parent?: DescribeBlock;
96
  mode: BlockMode;
97
  hooks: Array<Hook>;
98
}
99

100
interface TestEntry {
101
  type: 'test';
102
  asyncError: Exception;
103
  concurrent: boolean;
104
  errors: Array<Exception>;
105
  retryReasons: Array<Exception>;
106
  fn: TestFn;
107
  mode: TestMode;
108
  name: TestName;
109
  parent: DescribeBlock;
110
  seenDone: boolean;
111
  timeout?: number;
112
  failing: boolean;
113
  invocations: number;
114
  numPassingAsserts: number;
115
  startedAt?: number | null;
116
  duration?: number | null;
117
  status?: 'skip' | 'done' | 'todo' | null;
118
}
119

120
interface Hook {
121
  asyncError: Error;
122
  fn: HookFn;
123
  type: HookType;
124
  parent: DescribeBlock;
125
  seenDone: boolean;
126
  timeout: number | undefined | null;
127
}
128

129
type HookType = 'beforeAll' | 'afterAll' | 'beforeEach' | 'afterEach';
130
type Exception = any;
131
type BlockName = string;
132
type TestName = string;
133
```
134

135
## Implementation Notes
136

137
The state management system uses internal symbols and globals to maintain test state across the execution lifecycle. These internal mechanisms are not part of the public API and should not be accessed directly. Use the provided `getState()`, `setState()`, and `resetState()` functions to interact with the test state.