refactor: change ClockAdvanceAmount to UtcNowAdvanceAmount

Author: egil

CHANGELOG.md

@@ -17,9 +17,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   Overriding `CreateManualTimer` makes it possible to intercept a `TimerCallback` and perform actions before and after the timer callback has been invoked.
 
-- Replace `AutoAdvanceAmount` property with the `AutoAdvanceBehavior` property on `ManualTimeProvider`, and introduced the `AutoAdvanceBehavior` type.
+- Replace `AutoAdvanceAmount` property with the `AutoAdvanceBehavior` property on `ManualTimeProvider`, and introduced the `AutoAdvanceBehavior` type. To automatically advance time when `GetUtcNow()` or `GetLocalNow()` is called, set `AutoAdvanceBehavior.UtcNowAdvanceAmount` to a time span larger than zero.
 
-- Enable auto advance feature for `GetTimestamp()` and `GetElapsedTime(long)`.
+- Enable auto advance feature for `GetTimestamp()` and `GetElapsedTime(long)`. To automatically advance time when `GetTimestamp()` or `GetElapsedTime(long)` is called, set `AutoAdvanceBehavior.TimestampAdvanceAmount` to a time span larger than zero.
 
 ## [1.0.0-rc.1]
 

src/TimeProviderExtensions/AutoAdvanceBehavior.cs

@@ -18,7 +18,7 @@ public sealed record class AutoAdvanceBehavior
     /// Set to <see cref="TimeSpan.Zero"/> to disable auto advance. The default value is <see cref="TimeSpan.Zero"/>.
     /// </remarks>
     /// <exception cref="ArgumentOutOfRangeException">Thrown when set to a value less than <see cref="TimeSpan.Zero"/>.</exception>
-    public TimeSpan ClockAdvanceAmount { get => clockAdvanceAmount; set { ThrowIfLessThanZero(value); clockAdvanceAmount = value; } }
+    public TimeSpan UtcNowAdvanceAmount { get => clockAdvanceAmount; set { ThrowIfLessThanZero(value); clockAdvanceAmount = value; } }
 
     /// <summary>
     /// Gets or sets the amount of time by which time advances whenever the a timestamp is read via <see cref="TimeProvider.GetTimestamp"/>

src/TimeProviderExtensions/ManualTimeProvider.cs

@@ -124,8 +124,8 @@ public override long GetTimestamp()
     /// all according to this <see cref="ManualTimeProvider"/>'s notion of time.
     /// </summary>
     /// <remarks>
-    /// If <see cref="AutoAdvanceBehavior.ClockAdvanceAmount"/> is greater than <see cref="TimeSpan.Zero"/>, calling this
-    /// method will move time forward by the amount specified by <see cref="AutoAdvanceBehavior.ClockAdvanceAmount"/>.
+    /// If <see cref="AutoAdvanceBehavior.UtcNowAdvanceAmount"/> is greater than <see cref="TimeSpan.Zero"/>, calling this
+    /// method will move time forward by the amount specified by <see cref="AutoAdvanceBehavior.UtcNowAdvanceAmount"/>.
     /// The <see cref="DateTimeOffset"/> returned from this method will reflect the time before
     /// the auto advance was applied, if any.
     /// </remarks>
@@ -136,7 +136,7 @@ public override DateTimeOffset GetUtcNow()
         lock (callbacks)
         {
             result = utcNow;
-            Advance(AutoAdvanceBehavior.ClockAdvanceAmount);
+            Advance(AutoAdvanceBehavior.UtcNowAdvanceAmount);
         }
 
         return result;
@@ -248,7 +248,7 @@ public void SetLocalTimeZone(TimeZoneInfo localTimeZone)
     /// <em>3 seconds</em>, <em>3 seconds</em>, and <em>3 seconds</em>, use <see cref="Jump(DateTimeOffset)"/> or <see cref="Jump(TimeSpan)"/> instead.
     /// </para>
     /// <para>
-    /// Learn more about this behavior at <seealso href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
+    /// Learn more about this behavior at <see href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
     /// </para>
     /// </remarks>
     /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="delta"/> is negative. Going back in time is not supported.</exception>
@@ -306,7 +306,7 @@ public void Advance(TimeSpan delta)
     /// <em>3 seconds</em>, <em>3 seconds</em>, and <em>3 seconds</em>, use <see cref="Jump(DateTimeOffset)"/> or <see cref="Jump(TimeSpan)"/> instead.
     /// </para>
     /// <para>
-    /// Learn more about this behavior at <seealso href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
+    /// Learn more about this behavior at <see href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
     /// </para>
     /// </remarks>
     /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="value"/> is less than the value returned by <see cref="GetUtcNow()"/>. Going back in time is not supported.</exception>
