Skip to main content

DateTime / DateTimeOffset

Describes the possible expectations for DateTime and DateTimeOffset.

ExpectationNegatedSummary
IsEqualToIsNotEqualToequal to the expected value
IsOneOfIsNotOneOfequal to one of the expected values
IsAfterIsNotAfterlater than the expected value
IsOnOrAfterIsNotOnOrAfternot earlier than the expected value
IsBeforeIsNotBeforeearlier than the expected value
IsOnOrBeforeIsNotOnOrBeforenot later than the expected value
IsBetweenIsNotBetweenbetween two values, both bounds included
HasYear, …negated comparisonhas the expected year, month, day, hour, …
HasDayOfWeeknegated comparisonfalls on the expected day of the week
HasKindnegated comparisona DateTime with the expected Kind
HasOffsetnegated comparisona DateTimeOffset with the expected Offset

Equality​

You can verify that the DateTime or DateTimeOffset is equal to another one or not:

DateTime releaseDate = new DateTime(1969, 9, 26);

await That(releaseDate).IsEqualTo(new DateTime(1969, 9, 26));
await That(releaseDate).IsNotEqualTo(new DateTime(1970, 5, 8));

One of​

You can verify that the DateTime or DateTimeOffset is one of many alternatives:

DateTime releaseDate = new DateTime(1969, 9, 26);

await That(releaseDate).IsOneOf([new DateTime(1969, 9, 26), new DateTime(1970, 5, 8)]);
await That(releaseDate).IsNotOneOf([new DateTime(1965, 8, 6), new DateTime(1966, 8, 5)]);

After / before​

You can verify that the DateTime or DateTimeOffset is (on or) after or before another value, or that it is not:

DateTime releaseDate = new DateTime(1969, 9, 26);

await That(releaseDate).IsAfter(new DateTime(1968, 11, 22));
await That(releaseDate).IsOnOrAfter(new DateTime(1969, 9, 26));
await That(releaseDate).IsBefore(new DateTime(1970, 5, 8));
await That(releaseDate).IsOnOrBefore(new DateTime(1969, 9, 26));
await That(releaseDate).IsNotAfter(new DateTime(1970, 5, 8));

Between​

You can verify that the DateTime or DateTimeOffset is between two values, or that it is not:

DateTime releaseDate = new DateTime(1969, 9, 26);

await That(releaseDate).IsBetween(new DateTime(1969, 1, 1)).And(new DateTime(1969, 12, 31));
await That(releaseDate).IsNotBetween(new DateTime(1970, 1, 1)).And(new DateTime(1970, 12, 31));

Both bounds are included.

Tolerance​

Every comparison on this page except the Has… properties accepts a tolerance with Within, which widens the accepted range by the tolerance, the same way for DateTime and DateTimeOffset:

DateTime importedAt = DateTime.Now;

await That(importedAt).IsEqualTo(DateTime.Now).Within(TimeSpan.FromSeconds(1))
  .Because("the import should have taken less than one second");
await That(importedAt).IsOneOf([DateTime.Now]).Within(TimeSpan.FromSeconds(1));
await That(importedAt).IsAfter(DateTime.Now).Within(TimeSpan.FromSeconds(1));
await That(importedAt).IsOnOrBefore(DateTime.Now).Within(TimeSpan.FromSeconds(1));
await That(importedAt).IsBetween(DateTime.Today).And(DateTime.Now).Within(TimeSpan.FromSeconds(1));

Without Within, the default tolerance applies, if one is configured.

Kind​

aweXpect refuses to compare a DateTime with DateTimeKind.Utc against one with DateTimeKind.Local, because they describe different instants: every comparison fails, except IsNotEqualTo and IsNotOneOf. A value with DateTimeKind.Unspecified is compatible with both kinds, and a DateTimeOffset is always comparable:

DateTime releaseDate = new DateTime(1969, 9, 26, 0, 0, 0, DateTimeKind.Utc);

// fails with "but it had kind Utc, which cannot be compared with Local"
await That(releaseDate).IsBefore(new DateTime(1969, 9, 27, 0, 0, 0, DateTimeKind.Local));

await That(releaseDate).IsNotEqualTo(new DateTime(1969, 9, 26, 0, 0, 0, DateTimeKind.Local));
await That(releaseDate).IsEqualTo(new DateTime(1969, 9, 26, 0, 0, 0, DateTimeKind.Unspecified));

The same rule applies wherever a DateTime is compared as a value, e.g. in collection expectations and in IsEquivalentTo.

Details of the Kind rule

The negated ordering expectations IsNotAfter, IsNotBefore, IsNotOnOrAfter, IsNotOnOrBefore and IsNotBetween fail for an incompatible pair as well. For IsBetween and IsNotBetween the subject must be comparable to both bounds. For IsOneOf and IsNotOneOf an alternative with an incompatible Kind can never be the match, but the remaining alternatives are still considered.

In a collection, two values that differ only in their kind never match:

DateTime[] releaseDates = [new DateTime(1969, 9, 26, 0, 0, 0, DateTimeKind.Utc)];

// fails, because the expected value denotes a different instant
await That(releaseDates).Contains(new DateTime(1969, 9, 26, 0, 0, 0, DateTimeKind.Local));

Properties​

You can verify the properties of DateTime or DateTimeOffset:

DateTime importedAt = new DateTime(2024, 12, 31, 15, 16, 17, 189, DateTimeKind.Utc);
// or: DateTimeOffset importedAt = new(2024, 12, 31, 15, 16, 17, 189, TimeSpan.FromMinutes(90));

await That(importedAt).HasYear(2024);
await That(importedAt).HasMonth(12);
await That(importedAt).HasDay(31);
await That(importedAt).HasHour().GreaterThan(12);
await That(importedAt).HasMinute(16);
await That(importedAt).HasSecond(17);
await That(importedAt).HasMillisecond().LessThan(500);
await That(importedAt).HasDayOfWeek(DayOfWeek.Tuesday);
await That(importedAt).HasDayOfWeek().NotEqualTo(DayOfWeek.Sunday);

For DateTime you can also verify the Kind property, and for DateTimeOffset the Offset property:

DateTime importedAt = new DateTime(2024, 12, 31, 15, 16, 17, 189, DateTimeKind.Utc);

await That(importedAt).HasKind(DateTimeKind.Utc);
await That(importedAt).HasKind().NotEqualTo(DateTimeKind.Local);

The Has… expectations whose value is a number or a TimeSpan, e.g. HasLength(), HasCount(), HasYear() or HasMajor(), continue with one of the following comparisons, each with a negated counterpart:

ComparisonNegatedSucceeds when the value is
EqualTo(x)NotEqualTo(x)equal to x
GreaterThan(x)NotGreaterThan(x)greater than x
GreaterThanOrEqualTo(x)NotGreaterThanOrEqualTo(x)greater than or equal to x
LessThan(x)NotLessThan(x)less than x
LessThanOrEqualTo(x)NotLessThanOrEqualTo(x)less than or equal to x
Between(min).And(max)NotBetween(min).And(max)between min and max, both bounds included

Passing the value directly, e.g. HasYear(2024), is a shorthand for EqualTo.

Comparing with null

The expected value is nullable, e.g. to pass a value mapped from a property. As the actual value is never null, EqualTo(null) fails and NotEqualTo(null) succeeds, while a comparison of order against null, such as GreaterThan(null) or Between(null).And(3), fails even when negated.

HasDayOfWeek and HasKind only offer EqualTo and NotEqualTo.