Overriding System Time for Testing in Java

1. Overview

In this quick tutorial, we’ll focus on different ways to override the system time for testing.

Sometimes there’s a logic around the current date in our code. Maybe some function calls such as new Date() or Calendar.getInstance(), which eventually are going to call System.CurrentTimeMillis.

For an introduction to the use of Java Clock, please refer to this article here. Or, to the use of AspectJ, here.

2. Using Clock in java.time

The java.time package in Java 8 includes an abstract class java.time.Clock with the purpose of allowing alternate clocks to be plugged in as and when required. With that, we can plug our own implementation or find one that is already made to satisfy our needs.

To accomplish our goals, the above library includes static methods to yield special implementations. We’re going to use two of them which returns an immutable, thread-safe and serializable implementation.

The first one is fixed. From it, we can obtain a Clock that always returns the same Instant, ensuring that the tests aren’t dependent on the current clock.

To use it, we need an Instant and a ZoneOffset:

Instant.now(Clock.fixed( 
  Instant.parse("2018-08-22T10:00:00Z"),
  ZoneOffset.UTC))

The second static method is offset. In this one, a clock wraps another clock that makes it the returned object capable of getting instants that are later or earlier by the specified duration.

In other words, it’s possible to simulate running in the future, in the past, or in any arbitrary point in time:

Clock constantClock = Clock.fixed(ofEpochMilli(0), ZoneId.systemDefault());

// go to the future:
Clock clock = Clock.offset(constantClock, Duration.ofSeconds(10));
        
// rewind back with a negative value:
clock = Clock.offset(constantClock, Duration.ofSeconds(-5));
 
// the 0 duration returns to the same clock:
clock = Clock.offset(constClock, Duration.ZERO);

With the Duration class, it’s possible to manipulate from nanoseconds to days. Also, we can negate a duration, which means to get a copy of this duration with the length negated.

3. Using Aspect-Oriented Programming

Another way to override the system time is by AOP. With this approach, we’re able to weave the System class to return a predefined value which we can set within our test cases.

Also, it’s possible to weave the application classes to redirect the call to System.currentTimeMillis() or to new Date() to another utility class of our own.

One way to implement this is through the use of AspectJ:

public aspect ChangeCallsToCurrentTimeInMillisMethod {
    long around(): 
      call(public static native long java.lang.System.currentTimeMillis()) 
        && within(user.code.base.pckg.*) {
          return 0;
      }
}

In the above example, we’re catching every call to System.currentTimeMillis() inside a specified package, which in this case is user.code.base.pckg.*, and returning zero every time that this event happens.

It’s in this place where we can declare our own implementation to obtain the desired time in milliseconds.

One advantage of using AspectJ is that it operates on bytecode level directly, so it doesn’t need the original source code to work.

For that reason, we wouldn’t need to recompile it.

4. Mocking the Instant.now() Method

We can use the Instant class to represent an instantaneous point on the timeline. Normally, we can use it to record event time-stamps in our application. The now() method of this class allows us to get the current instant from the system clock in the UTC timezone.

Let’s see some alternatives for changing its behavior when we test.

4.1. Overloading now() With a Clock

We can overload the now() method with a fixed Clock instance. Many of the classes in the java.time package have a now() method that takes a Clock parameter, which makes this our preferred approach:

@Test
public void givenFixedClock_whenNow_thenGetFixedInstant() {
    String instantExpected = "2014-12-22T10:15:30Z";
    Clock clock = Clock.fixed(Instant.parse(instantExpected), ZoneId.of("UTC"));

    Instant instant = Instant.now(clock);

    assertThat(instant.toString()).isEqualTo(instantExpected);
}

4.2. Using Mockito

In addition, if we need to modify the behavior of the now() method without sending parameters, we can use Mockito:

@Test
public void givenInstantMock_whenNow_thenGetFixedInstant() {
    String instantExpected = "2014-12-22T10:15:30Z";
    Clock clock = Clock.fixed(Instant.parse(instantExpected), ZoneId.of("UTC"));
    Instant instant = Instant.now(clock);

    try (MockedStatic<Instant> mockedStatic = mockStatic(Instant.class)) {
        mockedStatic.when(Instant::now).thenReturn(instant);
        Instant now = Instant.now();
        assertThat(now.toString()).isEqualTo(instantExpected);
    }
}

4.3. Using JMockit

Alternatively, we can use the JMockit library.

JMockit offers us two ways of mocking a static method. One is using the MockUp class:

@Test
public void givenInstantWithJMock_whenNow_thenGetFixedInstant() {
    String instantExpected = "2014-12-21T10:15:30Z";
    Clock clock = Clock.fixed(Instant.parse(instantExpected), ZoneId.of("UTC"));
    new MockUp<Instant>() {
        @Mock
        public Instant now() {
            return Instant.now(clock);
        }
    };

    Instant now = Instant.now();

    assertThat(now.toString()).isEqualTo(instantExpected);
}

And the another is using the Expectations class:

@Test
public void givenInstantWithExpectations_whenNow_thenGetFixedInstant() {
    Clock clock = Clock.fixed(Instant.parse("2014-12-23T10:15:30.00Z"), ZoneId.of("UTC"));
    Instant instantExpected = Instant.now(clock);
    new Expectations(Instant.class) {
        {
            Instant.now();
            result = instantExpected;
        }
    };

    Instant now = Instant.now();

    assertThat(now).isEqualTo(instantExpected);
}

5. Mocking the LocalDateTime.now() Method

Another useful class in the java.time package is the LocalDateTime class. This class represents a date-time without a timezone in the ISO-8601 calendar system. The now() method of this class allows us to get the current date-time from the system clock in the default timezone.

We can use the same alternatives to mock it as we saw before. For example, overloading now() with a fixed Clock:

@Test
public void givenFixedClock_whenNow_thenGetFixedLocalDateTime() {
    Clock clock = Clock.fixed(Instant.parse("2014-12-22T10:15:30.00Z"), ZoneId.of("UTC"));
    String dateTimeExpected = "2014-12-22T10:15:30";

    LocalDateTime dateTime = LocalDateTime.now(clock);

    assertThat(dateTime).isEqualTo(dateTimeExpected);
}

6. Conclusion

In this article, we’ve explored different ways to override the system time for testing. First, we looked at the native package java.time and its Clock class. Next, we saw how to apply an aspect to weave the System class. Finally, we saw different alternatives to mocking the now() method on Instant and LocalDateTime classes.