@@ -389,7 +389,7 @@ public void SetUtcNow(DateTimeOffset value)
     /// use <see cref="Advance(TimeSpan)"/> or <see cref="SetUtcNow(DateTimeOffset)"/> instead.
     /// </para>
     /// <para>
-    /// Learn more about this behavior at <seealso href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
+    /// Learn more about this behavior at <see href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
     /// </para>
     /// </remarks>
     /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="delta"/> is negative. Going back in time is not supported.</exception>
@@ -446,7 +446,7 @@ public void Jump(TimeSpan delta)
     /// use <see cref="Advance(TimeSpan)"/> or <see cref="SetUtcNow(DateTimeOffset)"/> instead.
     /// </para>
     /// <para>
-    /// Learn more about this behavior at <seealso href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
+    /// Learn more about this behavior at <see href="https://github.com/egil/TimeProviderExtensions/#difference-between-manualtimeprovider-and-faketimeprovider"/>.
     /// </para>
     /// </remarks>
     /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="value"/> is less than the value returned by <see cref="GetUtcNow()"/>. Going back in time is not supported.</exception>

test/TimeProviderExtensions.Tests/AutoAdvanceBehaviorTests.cs

@@ -7,10 +7,10 @@ public void ClockAdvanceAmount_throws_when_lt_zero()
     {
         var sut = new AutoAdvanceBehavior();
 
-        var throws = () => sut.ClockAdvanceAmount = TimeSpan.FromTicks(-1);
+        var throws = () => sut.UtcNowAdvanceAmount = TimeSpan.FromTicks(-1);
 
         throws.Should().Throw<ArgumentOutOfRangeException>()
-            .And.ParamName.Should().Be(nameof(AutoAdvanceBehavior.ClockAdvanceAmount));
+            .And.ParamName.Should().Be(nameof(AutoAdvanceBehavior.UtcNowAdvanceAmount));
     }
 
     [Fact]

test/TimeProviderExtensions.Tests/ManualTimeProviderTests.cs

@@ -150,7 +150,7 @@ async Task AsyncCallbacks(PeriodicTimer periodicTimer)
     public void Timer_callback_GetUtcNow_AutoAdvance()
     {
         var oneSecond = TimeSpan.FromSeconds(1);
-        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = oneSecond } };
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { UtcNowAdvanceAmount = oneSecond } };
 
         using var t1 = sut.CreateTimer(_ =>
         {
@@ -163,7 +163,7 @@ public void Timer_callback_GetUtcNow_AutoAdvance()
     [Fact]
     public void GetUtcNow_with_ClockAdvanceAmount_gt_zero()
     {
-        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = 1.Seconds() } };
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { UtcNowAdvanceAmount = 1.Seconds() } };
 
         var result = sut.GetUtcNow();
 
@@ -174,7 +174,7 @@ public void GetUtcNow_with_ClockAdvanceAmount_gt_zero()
     [Fact]
     public void GetLocalNow_with_ClockAdvanceAmount_gt_zero()
     {
-        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { ClockAdvanceAmount = 1.Seconds() } };
+        var sut = new ManualTimeProvider() { AutoAdvanceBehavior = { UtcNowAdvanceAmount = 1.Seconds() } };
 
         var result = sut.GetLocalNow();
 

test/TimeProviderExtensions.Tests/Microsoft.Extensions.Time.Testing.Test/FakeTimeProviderTests.cs

@@ -306,7 +306,7 @@ public async Task WaitAsync_Cancel()
     [Fact]
     public void AutoAdvance()
     {
-        var timeProvider = new FakeTimeProvider { AutoAdvanceBehavior = { ClockAdvanceAmount = TimeSpan.FromSeconds(1) } };
+        var timeProvider = new FakeTimeProvider { AutoAdvanceBehavior = { UtcNowAdvanceAmount = TimeSpan.FromSeconds(1) } };
 
         var first = timeProvider.GetUtcNow();
         var second = timeProvider.GetUtcNow();
@@ -330,11 +330,11 @@ public void ToString_AutoAdvance_off()
     [Fact]
     public void ToString_AutoAdvance_on()
     {
-        var timeProvider = new FakeTimeProvider { AutoAdvanceBehavior = { ClockAdvanceAmount = TimeSpan.FromSeconds(1) } };
+        var timeProvider = new FakeTimeProvider { AutoAdvanceBehavior = { UtcNowAdvanceAmount = TimeSpan.FromSeconds(1) } };
 
         _ = timeProvider.ToString();
 
-        timeProvider.AutoAdvanceBehavior.ClockAdvanceAmount = TimeSpan.Zero;
+        timeProvider.AutoAdvanceBehavior.UtcNowAdvanceAmount = TimeSpan.Zero;
         Assert.Equal(timeProvider.Start, timeProvider.GetUtcNow());
     }
 }