chore: make Clock static. (#8)

Author: dmytro-khmara

README.md

@@ -1,22 +1,70 @@
 # Timecop - Easy Date and Time Testing in C\#
 
-Timecop is a small library that helps you test DateTime in a static, thread-safe, ambient context.
+Timecop is a small library that helps to test the code that depends on DateTime by allowing you to freeze and travel in time.
 
 Timecop targets .NET Standard 2.0, has no external dependencies, and can be used with .NET Framework 4.5+ and any version of .NET and .NET Core.
 
 Timecop has been inspired by the [timecop](https://github.com/travisjeffery/timecop) Ruby gem.
 
 ## Installation
 
-You can install [Timecop](https://www.nuget.org/packages/Timecop/) from NuGet using the .NET CLI:
+You can install [Timecop](https://www.nuget.org/packages/Timecop/) from NuGet using your IDE or the .NET CLI:
 
 ```
 dotnet add package Timecop
 ```
 
-##  Basic usage
+## Basics and usage
 
-Timecop allows you to freeze and travel in time. Just use the `Clock` class instead of `DateTime`to get the current time via `Now` or `UtcNow` properties, and manipulate time with the `Timecop` class in your tests.
+To test with Timecop, your code must get the current time using either:
+- The `IClock` interface injected as a method or a constructor parameter;
+- The static `Clock` class.
+ 
+### Usage with the `IClock` interface
+
+Timecop provides the `IClock` interface that exposes the `Now` and `UtcNow` properties.
+
+Here's how to use it:
+1. Pass the instance of `IClock` to your code as a method or a constructur parameter and use it to get the current time;
+1. In your tests, configure the `Timecop` instance and pass the `Timecop.Clock` into the code under test;
+1. When running in production, pass the `IClock` implementaton that returns the current time. You can use the [Timecop.Extensions.DependencyInjection](https://github.com/timecop-net/Timecop.Extensions.DependencyInjection) package to register such implementation with the DI container in one line of code.
+
+Here's an example:
+
+```csharp
+string Greet(IClock clock)
+{
+    var timeOfDay = clock.Now.Hour switch
+    {
+        >= 0 and < 6 => "night",
+        >= 6 and < 12 => "morning",
+        >= 12 and < 18 => "afternoon",
+        _ => "evening"
+    };
+
+    return $"Good {timeOfDay}!";
+}
+
+// freeze at 2pm local time:
+using var tc = Timecop.Frozen(o => o.At(14,0,0).LocalTime()); 
+
+Greet(tc.Clock); // Good afternoon!
+
+// travel to 8pm local time:
+tc.TravelBy(TimeSpan.FromHours(6)); 
+
+Greet(tc.Clock); // Good evening!
+```
+
+### Usage with the `Clock` class
+
+Timecop provides the static `Clock` class that you can use instead of `DateTime` to get the current local or UTC time. Despite `Clock` being a static class, it is safe to use in tests that run in parallel as it uses [AsyncLocal](https://learn.microsoft.com/en-us/dotnet/api/system.threading.asynclocal-1) under the hood.
+
+Here's how to use it:
+1. Replace the calls to `DateTime.Now` and `DateTime.UtcNow` with `Clock.Now` and `Clock.UtcNow`;
+1. In your tests, configure the `Timecop` instance
+
+Example:
 
 ```csharp
 string Greet()
@@ -45,11 +93,13 @@ Greet(); // Good evening!
 
 ## Available methods
 
+Timecop allows to manipulate time in any imaginable way. Freeze time, travel in time, and resume the flow of time with a simple API.
+
 ### Freezing and resuming time
 
-You can freeze the time so that it stops running for your tests until you call `Resume` or dispose the `Timecop` instance.
+You can freeze the time so that it stops running for your tests until you call `Resume`, `Reset`, or dispose the `Timecop` instance.
 
-You freeze time with either an instance `Freeze` or a static `Frozen` method, which both have the same set of overloads. Both methods have the same effect, however the static `Frozen` creates an already frozen `Timecop` instance.
+You freeze time with either an instance `Freeze` or a static `Frozen` method, both having the same set of overloads. Both methods have the same effect, however the static `Frozen` creates an already frozen `Timecop` instance.
 
 ```csharp
 using var tc = Timecop.Frozen(1990, 12, 2, 14, 38, 51, DateTimeKind.Local);
@@ -60,11 +110,11 @@ Thread.Sleep(TimeSpan.FromSeconds(3));
 
 Clock.Now; // 1990-12-02 14:38:51 - still the same value
 
-tc.Resume();
+tc.Resume(); // Resumes the flow of time.
 
 Thread.Sleep(TimeSpan.FromSeconds(3));
 
-Clock.Now; // 1990-12-02 14:38:54 - time has changed
+Clock.Now; // 1990-12-02 14:38:54 - moved 3 seconds forward
 ```
 
 `Freeze` and `Frozen` have multiple overloads:
@@ -73,24 +123,24 @@ Clock.Now; // 1990-12-02 14:38:54 - time has changed
 // freeze at the current instant:
 var frozenAt = tc.Freeze();
 
-// freeze at the specified DateTime:
+// freeze at the specific DateTime:
 frozenAt = tc.Freeze(new DateTime(1990, 12, 2, 14, 38, 51, DateTimeKind.Utc));
 
-// freeze at the specified date and time:
+// freeze at the specific date and time:
 frozenAt = tc.Freeze(1990, 12, 2, 14, 38, 51, DateTimeKind.Utc);
 
-// freeze at the specified date:
+// freeze at the specific date:
 frozenAt = tc.Freeze(1990, 12, 2, DateTimeKind.Utc);
 
-// freeze at the specified date or time using a builder:
+// freeze at the specific date or time using PointInTimeBuilder:
 frozenAt = tc.Freeze(o => o.On(1990, 12, 2)
                 .At(14, 13, 51)
-                .LocalTime());
+                .InLocalZone());
 ```
 
 ### Traveling in time
 
-Use  the `TravelBy` method to travel forward and backward in time:
+Use the `TravelBy` method to travel forward and backward in time:
 
 ```csharp
 using var tc = Timecop.Frozen(1990, 12, 2, 14, 38, 51, DateTimeKind.Local);
@@ -100,6 +150,44 @@ tc.TravelBy(TimeSpan.FromDays(1));
 Clock.Now; // 1990-12-03 14:38:51 - one day in the future
 ```
 
+Use the `TravelTo` method to travel to the specific point in time:
+
+```csharp
+// travel to the specific DateTime:
+traveledTo = tc.TravelTo(new DateTime(1990, 12, 2, 14, 38, 51, DateTimeKind.Utc));
+
+// freeze at the specific date and time:
+traveledTo = tc.TravelTo(1990, 12, 2, 14, 38, 51, DateTimeKind.Utc);
+
+// freeze at the specific date:
+traveledTo = tc.TravelTo(1990, 12, 2, DateTimeKind.Utc);
+
+// freeze at the specific date or time using PointInTimeBuilder:
+traveledTo = tc.TravelTo(o => o.On(1990, 12, 2)
+                .At(14, 13, 51)
+                .InLocalZone());
+```
+
+### Using PointInTimeBuilder
+
+`Freeze`, `Frozen`, and `TravelTo` methods each accept a lambda that allows to configure the time with the `PointInTimeBuilder` class.
+
+Use `PointInTimeBuilder` to specify different components of date and time. When using `At` and `On` methods, always specify whether the time is local or UTC using `InLocalZone` or `InUtc`.
+
+
+```csharp
+// When only the date matters:
+builder.On(1990, 12, 2).InLocalZone(); // will use the specified date and current time
+
+// When only the time matters:
+builder.At(14, 13, 51).InLocalZone(); // will use the specified time and current date
+
+// When neither the date nor time matter, but the date must be in the future or in the past:
+builder.InTheFuture();
+
+builder.InThePast();
+```
+
 ## License
 
 Timecop was created by [Dmytro Khmara](https://dmytrokhmara.com) and is licensed under the [MIT license](LICENSE.txt).

src/Timecop/Clock.cs

@@ -2,7 +2,7 @@
 
 namespace TCop;
 
-public class Clock
+public static class Clock
 {
     /// <summary>Returns either current or pre-configured local time. Time can be pre-configured by using <see cref="T:TCop.Timecop" />.</summary>
     public static DateTime Now => Timecop.UtcNow.ToLocalTime();

src/Timecop/Time/Builder/PointInTimeBuilder.cs

@@ -19,13 +19,13 @@ public PointInTimeBuilder On(int year, int month, int day)
         return this;
     }
 
-    public PointInTimeBuilder LocalTime()
+    public PointInTimeBuilder InLocalZone()
     {
         _context.Kind = DateTimeKind.Local;
         return this;
     }
 
-    public PointInTimeBuilder UtcTime()
+    public PointInTimeBuilder InUtc()
     {
         _context.Kind = DateTimeKind.Utc;
         return this;

src/Timecop/Time/Builder/PointInTimeBuilderNeitherLocalNorUtcException.cs

@@ -4,7 +4,7 @@ namespace TCop.Time.Builder;
 
 public class PointInTimeBuilderNeitherLocalNorUtcException : Exception
 {
-    public PointInTimeBuilderNeitherLocalNorUtcException() : base($"Call either {nameof(PointInTimeBuilder.LocalTime)}() or {nameof(PointInTimeBuilder.UtcTime)}() when configuring the point in time.")
+    public PointInTimeBuilderNeitherLocalNorUtcException() : base($"Call either {nameof(PointInTimeBuilder.InLocalZone)}() or {nameof(PointInTimeBuilder.InUtc)}() when configuring the point in time.")
     {
     }
 }

test/Timecop.Tests/Time/PointInTimeBuilderTests.cs

@@ -12,7 +12,7 @@ public class PointInTimeBuilderTests
     [Fact]
     public void LocalTime_ShouldReturnCurrentLocalTime()
     {
-        _builder.LocalTime();
+        _builder.InLocalZone();
 
         _builder.Build(out var kind).DateTimeUtc.ToLocalTime().Should().BeCloseTo(DateTime.Now, DateTimeComparisonPrecision);
         kind.Should().Be(DateTimeKind.Local);
@@ -21,7 +21,7 @@ public void LocalTime_ShouldReturnCurrentLocalTime()
     [Fact]
     public void UtcTime_ShouldReturnCurrentUtcTime()
     {
-        _builder.UtcTime();
+        _builder.InUtc();
 
         _builder.Build(out var kind).DateTimeUtc.Should().BeCloseTo(DateTime.UtcNow, DateTimeComparisonPrecision);
         kind.Should().Be(DateTimeKind.Utc);
@@ -34,7 +34,7 @@ public void Build_OnWasCalled_ButNeitherLocalNorUtcWasCalled_ShouldThrow()
 
         var build = () => _builder.Build(out _);
 
-        build.Should().Throw<PointInTimeBuilderNeitherLocalNorUtcException>().WithMessage("Call either LocalTime() or UtcTime() when configuring the point in time.");
+        build.Should().Throw<PointInTimeBuilderNeitherLocalNorUtcException>().WithMessage("Call either InLocalZone() or InUtc() when configuring the point in time.");
     }
 
     [Fact]
@@ -44,7 +44,7 @@ public void Build_AtWasCalled_ButNeitherLocalNorUtcWasCalled_ShouldThrow()
 
         var build = () => _builder.Build(out _);
 
-        build.Should().Throw<PointInTimeBuilderNeitherLocalNorUtcException>().WithMessage("Call either LocalTime() or UtcTime() when configuring the point in time.");
+        build.Should().Throw<PointInTimeBuilderNeitherLocalNorUtcException>().WithMessage("Call either InLocalZone() or InUtc() when configuring the point in time.");
     }
 
     [Fact]
@@ -59,7 +59,7 @@ public void InTheFuture_ShouldReturnPointOfTimeInTheFuture()
     [Fact]
     public void InTheFuture_WithLocalTime_ShouldReturnPointOfTimeInTheFutureInLocalTime()
     {
-        _builder.InTheFuture().LocalTime();
+        _builder.InTheFuture().InLocalZone();
 
         _builder.Build(out var kind).DateTimeUtc.Should().BeAfter(DateTime.UtcNow);
         kind.Should().Be(DateTimeKind.Local);
@@ -79,7 +79,7 @@ public void On_ShouldReturnSetDateAndCurrentTime()
     {
         _builder
             .On(1990, 12, 2)
-            .LocalTime();
+            .InLocalZone();
 
         var now = DateTime.Now;
 
@@ -93,7 +93,7 @@ public void At_ShouldReturnSetTimeAndCurrentDate()
     {
         _builder
             .At(14, 15, 30, 893)
-            .LocalTime();
+            .InLocalZone();
 
         var now = DateTime.Now;
 

test/Timecop.Tests/TimecopFreezeTests.cs

@@ -66,7 +66,7 @@ public void FreezeAtRandomFutureLocalTime_ShouldFreeze_AndReturnFrozenLocalDateT
         {
             using var tc = new Timecop();
 
-            var frozenAt = tc.Freeze(o => o.InTheFuture().LocalTime());
+            var frozenAt = tc.Freeze(o => o.InTheFuture().InLocalZone());
             var currentLocalTime = DateTime.Now;
 
             Thread.Sleep(100);

test/Timecop.Tests/TimecopTravelTests.cs

@@ -70,7 +70,7 @@ public void TravelToRandomFutureLocalTime_ShouldTravel_AndReturnTheLocalDateTime
         {
             using var tc = new Timecop();
 
-            var traveledTo = tc.TravelTo(o => o.InTheFuture().LocalTime());
+            var traveledTo = tc.TravelTo(o => o.InTheFuture().InLocalZone());
             var currentLocalTime = DateTime.Now;
 
             Thread.Sleep(100);