Mocking and Stubbing in Java: Real Examples with JMockitUnit tests are the foundation of reliable software. When testing Java code, isolating the class under test from its dependencies is essential so tests run fast, deterministically, and focus on a single behavior. Two common techniques for isolation are mocking and stubbing. This article explains those concepts and shows real-world examples using JMockit, a powerful Java testing toolkit that provides mocking, stubbing, faking, and verification for unit and integration tests.
What are mocking and stubbing?
- Mocking: creating a test double that records interactions (calls, arguments) so you can verify how the system under test used its dependencies.
- Stubbing: providing canned responses (return values or thrown exceptions) from dependencies so the system under test receives predictable inputs.
Both techniques let you avoid creating real external resources (databases, web services, file systems) and let you focus on the behavior of the class under test.
Why JMockit?
JMockit is different from many other mocking libraries (e.g., Mockito) because it uses instrumentation to allow:
- Mocking of final classes and methods, static methods, constructors, private methods, and even code without interfaces.
- Inlined expectations and verifications with concise annotations and APIs.
- Tight control over behavior and lifecycle of test doubles.
Use JMockit when you need to test legacy code or code with hard-to-mock constructs. Note: JMockit requires the Java agent (it uses bytecode instrumentation), and setup differs slightly depending on your build/test runner.
Setup
Add JMockit as a test dependency (Maven example):
<dependency> <groupId>org.jmockit</groupId> <artifactId>jmockit</artifactId> <version>1.49</version> <!-- replace with latest compatible version --> <scope>test</scope> </dependency> For JUnit 5, use the JMockit JUnit 5 integration or run tests with the JMockit Java agent. For JUnit 4, the @RunWith(JMockit.class) runner was common.
Basic concepts and annotations
- @Mocked — creates a mock instance for a type; all instances of that type become mocked within the test scope.
- @Injectable — creates a mock instance used only for a single injectable instance (useful for dependency injection-like scenarios).
- @Capturing — mocks all implementations of a type (used for interfaces or base classes).
- Expectations — specify behavior (stubbing) and optionally record expected interactions.
- Verifications — assert that interactions happened as expected.
- Deencapsulation / Reflection utilities — call private methods or access private fields when necessary.
Example 1 — Simple stubbing and verification
Imagine a NotificationService that sends messages via an external SmsClient. We want to test NotificationService without actually sending SMS.
Code under test (simplified):
public class SmsClient { public void send(String phone, String message) { /* calls external API */ } } public class NotificationService { private final SmsClient smsClient; public NotificationService(SmsClient smsClient) { this.smsClient = smsClient; } public boolean notifyUser(String phone, String message) { if (phone == null || phone.isEmpty()) return false; smsClient.send(phone, message); return true; } } Test with JMockit:
import mockit.Expectations; import mockit.Mocked; import mockit.Verifications; import org.junit.Test; public class NotificationServiceTest { @Mocked SmsClient smsClient; // all SmsClient instances are mocked @Test public void notifyUser_sendsSms_whenPhoneValid() { NotificationService service = new NotificationService(new SmsClient()); new Expectations() {{ // we can optionally stub behavior, but void method needs no return smsClient.send(anyString, anyString); }}; boolean result = service.notifyUser("+1234567890", "Hello"); assertTrue(result); new Verifications() {{ smsClient.send("+1234567890", "Hello"); times = 1; }}; } @Test public void notifyUser_returnsFalse_whenPhoneInvalid() { NotificationService service = new NotificationService(new SmsClient()); boolean result = service.notifyUser("", "Hi"); assertFalse(result); new Verifications() {{ smsClient.send((String) any, (String) any); times = 0; }}; } } Notes:
- @Mocked replaces behavior for all SmsClient instances in the test scope.
- The Expectations block can be used to define return values or to specify that a call is expected when you need strict ordering or to stub behavior.
Example 2 — Stubbing returns and throwing exceptions
Suppose a DataRepository fetches data and can throw an exception when the data source is unreachable.
Class under test:
public class DataRepository { public String fetchData(String key) { /* calls DB or remote service */ } } public class DataService { private final DataRepository repo; public DataService(DataRepository repo) { this.repo = repo; } public String getUppercaseData(String key) { String data = repo.fetchData(key); return data == null ? null : data.toUpperCase(); } } Test:
import mockit.Expectations; import mockit.Mocked; import org.junit.Test; import static org.junit.Assert.*; public class DataServiceTest { @Mocked DataRepository repo; @Test public void returnsUppercase_whenRepoReturnsValue() { new Expectations() {{ repo.fetchData("k1"); result = "hello"; }}; DataService svc = new DataService(new DataRepository()); assertEquals("HELLO", svc.getUppercaseData("k1")); } @Test(expected = RuntimeException.class) public void throws_whenRepoThrows() { new Expectations() {{ repo.fetchData("bad"); result = new RuntimeException("DB down"); }}; new DataService(new DataRepository()).getUppercaseData("bad"); } } Key points:
- Use result = value to stub return values, or result = new Exception(…) to simulate errors.
Example 3 — Mocking static methods and constructors
Many libraries have static helpers or APIs with static methods. JMockit can mock those directly.
Example: Utility class with static method and a class that instantiates a helper.
public final class TimeUtils { public static long currentTimeMillis() { return System.currentTimeMillis(); } } public class ReportGenerator { public Report generate() { long t = TimeUtils.currentTimeMillis(); return new Report(t); } } Test:
import mockit.Expectations; import mockit.Mocked; import org.junit.Test; import static org.junit.Assert.*; public class ReportGeneratorTest { @Mocked TimeUtils timeUtils; // mocks static methods @Test public void generate_usesMockedTime() { new Expectations() {{ TimeUtils.currentTimeMillis(); result = 1000L; }}; Report r = new ReportGenerator().generate(); assertEquals(1000L, r.getTimestamp()); } } Mocking constructors:
public class ExternalClient { public ExternalClient(String config) { /* setup */ } public String call() { return "ok"; } } public class ClientUser { public String useClient() { ExternalClient client = new ExternalClient("cfg"); return client.call(); } } Test:
import mockit.Expectations; import mockit.Mocked; import org.junit.Test; import static org.junit.Assert.*; public class ClientUserTest { @Mocked ExternalClient anyClient; @Test public void useClient_withMockedConstructor() { new Expectations() {{ new ExternalClient((String) any); anyClient.call(); result = "mocked"; }}; assertEquals("mocked", new ClientUser().useClient()); } } Example 4 — @Injectable vs @Mocked vs @Capturing
- @Mocked: all instances of a type inside test are mocked.
- @Injectable: only that single instance is mocked; other instances are real.
- @Capturing: captures and mocks every implementation/subclass of a base type.
Use case: you want to mock one dependency passed via constructor (injectable), but leave other instances of same class untouched.
public class AService { private final Helper helper; public AService(Helper helper) { this.helper = helper; } public String doSomething() { return helper.help(); } } public class Helper { public String help() { return "real"; } } Test:
import mockit.Injectable; import mockit.Expectations; import org.junit.Test; import static org.junit.Assert.*; public class AServiceTest { @Injectable Helper injectedHelper; @Test public void usesInjectedHelper() { new Expectations() {{ injectedHelper.help(); result = "fake"; }}; AService s = new AService(injectedHelper); assertEquals("fake", s.doSomething()); } } Example 5 — Verifying order and number of calls
When behavior depends on the sequence of interactions, JMockit supports strict/ordered expectations.
new Expectations() {{ dependency.first(); times = 1; dependency.second(); times = 1; }}; Or use VerificationsInOrder for post-fact verification:
new VerificationsInOrder() {{ dependency.first(); dependency.second(); }}; Tips and best practices
- Prefer @Injectable for clearer, less intrusive tests when possible.
- Use @Mocked for broad-scope mocking (legacy code) but be careful: it affects all instances.
- Keep tests focused: stub only what is needed and verify only what matters for behavior.
- Avoid over-mocking internal implementation; test observable behavior.
- For static-heavy legacy code, prefer JMockit or refactor to make code more testable.
- When mocking constructors, ensure you do not accidentally hide important side effects needed by the test context.
Troubleshooting
- If JMockit mocks don’t apply, ensure the Java agent is active or you’re using the correct runner/extension for your JUnit version.
- Mocking final or static members requires proper JMockit setup — check your build/test runner documentation.
- Interaction-based testing can lead to brittle tests; prefer state verification when practical.
Conclusion
Mocking and stubbing are essential for fast, focused unit tests. JMockit offers powerful features to mock static methods, final classes, constructors, and private methods, making it especially useful for testing legacy Java code. Used correctly, JMockit lets you write expressive, precise tests that isolate the unit under test and assert its behavior with confidence.
Leave a Reply