|
| 1 | +//! Clock abstraction for testable time management |
| 2 | +//! |
| 3 | +//! This module provides a clock abstraction that allows controlling time |
| 4 | +//! in tests. Time is treated as an infrastructure concern, similar to |
| 5 | +//! database or filesystem access. |
| 6 | +//! |
| 7 | +//! # Design Philosophy |
| 8 | +//! |
| 9 | +//! Direct use of `Utc::now()` throughout the codebase makes tests |
| 10 | +//! non-deterministic and harder to maintain. By abstracting time behind |
| 11 | +//! a trait, we can: |
| 12 | +//! |
| 13 | +//! - Control time in tests (set specific timestamps) |
| 14 | +//! - Make tests deterministic and reproducible |
| 15 | +//! - Test time-dependent behavior (timeouts, retries, etc.) |
| 16 | +//! - Mock time progression without actual delays |
| 17 | +//! |
| 18 | +//! # Usage |
| 19 | +//! |
| 20 | +//! ## In Production Code |
| 21 | +//! |
| 22 | +//! ```rust |
| 23 | +//! use torrust_deployer_types::Clock; |
| 24 | +//! |
| 25 | +//! fn record_event(clock: &dyn Clock) { |
| 26 | +//! let timestamp = clock.now(); |
| 27 | +//! println!("Event occurred at: {}", timestamp); |
| 28 | +//! } |
| 29 | +//! ``` |
| 30 | +//! |
| 31 | +//! ## In Tests |
| 32 | +//! |
| 33 | +//! ```rust,no_run |
| 34 | +//! // Note: MockClock is only available in the root crate's testing module |
| 35 | +//! # #[cfg(test)] |
| 36 | +//! # { |
| 37 | +//! use torrust_tracker_deployer_lib::testing::MockClock; |
| 38 | +//! use chrono::{DateTime, TimeZone, Utc}; |
| 39 | +//! |
| 40 | +//! let fixed_time = Utc.with_ymd_and_hms(2025, 10, 7, 12, 0, 0).unwrap(); |
| 41 | +//! let clock = MockClock::new(fixed_time); |
| 42 | +//! |
| 43 | +//! // Time is now fixed at the specified timestamp |
| 44 | +//! assert_eq!(clock.now(), fixed_time); |
| 45 | +//! |
| 46 | +//! // Advance time by 5 seconds |
| 47 | +//! clock.advance_secs(5); |
| 48 | +//! assert_eq!( |
| 49 | +//! clock.now(), |
| 50 | +//! Utc.with_ymd_and_hms(2025, 10, 7, 12, 0, 5).unwrap() |
| 51 | +//! ); |
| 52 | +//! # } |
| 53 | +//! ``` |
| 54 | +
|
| 55 | +use chrono::{DateTime, Utc}; |
| 56 | + |
| 57 | +/// Clock trait for obtaining the current time |
| 58 | +/// |
| 59 | +/// This trait abstracts time acquisition, making it mockable in tests. |
| 60 | +/// All time-dependent code should use this trait instead of calling |
| 61 | +/// `Utc::now()` directly. |
| 62 | +pub trait Clock: Send + Sync { |
| 63 | + /// Returns the current time in UTC |
| 64 | + fn now(&self) -> DateTime<Utc>; |
| 65 | +} |
| 66 | + |
| 67 | +/// System clock implementation using real system time |
| 68 | +/// |
| 69 | +/// This is the production implementation that uses `Utc::now()` |
| 70 | +/// to get the actual current time. |
| 71 | +/// |
| 72 | +/// # Example |
| 73 | +/// |
| 74 | +/// ```rust |
| 75 | +/// use torrust_deployer_types::{Clock, SystemClock}; |
| 76 | +/// |
| 77 | +/// let clock = SystemClock; |
| 78 | +/// let now = clock.now(); |
| 79 | +/// println!("Current time: {}", now); |
| 80 | +/// ``` |
| 81 | +#[derive(Debug, Clone, Copy, Default)] |
| 82 | +pub struct SystemClock; |
| 83 | + |
| 84 | +impl Clock for SystemClock { |
| 85 | + fn now(&self) -> DateTime<Utc> { |
| 86 | + Utc::now() |
| 87 | + } |
| 88 | +} |
| 89 | + |
| 90 | +#[cfg(test)] |
| 91 | +mod tests { |
| 92 | + use super::*; |
| 93 | + |
| 94 | + #[test] |
| 95 | + fn it_should_return_current_system_time() { |
| 96 | + let clock = SystemClock; |
| 97 | + let before = Utc::now(); |
| 98 | + let now = clock.now(); |
| 99 | + let after = Utc::now(); |
| 100 | + |
| 101 | + // Verify the returned time is between before and after |
| 102 | + assert!(now >= before); |
| 103 | + assert!(now <= after); |
| 104 | + } |
| 105 | + |
| 106 | + #[test] |
| 107 | + fn it_should_return_different_times_on_subsequent_calls() { |
| 108 | + let clock = SystemClock; |
| 109 | + let first = clock.now(); |
| 110 | + |
| 111 | + // Small delay to ensure different timestamp |
| 112 | + std::thread::sleep(std::time::Duration::from_millis(10)); |
| 113 | + |
| 114 | + let second = clock.now(); |
| 115 | + assert!(second > first); |
| 116 | + } |
| 117 | +} |
0 commit comments