faketime lets you run a job command as though its process sees a chosen date and time, so you can test time-dependent logic without waiting for that date to arrive. It does not, by itself, move a cron daemon or prove that a scheduler will trigger a job at the right wall-clock time: it changes the time view of the command you wrap, not the host clock for every service.
What faketime changes when you run a job
The faketime command is a wrapper around libfaketime. The library uses linker-preload interposition to intercept selected time-related calls made by a target process. Its project README describes the approach as intercepting calls programs use to retrieve the current date and time: libfaketime project README.
As an Amazon Associate I earn from qualifying purchases.
With a fixed starting timestamp, the wrapped command sees that time and, by default, its wall clock continues advancing from it. The manual also describes relative offsets and options for changing the apparent clock rate. Those are different test conditions: a fixed starting time is not the same as simulating time passing faster or slower. See the faketime manual for the supported timestamp formats and options.
Recommended Free Tools
The distinction matters for scheduled jobs. Wrapping a job executable tests what that process does when it sees a chosen time. It does not establish that cron, a queue service, a database, or another system has the same clock, nor that its trigger mechanism will behave as though real wall-clock time had advanced. That follows from libfaketime’s documented process-level scope; it is not a guarantee about any particular scheduler.
Test job logic without waiting for real time
Use faketime to exercise branches that depend on the time observed by the job itself—for example, a due-date check, an expiration path, a daily aggregation, or a time-window condition. These are examples of test scenarios, not behavior guaranteed by faketime. The useful result is an observable outcome from the job, such as a changed record or generated output, not merely a date printed by a diagnostic command.
- Choose the behavior and expected outcome. Identify the time-dependent branch, the date or offset that should reach it, and what the job should do if the branch runs.
- Run the job command directly under faketime. Use the wrapper’s documented syntax to supply an explicit starting timestamp or relative offset. Check the manual for the exact format supported by the installed version.
- Check the job’s actual effect. Assert the expected output or state change. Confirming that a process reports a fake date is useful as a diagnostic, but does not show that the intended job logic ran correctly.
- Repeat for relevant time boundaries. Test the cases your logic distinguishes, such as just before and just after a deadline, rather than relying on one arbitrary future date.
- Test the scheduler separately if its trigger is the requirement. Use documentation and tests for the specific scheduler and deployment environment to establish whether it fires at the intended real wall-clock time.
This approach separates two questions: “Does the job behave correctly when it sees this date?” and “Does the scheduler launch it at the right time?” Faketime addresses the first question only when the target process honors its interposition; it does not provide a generic way to time-travel a scheduler daemon.
Choose the time behavior that matches the test
- Fixed starting timestamp: Useful for testing logic at a specific date and time. The wrapped process’s wall clock normally proceeds from that starting point.
- Relative offset: Useful when the test should shift the process’s time relative to the actual clock. Follow the manual’s syntax for the offset you need.
- Accelerated or slowed clock: Can help test behavior that depends on elapsed time, but the manual warns that rate adjustments may not behave as expected in child processes.
- Monotonic time: Do not assume every clock API is altered identically. The manual documents an option to exclude
CLOCK_MONOTONIC, and the project README discusses monotonic-clock issues. Check which clock your runtime and job use.
Check compatibility before trusting a passing test
Faketime relies on preload interposition, so its effect depends on the operating system, binary linkage, runtime, and the clock path used by the application. The project describes Linux and macOS as intended platforms, with behavior on other Unix-like systems potentially varying. Its documentation also identifies cases where the approach may not take effect.
- Static or setuid binaries: The upstream manual and README say preload interposition does not work for statically linked binaries or setuid programs.
- Alternate time paths: A program may bypass the intercepted calls by using vDSO, direct system calls, dynamically loaded system libraries, or a runtime-specific clock path. A successful test of one command does not establish compatibility for every program in its process.
- Java: The project warns that JVM applications may need an additional monotonic-clock setting and that otherwise Java may hang. Check current project instructions for the specific Java version and setup.
- Child processes: Verify the environment and observed time of subprocesses independently. The manual says a child can start a new libfaketime instance and reinitialize its start time, so acceleration or slowdown may differ from the parent process.
For Python tests that launch subprocesses, the Python faketime package documentation discusses preparing preload environment variables for child processes. It also reports a possible uuid1 deadlock in a fake-time context when an OS-level UUID library is available and describes a package-specific workaround. Treat that warning as guidance for that package and situation, not as a universal property of libfaketime.
Before relying on a test, verify the exact command, runtime, operating system, and subprocess tree you intend to run. A basic test that sees the chosen date is not proof that every time API used by the job—or any separately running service—shares that clock.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep scheduler and job tests separate
If the question is whether a job’s date-dependent code works, run the job command under faketime and verify its effects. If the question is whether a scheduler fires on time, test the scheduler’s trigger behavior using that scheduler’s own documentation and a representative environment. If the job also consults external services, verify those services’ clocks and time assumptions separately; wrapping one process does not establish that they observe the same date.
Quick Recap
Best Value
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
