0
# Reflection and Internal State Access
1

2
PowerMock's Whitebox utility provides comprehensive reflection capabilities for testing internal object state and behavior. These utilities enable access to private fields, methods, and constructors without modifying production code.
3

4
## Capabilities
5

6
### Field Access and Manipulation
7

8
Get and set field values regardless of visibility modifiers.
9

10
```java { .api }
11
/**
12
 * Get the value of a field (including private fields)
13
 * @param object the object containing the field
14
 * @param fieldName the name of the field
15
 * @return the field value
16
 */
17
public static <T> T getInternalState(Object object, String fieldName);
18

19
/**
20
 * Get the value of a field by type
21
 * @param object the object containing the field
22
 * @param fieldType the type of the field
23
 * @return the field value
24
 */
25
public static <T> T getInternalState(Object object, Class<T> fieldType);
26

27
/**
28
 * Get the value of a field from a specific class in the hierarchy
29
 * @param object the object containing the field
30
 * @param fieldName the name of the field
31
 * @param where the class that declares the field
32
 * @return the field value
33
 */
34
public static <T> T getInternalState(Object object, String fieldName, Class<?> where);
35

36
/**
37
 * Get the value of a field by type from a specific class in the hierarchy
38
 * @param object the object containing the field
39
 * @param fieldType the type of the field
40
 * @param where the class that declares the field
41
 * @return the field value
42
 */
43
public static <T> T getInternalState(Object object, Class<T> fieldType, Class<?> where);
44

45
/**
46
 * Set the value of a field (including private fields)
47
 * @param object the object containing the field
48
 * @param fieldName the name of the field
49
 * @param value the value to set
50
 */
51
public static void setInternalState(Object object, String fieldName, Object value);
52

53
/**
54
 * Set the value of multiple fields at once
55
 * @param object the object containing the fields
56
 * @param value the first value to set
57
 * @param additionalValues additional values to set
58
 */
59
public static void setInternalState(Object object, Object value, Object... additionalValues);
60

61
/**
62
 * Set the value of a field by type
63
 * @param object the object containing the field
64
 * @param fieldType the type of the field
65
 * @param value the value to set
66
 */
67
public static void setInternalState(Object object, Class<?> fieldType, Object value);
68

69
/**
70
 * Set the value of a field in a specific class in the hierarchy
71
 * @param object the object containing the field
72
 * @param fieldName the name of the field
73
 * @param value the value to set
74
 * @param where the class that declares the field
75
 */
76
public static void setInternalState(Object object, String fieldName, Object value, Class<?> where);
77

78
/**
79
 * Set the value of a field by type in a specific class in the hierarchy
80
 * @param object the object containing the field
81
 * @param fieldType the type of the field
82
 * @param value the value to set
83
 * @param where the class that declares the field
84
 */
85
public static void setInternalState(Object object, Class<?> fieldType, Object value, Class<?> where);
86
```
87

88
### Method Invocation
89

90
Invoke methods including private methods with support for parameter type resolution.
91

92
```java { .api }
93
/**
94
 * Invoke a method with automatic method resolution
95
 * @param instance the object instance
96
 * @param arguments the method arguments
97
 * @return the method return value
98
 */
99
public static synchronized <T> T invokeMethod(Object instance, Object... arguments) throws Exception;
100

101
/**
102
 * Invoke a method by name
103
 * @param instance the object instance
104
 * @param methodToExecute the method name
105
 * @param arguments the method arguments
106
 * @return the method return value
107
 */
108
public static synchronized <T> T invokeMethod(Object instance, String methodToExecute, Object... arguments) throws Exception;
109

110
/**
111
 * Invoke a method with explicit parameter types
112
 * @param instance the object instance
113
 * @param methodToExecute the method name
114
 * @param argumentTypes the parameter types
115
 * @param arguments the method arguments
116
 * @return the method return value
117
 */
118
public static synchronized <T> T invokeMethod(Object instance, String methodToExecute, Class<?>[] argumentTypes, Object... arguments) throws Exception;
119

120
/**
121
 * Invoke a method in a specific declaring class
122
 * @param instance the object instance
123
 * @param declaringClass the class that declares the method
124
 * @param methodToExecute the method name
125
 * @param arguments the method arguments
126
 * @return the method return value
127
 */
128
public static synchronized <T> T invokeMethod(Object instance, Class<?> declaringClass, String methodToExecute, Object... arguments) throws Exception;
129

130
/**
131
 * Invoke a method with full parameter specification
132
 * @param object the object instance
133
 * @param declaringClass the class that declares the method
134
 * @param methodToExecute the method name
135
 * @param parameterTypes the parameter types
136
 * @param arguments the method arguments
137
 * @return the method return value
138
 */
139
public static synchronized <T> T invokeMethod(Object object, Class<?> declaringClass, String methodToExecute, Class<?>[] parameterTypes, Object... arguments) throws Exception;
140

141
/**
142
 * Invoke a static method with automatic method resolution
143
 * @param klass the class containing the static method
144
 * @param arguments the method arguments
145
 * @return the method return value
146
 */
147
public static synchronized <T> T invokeMethod(Class<?> klass, Object... arguments) throws Exception;
148

149
/**
150
 * Invoke a static method by name
151
 * @param clazz the class containing the static method
152
 * @param methodToExecute the method name
153
 * @param arguments the method arguments
154
 * @return the method return value
155
 */
156
public static synchronized <T> T invokeMethod(Class<?> clazz, String methodToExecute, Object... arguments) throws Exception;
157
```
158

