setmocktime

Setmocktime is a testing utility used in Bitcoin Core to override the node’s notion of time during tests. It provides a deterministic way to simulate time-dependent behavior in unit and functional tests by letting the test framework set a mock, or fake, current time.

In the codebase, time sources are centralized. When mock time is enabled, time-related functions return the mock value instead of the real system time. The SetMockTime function sets the internal mock time, and components such as GetAdjustedTime can return this value. This allows tests to exercise features that depend on timestamps or time intervals—such as locktimes, coinbase maturity, block timing, and mempool expiry—without having to wait in real time.

Usage typically occurs in test or regtest environments. The mock time can be advanced by the test harness or via an RPC call named setmocktime, which accepts a UNIX timestamp. Some testing configurations also support a -mocktime command-line option to initialize the mock time. These mechanisms do not affect the actual wall clock; they only influence the node’s internal clock for testing purposes.

Limitations and scope: setmocktime is intended for development and testing, not production use. It is primarily valuable for deterministic testing of time-dependent logic. On production networks, mock time features are generally disabled or ignored to preserve real-world timing and consensus rules.