# FakeClock

Artifact: [androidx.media3:media3-test-utils](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/test/utils/FakeClock.java+class:androidx.media3.test.utils.FakeClock)

*** ** * ** ***


```
@UnstableApi
public class FakeClock implements Clock
```

<br />

*** ** * ** ***

Fake `https://developer.android.com/reference/androidx/media3/common/util/Clock` implementation that allows to `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#advanceTime(long)` manually to trigger pending timed messages.

All timed messages sent by a `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#createHandler(android.os.Looper,android.os.Handler.Callback)` created from this clock are governed by the clock's time. Messages sent through these handlers are not triggered until previous messages on any thread have been handled to ensure deterministic execution. Note that this includes messages sent from the main Robolectric test thread, meaning that these messages are only triggered if the main test thread is idle, which can be explicitly requested by calling `ShadowLooper.idleMainLooper()`.

The clock also sets the time of the `https://developer.android.com/reference/android/os/SystemClock.html` to match the `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#elapsedRealtime()`.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/media3/test/utils/FakeClock.Builder` A builder for `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock` instances. |
| `protected final inner class https://developer.android.com/reference/androidx/media3/test/utils/FakeClock.HandlerMessage implements https://developer.android.com/reference/java/lang/Comparable.html<https://developer.android.com/reference/androidx/media3/test/utils/FakeClock.HandlerMessage>, https://developer.android.com/reference/androidx/media3/common/util/HandlerWrapper.Message` Message data saved to send messages or execute runnables at a later time on a Handler. |

| ### Constants |
|---|---|
| `static final long` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#DEFAULT_MAX_AUTO_ADVANCING_TIME_DIFF_MS() = 1000` The default maximum time difference between two messages that the fake clock will automatically advance. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#FakeClock(long)(long initialTimeMs)` Creates a fake clock that doesn't auto-advance and assumes that the system was booted exactly at time `0` (the Unix Epoch) and `initialTimeMs` milliseconds have passed since system boot. |
| `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#FakeClock(boolean)(boolean isAutoAdvancing)` Creates a fake clock that assumes that the system was booted exactly at time `0` (the Unix Epoch) and an `initialTimeMs` of `0`. |
| `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#FakeClock(long,boolean)(long initialTimeMs, boolean isAutoAdvancing)` Creates a fake clock that assumes that the system was booted exactly at time `0` (the Unix Epoch) and `initialTimeMs` milliseconds have passed since system boot. |
| `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#FakeClock(long,long,boolean)(long bootTimeMs, long initialTimeMs, boolean isAutoAdvancing)` Creates a fake clock specifying when the system was booted and how much time has passed since then. |

| ### Public methods |
|---|---|
| `synchronized void` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#advanceTime(long)(long timeDiffMs)` Advance timestamp of `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock` by the specified duration. |
| `https://developer.android.com/reference/androidx/media3/common/util/HandlerWrapper` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#createHandler(android.os.Looper,android.os.Handler.Callback)( https://developer.android.com/reference/android/os/Looper.html looper, @https://checkerframework.org/api/org/checkerframework/checker/initialization/qual/UnknownInitialization.html @https://developer.android.com/reference/androidx/annotation/Nullable @https://checkerframework.org/api/org/checkerframework/checker/initialization/qual/UnknownInitialization.html https://developer.android.com/reference/android/os/Handler.Callback.html callback )` Creates a `https://developer.android.com/reference/androidx/media3/common/util/HandlerWrapper` using a specified looper and a specified callback for handling messages. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#currentTimeMillis()()` Returns the current time in milliseconds since the Unix Epoch. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#elapsedRealtime()()` |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#nanoTime()()` See `https://developer.android.com/reference/java/lang/System.html#nanoTime()` |
| `synchronized void` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#onThreadBlocked()()` Notifies the clock that the current thread is about to be blocked and won't return until a condition on another thread becomes true. |
| `long` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#uptimeMillis()()` |

| ### Protected methods |
|---|---|
| `synchronized void` | `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock#addPendingHandlerMessage(androidx.media3.test.utils.FakeClock.HandlerMessage)(https://developer.android.com/reference/androidx/media3/test/utils/FakeClock.HandlerMessage message)` Adds a message to the list of pending messages. |

### Inherited Constants