159
### Constructor Invocation
160

161
Create objects using private or complex constructors.
162

163
```java { .api }
164
/**
165
 * Create an instance using constructor arguments
166
 * @param classThatContainsTheConstructorToTest the class to instantiate
167
 * @param arguments the constructor arguments
168
 * @return the new instance
169
 */
170
public static <T> T invokeConstructor(Class<T> classThatContainsTheConstructorToTest, Object... arguments) throws Exception;
171

172
/**
173
 * Create an instance with explicit parameter types
174
 * @param classThatContainsTheConstructorToTest the class to instantiate
175
 * @param parameterTypes the constructor parameter types
176
 * @param arguments the constructor arguments
177
 * @return the new instance
178
 */
179
public static <T> T invokeConstructor(Class<T> classThatContainsTheConstructorToTest, Class<?>[] parameterTypes, Object[] arguments) throws Exception;
180

181
/**
182
 * Create an instance using the default constructor
183
 * @param classToInstantiate the class to instantiate
184
 * @return the new instance
185
 */
186
public static <T> T newInstance(Class<T> classToInstantiate);
187
```
188

189
### Field and Method Discovery
190

191
Access reflection metadata for fields, methods, and constructors.
192

193
```java { .api }
194
/**
195
 * Get a field by name
196
 * @param type the class containing the field
197
 * @param fieldName the field name
198
 * @return the Field object
199
 */
200
public static Field getField(Class<?> type, String fieldName);
201

202
/**
203
 * Get multiple fields by name
204
 * @param clazz the class containing the fields
205
 * @param fieldNames the field names
206
 * @return array of Field objects
207
 */
208
public static Field[] getFields(Class<?> clazz, String... fieldNames);
209

210
/**
211
 * Get all instance fields
212
 * @param object the object
213
 * @return set of all instance fields
214
 */
215
public static Set<Field> getAllInstanceFields(Object object);
216

217
/**
218
 * Get all static fields
219
 * @param type the class
220
 * @return set of all static fields
221
 */
222
public static Set<Field> getAllStaticFields(Class<?> type);
223

224
/**
225
 * Get fields of a specific type
226
 * @param object the object
227
 * @param type the field type
228
 * @return set of fields of the specified type
229
 */
230
public static Set<Field> getFieldsOfType(Object object, Class<?> type);
231

232
/**
233
 * Get fields annotated with specific annotations
234
 * @param object the object
235
 * @param annotation the annotation type
236
 * @param additionalAnnotations additional annotation types
237
 * @return set of annotated fields
238
 */
239
public static Set<Field> getFieldsAnnotatedWith(Object object, Class<? extends Annotation> annotation, Class<? extends Annotation>... additionalAnnotations);
240

241
/**
242
 * Get a method by name and parameter types
243
 * @param type the class containing the method
244
 * @param methodName the method name
245
 * @param parameterTypes the parameter types
246
 * @return the Method object
247
 */
248
public static Method getMethod(Class<?> type, String methodName, Class<?>... parameterTypes);
249

250
/**
251
 * Get a method by parameter types only
252
 * @param type the class containing the method
253
 * @param parameterTypes the parameter types
254
 * @return the Method object
255
 */
256
public static Method getMethod(Class<?> type, Class<?>... parameterTypes);
257

258
/**
259
 * Get multiple methods by name
260
 * @param clazz the class containing the methods  
261
 * @param methodNames the method names
262
 * @return array of Method objects
263
 */
264
public static Method[] getMethods(Class<?> clazz, String... methodNames);
265

266
/**
267
 * Get a constructor by parameter types
268
 * @param type the class containing the constructor
269
 * @param parameterTypes the parameter types
270
 * @return the Constructor object
271
 */
272
public static <T> Constructor<T> getConstructor(Class<?> type, Class<?>... parameterTypes);
273

274
/**
275
 * Get the first parent constructor
276
 * @param klass the class
277
 * @return the first parent constructor
278
 */
279
public static Constructor<?> getFirstParentConstructor(Class<?> klass);
280
```
281