From [androidx.media3.common.util.Clock](https://developer.android.com/reference/androidx/media3/common/util/Clock) `static final https://developer.android.com/reference/androidx/media3/common/util/Clock` `https://developer.android.com/reference/androidx/media3/common/util/Clock#DEFAULT()`

Default `https://developer.android.com/reference/androidx/media3/common/util/Clock` to use for all non-test cases.

## Constants

### DEFAULT_MAX_AUTO_ADVANCING_TIME_DIFF_MS

```
public static final long DEFAULT_MAX_AUTO_ADVANCING_TIME_DIFF_MS = 1000
```

The default maximum time difference between two messages that the fake clock will automatically advance.

## Public constructors

### FakeClock

```
public FakeClock(long initialTimeMs)
```

Creates a fake clock that doesn't auto-advance and assumes that the system was booted exactly at time `0` (the Unix Epoch) and `initialTimeMs` milliseconds have passed since system boot.

| Parameters |
|---|---|
| `long initialTimeMs` | The initial elapsed time since the boot time, in milliseconds. |

### FakeClock

```
public FakeClock(boolean isAutoAdvancing)
```

Creates a fake clock that assumes that the system was booted exactly at time `0` (the Unix Epoch) and an `initialTimeMs` of `0`.

| Parameters |
|---|---|
| `boolean isAutoAdvancing` | Whether the clock should automatically advance the time to the time of next message that is due to be sent. |

### FakeClock

```
public FakeClock(long initialTimeMs, boolean isAutoAdvancing)
```

Creates a fake clock that assumes that the system was booted exactly at time `0` (the Unix Epoch) and `initialTimeMs` milliseconds have passed since system boot.

| Parameters |
|---|---|
| `long initialTimeMs` | The initial elapsed time since the boot time, in milliseconds. |
| `boolean isAutoAdvancing` | Whether the clock should automatically advance the time to the time of next message that is due to be sent. |

### FakeClock

```
public FakeClock(long bootTimeMs, long initialTimeMs, boolean isAutoAdvancing)
```

Creates a fake clock specifying when the system was booted and how much time has passed since then.

| Parameters |
|---|---|
| `long bootTimeMs` | The time the system was booted since the Unix Epoch, in milliseconds. |
| `long initialTimeMs` | The initial elapsed time since the boot time, in milliseconds. |
| `boolean isAutoAdvancing` | Whether the clock should automatically advance the time to the time of next message that is due to be sent. |

## Public methods

### advanceTime

```
synchronized public void advanceTime(long timeDiffMs)
```

Advance timestamp of `https://developer.android.com/reference/androidx/media3/test/utils/FakeClock` by the specified duration.

| Parameters |
|---|---|
| `long timeDiffMs` | The amount of time to add to the timestamp in milliseconds. |

### createHandler

```
public HandlerWrapper createHandler(
    Looper looper,
    @UnknownInitialization @Nullable @UnknownInitialization Handler.Callback callback
)
```

Creates a `https://developer.android.com/reference/androidx/media3/common/util/HandlerWrapper` using a specified looper and a specified callback for handling messages.

| See also |
|---|---|
| `https://developer.android.com/reference/android/os/Handler.html#Handler(android.os.Looper, android.os.Handler.Callback)` |   |

### currentTimeMillis

```
synchronized public long currentTimeMillis()
```

Returns the current time in milliseconds since the Unix Epoch.

| See also |
|---|---|
| `https://developer.android.com/reference/java/lang/System.html#currentTimeMillis()` |   |

### elapsedRealtime

```
synchronized public long elapsedRealtime()
```

| See also |
|---|---|
| `https://developer.android.com/reference/android/os/SystemClock.html#elapsedRealtime()` |   |

### nanoTime

```
synchronized public long nanoTime()
```

See `https://developer.android.com/reference/java/lang/System.html#nanoTime()`

### onThreadBlocked

```
synchronized public void onThreadBlocked()
```

Notifies the clock that the current thread is about to be blocked and won't return until a condition on another thread becomes true.

Should be a no-op for all non-test cases.

### uptimeMillis

```
public long uptimeMillis()
```

| See also |
|---|---|
| `https://developer.android.com/reference/android/os/SystemClock.html#uptimeMillis()` |   |

## Protected methods

### addPendingHandlerMessage

```
synchronized protected void addPendingHandlerMessage(FakeClock.HandlerMessage message)
```

Adds a message to the list of pending messages.