282
### Context-Based Field Setting
283

284
Set multiple fields using context objects for dependency injection scenarios.
285

286
```java { .api }
287
/**
288
 * Set internal state from context objects
289
 * @param instance the target object
290
 * @param context the context object providing values
291
 * @param additionalContexts additional context objects
292
 */
293
public static void setInternalStateFromContext(Object instance, Object context, Object... additionalContexts);
294

295
/**
296
 * Set internal state from context classes
297
 * @param classOrInstance the target object or class
298
 * @param context the context class providing values
299
 * @param additionalContexts additional context classes
300
 */
301
public static void setInternalStateFromContext(Object classOrInstance, Class<?> context, Class<?>... additionalContexts);
302

303
/**
304
 * Set internal state from context with matching strategy
305
 * @param instance the target object
306
 * @param context the context object providing values
307
 * @param strategy the field matching strategy
308
 */
309
public static void setInternalStateFromContext(Object instance, Object context, FieldMatchingStrategy strategy);
310

311
/**
312
 * Set internal state from context class with matching strategy
313
 * @param instance the target object
314
 * @param context the context class providing values
315
 * @param strategy the field matching strategy
316
 */
317
public static void setInternalStateFromContext(Object instance, Class<?> context, FieldMatchingStrategy strategy);
318
```
319

320
### Type Utilities
321

322
Access type information and work with inner classes.
323

324
```java { .api }
325
/**
326
 * Get the type of an object
327
 * @param object the object
328
 * @return the object's type
329
 */
330
public static Class<?> getType(Object object);
331

332
/**
333
 * Get the unproxied type of an object
334
 * @param object the object (potentially proxied)
335
 * @return the original type
336
 */
337
public static Class<?> getUnproxyType(Object object);
338

339
/**
340
 * Get an inner class type by name
341
 * @param declaringClass the declaring class
342
 * @param name the inner class name
343
 * @return the inner class type
344
 */
345
public static Class<Object> getInnerClassType(Class<?> declaringClass, String name) throws ClassNotFoundException;
346

347
/**
348
 * Get a local class type by occurrence and name
349
 * @param declaringClass the declaring class
350
 * @param occurrence the occurrence number
351
 * @param name the local class name
352
 * @return the local class type
353
 */
354
public static Class<Object> getLocalClassType(Class<?> declaringClass, int occurrence, String name) throws ClassNotFoundException;
355

356
/**
357
 * Get an anonymous inner class type by occurrence
358
 * @param declaringClass the declaring class
359
 * @param occurrence the occurrence number
360
 * @return the anonymous class type
361
 */
362
public static Class<Object> getAnonymousInnerClassType(Class<?> declaringClass, int occurrence) throws ClassNotFoundException;
363
```
364

365
## Usage Examples
366

367
### Basic Field Access
368

369
```java
370
// Get private field value
371
String value = Whitebox.getInternalState(myObject, "privateField");
372

373
// Set private field value
374
Whitebox.setInternalState(myObject, "privateField", "newValue");
375

376
// Set field by type
377
Whitebox.setInternalState(myObject, DatabaseConnection.class, mockConnection);
378
```
379

380
### Private Method Invocation
381

382
```java
383
// Invoke private method
384
String result = Whitebox.invokeMethod(myObject, "privateMethod", "param1", 123);
385

386
// Invoke private static method
387
int result = Whitebox.invokeMethod(MyClass.class, "privateStaticMethod", "param");
388
```
389

390
### Constructor Testing
391

392
```java
393
// Create instance with private constructor
394
MyClass instance = Whitebox.invokeConstructor(MyClass.class, "param1", 123);
395

396
// Create instance using default constructor
397
MyClass instance = Whitebox.newInstance(MyClass.class);
398
```
399

400
### Context-Based Field Setting
401

402
```java
403
// Set fields from context object (dependency injection testing)
404
TestContext context = new TestContext();
405
context.database = mockDatabase;
406
context.logger = mockLogger;
407

408
Whitebox.setInternalStateFromContext(serviceUnderTest, context);
409
```
410

411
## Types
412

413
```java { .api }
414
/**
415
 * Strategy for matching fields when setting internal state from context
416
 */
417
interface FieldMatchingStrategy {
418
    // Strategy implementations for field matching
419
}
420
```