tessl/maven-io-kotest--kotest-assertions-core-jvm
Core assertion and matcher library for Kotest testing framework
—
Pending
datetime.mddocs/
Date and Time Matchers
JVM date and time assertions for Java time API including temporal comparisons, duration validation, and specialized date/time operations for comprehensive temporal testing capabilities.
Capabilities
LocalDate Matchers
Matchers for LocalDate validation including comparisons and date-specific operations.
/**
* Assert that LocalDate is before another date
* @param other The date this should be before
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldBeBefore(other: LocalDate): LocalDate
/**
* Assert that LocalDate is not before another date
* @param other The date this should not be before
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldNotBeBefore(other: LocalDate): LocalDate
/**
* Assert that LocalDate is after another date
* @param other The date this should be after
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldBeAfter(other: LocalDate): LocalDate
/**
* Assert that LocalDate is not after another date
* @param other The date this should not be after
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldNotBeAfter(other: LocalDate): LocalDate
/**
* Assert that LocalDate is today's date
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeToday(): LocalDate
/**
* Assert that LocalDate is not today's date
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldNotBeToday(): LocalDate
/**
* Assert that LocalDate is yesterday's date
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeYesterday(): LocalDate
/**
* Assert that LocalDate is tomorrow's date
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeTomorrow(): LocalDate
/**
* Assert that LocalDate is within specified number of days from another date
* @param days Number of days tolerance
* @param other The reference date
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeWithinDays(days: Int, other: LocalDate): LocalDate
/**
* Create matcher for date comparison (before)
* @param other The date to compare against
* @return Matcher that passes when date is before other
*/
fun beBefore(other: LocalDate): Matcher<LocalDate>
/**
* Create matcher for date comparison (after)
* @param other The date to compare against
* @return Matcher that passes when date is after other
*/
fun beAfter(other: LocalDate): Matcher<LocalDate>
/**
* Create matcher for today validation
* @return Matcher that passes when date is today
*/
fun beToday(): Matcher<LocalDate>
/**
* Create matcher for yesterday validation
* @return Matcher that passes when date is yesterday
*/
fun beYesterday(): Matcher<LocalDate>
/**
* Create matcher for tomorrow validation
* @return Matcher that passes when date is tomorrow
*/
fun beTomorrow(): Matcher<LocalDate>
/**
* Create matcher for date proximity validation
* @param days Number of days tolerance
* @param other The reference date
* @return Matcher that passes when date is within specified days
*/
fun beWithinDays(days: Int, other: LocalDate): Matcher<LocalDate>Usage Examples:
import io.kotest.matchers.date.*
import java.time.LocalDate
val today = LocalDate.now()
val birthday = LocalDate.of(1990, 6, 15)
val deadline = LocalDate.of(2024, 12, 31)
// Date comparison
birthday shouldBeBefore today
deadline shouldBeAfter today
today.shouldBeToday()
// Proximity validation
val nearDate = today.plusDays(2)
nearDate.shouldBeWithinDays(5, today)
// Using matcher syntax
birthday should beBefore(today)
today should beToday()
deadline should beAfter(LocalDate.now())LocalTime Matchers
Matchers for LocalTime validation and time-specific operations.
/**
* Assert that LocalTime is before another time
* @param other The time this should be before
* @return The original LocalTime for chaining
*/
infix fun LocalTime.shouldBeBefore(other: LocalTime): LocalTime
/**
* Assert that LocalTime is after another time
* @param other The time this should be after
* @return The original LocalTime for chaining
*/
infix fun LocalTime.shouldBeAfter(other: LocalTime): LocalTime
/**
* Assert that LocalTime is within specified duration of another time
* @param duration The maximum allowed difference
* @param other The reference time
* @return The original LocalTime for chaining
*/
fun LocalTime.shouldBeWithin(duration: Duration, other: LocalTime): LocalTime
/**
* Assert that LocalTime represents morning (AM)
* @return The original LocalTime for chaining
*/
fun LocalTime.shouldBeMorning(): LocalTime
/**
* Assert that LocalTime represents afternoon (PM)
* @return The original LocalTime for chaining
*/
fun LocalTime.shouldBeAfternoon(): LocalTime
/**
* Assert that LocalTime is within business hours (9 AM - 5 PM)
* @return The original LocalTime for chaining
*/
fun LocalTime.shouldBeBusinessHours(): LocalTime
/**
* Create matcher for time comparison (before)
* @param other The time to compare against
* @return Matcher that passes when time is before other
*/
fun beBefore(other: LocalTime): Matcher<LocalTime>
/**
* Create matcher for time comparison (after)
* @param other The time to compare against
* @return Matcher that passes when time is after other
*/
fun beAfter(other: LocalTime): Matcher<LocalTime>
/**
* Create matcher for time proximity validation
* @param duration Maximum allowed difference
* @param other The reference time
* @return Matcher that passes when time is within duration
*/
fun beWithin(duration: Duration, other: LocalTime): Matcher<LocalTime>
/**
* Create matcher for morning time validation
* @return Matcher that passes for morning times
*/
fun beMorning(): Matcher<LocalTime>
/**
* Create matcher for business hours validation
* @return Matcher that passes for business hour times
*/
fun beBusinessHours(): Matcher<LocalTime>LocalDateTime Matchers
Matchers for LocalDateTime combining date and time validation capabilities.
/**
* Assert that LocalDateTime is before another datetime
* @param other The datetime this should be before
* @return The original LocalDateTime for chaining
*/
infix fun LocalDateTime.shouldBeBefore(other: LocalDateTime): LocalDateTime
/**
* Assert that LocalDateTime is after another datetime
* @param other The datetime this should be after
* @return The original LocalDateTime for chaining
*/
infix fun LocalDateTime.shouldBeAfter(other: LocalDateTime): LocalDateTime
/**
* Assert that LocalDateTime is within specified duration of another datetime
* @param duration The maximum allowed difference
* @param other The reference datetime
* @return The original LocalDateTime for chaining
*/
fun LocalDateTime.shouldBeWithin(duration: Duration, other: LocalDateTime): LocalDateTime
/**
* Assert that LocalDateTime is close to now within specified duration
* @param duration Maximum allowed difference from current time
* @return The original LocalDateTime for chaining
*/
fun LocalDateTime.shouldBeCloseToNow(duration: Duration): LocalDateTime
/**
* Assert that LocalDateTime represents today (same date as today)
* @return The original LocalDateTime for chaining
*/
fun LocalDateTime.shouldBeToday(): LocalDateTime
/**
* Assert that LocalDateTime is in the past
* @return The original LocalDateTime for chaining
*/
fun LocalDateTime.shouldBeInPast(): LocalDateTime
/**
* Assert that LocalDateTime is in the future
* @return The original LocalDateTime for chaining
*/
fun LocalDateTime.shouldBeInFuture(): LocalDateTime
/**
* Create matcher for datetime comparison (before)
* @param other The datetime to compare against
* @return Matcher that passes when datetime is before other
*/
fun beBefore(other: LocalDateTime): Matcher<LocalDateTime>
/**
* Create matcher for datetime comparison (after)
* @param other The datetime to compare against
* @return Matcher that passes when datetime is after other
*/
fun beAfter(other: LocalDateTime): Matcher<LocalDateTime>
/**
* Create matcher for datetime proximity validation
* @param duration Maximum allowed difference
* @param other The reference datetime
* @return Matcher that passes when datetime is within duration
*/
fun beWithin(duration: Duration, other: LocalDateTime): Matcher<LocalDateTime>
/**
* Create matcher for recent time validation
* @param duration Maximum age from now
* @return Matcher that passes when datetime is recent
*/
fun beCloseToNow(duration: Duration): Matcher<LocalDateTime>
/**
* Create matcher for past time validation
* @return Matcher that passes for past datetimes
*/
fun beInPast(): Matcher<LocalDateTime>
/**
* Create matcher for future time validation
* @return Matcher that passes for future datetimes
*/
fun beInFuture(): Matcher<LocalDateTime>Usage Examples:
import io.kotest.matchers.date.*
import java.time.*
val now = LocalDateTime.now()
val pastEvent = now.minusHours(2)
val futureEvent = now.plusDays(1)
val morningTime = LocalTime.of(9, 30)
// DateTime comparison
pastEvent shouldBeBefore now
futureEvent shouldBeAfter now
pastEvent.shouldBeInPast()
futureEvent.shouldBeInFuture()
// Time validation
morningTime.shouldBeMorning()
morningTime.shouldBeBusinessHours()
// Proximity validation
val recent = now.minusMinutes(5)
recent.shouldBeCloseToNow(Duration.ofMinutes(10))
// Using matcher syntax
pastEvent should beInPast()
futureEvent should beInFuture()
morningTime should beMorning()Instant and ZonedDateTime Matchers
Matchers for timezone-aware and UTC instant validation.
/**
* Assert that Instant is before another instant
* @param other The instant this should be before
* @return The original Instant for chaining
*/
infix fun Instant.shouldBeBefore(other: Instant): Instant
/**
* Assert that Instant is after another instant
* @param other The instant this should be after
* @return The original Instant for chaining
*/
infix fun Instant.shouldBeAfter(other: Instant): Instant
/**
* Assert that Instant is within specified duration of another instant
* @param duration The maximum allowed difference
* @param other The reference instant
* @return The original Instant for chaining
*/
fun Instant.shouldBeWithin(duration: Duration, other: Instant): Instant
/**
* Assert that Instant is close to now within specified duration
* @param duration Maximum allowed difference from current instant
* @return The original Instant for chaining
*/
fun Instant.shouldBeCloseToNow(duration: Duration): Instant
/**
* Assert that ZonedDateTime is in specified timezone
* @param zone The expected timezone
* @return The original ZonedDateTime for chaining
*/
infix fun ZonedDateTime.shouldBeInZone(zone: ZoneId): ZonedDateTime
/**
* Assert that ZonedDateTime is in UTC timezone
* @return The original ZonedDateTime for chaining
*/
fun ZonedDateTime.shouldBeInUTC(): ZonedDateTime
/**
* Assert that ZonedDateTime is before another zoned datetime
* @param other The datetime this should be before
* @return The original ZonedDateTime for chaining
*/
infix fun ZonedDateTime.shouldBeBefore(other: ZonedDateTime): ZonedDateTime
/**
* Assert that ZonedDateTime is after another zoned datetime
* @param other The datetime this should be after
* @return The original ZonedDateTime for chaining
*/
infix fun ZonedDateTime.shouldBeAfter(other: ZonedDateTime): ZonedDateTime
/**
* Create matcher for instant comparison (before)
* @param other The instant to compare against
* @return Matcher that passes when instant is before other
*/
fun beBefore(other: Instant): Matcher<Instant>
/**
* Create matcher for instant proximity validation
* @param duration Maximum allowed difference
* @param other The reference instant
* @return Matcher that passes when instant is within duration
*/
fun beWithin(duration: Duration, other: Instant): Matcher<Instant>
/**
* Create matcher for timezone validation
* @param zone Expected timezone
* @return Matcher that passes when datetime is in specified zone
*/
fun beInZone(zone: ZoneId): Matcher<ZonedDateTime>
/**
* Create matcher for UTC timezone validation
* @return Matcher that passes when datetime is in UTC
*/
fun beInUTC(): Matcher<ZonedDateTime>Duration and Period Matchers
Matchers for validating time durations and date periods.
/**
* Assert that Duration is positive (greater than zero)
* @return The original Duration for chaining
*/
fun Duration.shouldBePositive(): Duration
/**
* Assert that Duration is negative (less than zero)
* @return The original Duration for chaining
*/
fun Duration.shouldBeNegative(): Duration
/**
* Assert that Duration is zero
* @return The original Duration for chaining
*/
fun Duration.shouldBeZero(): Duration
/**
* Assert that Duration is greater than another duration
* @param other The duration to compare against
* @return The original Duration for chaining
*/
infix fun Duration.shouldBeGreaterThan(other: Duration): Duration
/**
* Assert that Duration is less than another duration
* @param other The duration to compare against
* @return The original Duration for chaining
*/
infix fun Duration.shouldBeLessThan(other: Duration): Duration
/**
* Assert that Duration is between two durations (inclusive)
* @param min Lower bound duration (inclusive)
* @param max Upper bound duration (inclusive)
* @return The original Duration for chaining
*/
fun Duration.shouldBeBetween(min: Duration, max: Duration): Duration
/**
* Assert that Period is positive (all components positive or zero)
* @return The original Period for chaining
*/
fun Period.shouldBePositive(): Period
/**
* Assert that Period is negative (at least one component negative)
* @return The original Period for chaining
*/
fun Period.shouldBeNegative(): Period
/**
* Assert that Period is zero (all components zero)
* @return The original Period for chaining
*/
fun Period.shouldBeZero(): Period
/**
* Create matcher for positive duration validation
* @return Matcher that passes for positive durations
*/
fun bePositive(): Matcher<Duration>
/**
* Create matcher for duration comparison (greater than)
* @param other The duration to compare against
* @return Matcher that passes when duration is greater
*/
fun beGreaterThan(other: Duration): Matcher<Duration>
/**
* Create matcher for duration range validation
* @param min Lower bound duration
* @param max Upper bound duration
* @return Matcher that passes when duration is within range
*/
fun beBetween(min: Duration, max: Duration): Matcher<Duration>Usage Examples:
import io.kotest.matchers.date.*
import java.time.*
val utcZone = ZoneId.of("UTC")
val pacificZone = ZoneId.of("America/Los_Angeles")
val utcTime = ZonedDateTime.now(utcZone)
val pacificTime = ZonedDateTime.now(pacificZone)
// Timezone validation
utcTime.shouldBeInUTC()
pacificTime shouldBeInZone pacificZone
// Instant validation
val now = Instant.now()
val past = now.minusSeconds(30)
val future = now.plusMinutes(5)
past shouldBeBefore now
future shouldBeAfter now
past.shouldBeCloseToNow(Duration.ofMinutes(1))
// Duration validation
val shortDuration = Duration.ofSeconds(30)
val longDuration = Duration.ofHours(2)
shortDuration.shouldBePositive()
longDuration shouldBeGreaterThan shortDuration
shortDuration.shouldBeBetween(Duration.ofSeconds(10), Duration.ofMinutes(1))
// Using matcher syntax
utcTime should beInUTC()
shortDuration should bePositive()
longDuration should beGreaterThan(Duration.ofHours(1))Specialized Date Operations
Advanced matchers for complex date and time operations.
/**
* Assert that date is a weekend (Saturday or Sunday)
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeWeekend(): LocalDate
/**
* Assert that date is a weekday (Monday through Friday)
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeWeekday(): LocalDate
/**
* Assert that date is a specific day of week
* @param dayOfWeek The expected day of week
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldBeDayOfWeek(dayOfWeek: DayOfWeek): LocalDate
/**
* Assert that date is in specified month
* @param month The expected month
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldBeInMonth(month: Month): LocalDate
/**
* Assert that date is in specified year
* @param year The expected year
* @return The original LocalDate for chaining
*/
infix fun LocalDate.shouldBeInYear(year: Int): LocalDate
/**
* Assert that date is a leap year
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeLeapYear(): LocalDate
/**
* Assert that date is not a leap year
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldNotBeLeapYear(): LocalDate
/**
* Assert that date is first day of month
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeFirstDayOfMonth(): LocalDate
/**
* Assert that date is last day of month
* @return The original LocalDate for chaining
*/
fun LocalDate.shouldBeLastDayOfMonth(): LocalDate
/**
* Create matcher for weekend validation
* @return Matcher that passes for weekend dates
*/
fun beWeekend(): Matcher<LocalDate>
/**
* Create matcher for weekday validation
* @return Matcher that passes for weekday dates
*/
fun beWeekday(): Matcher<LocalDate>
/**
* Create matcher for day of week validation
* @param dayOfWeek The expected day of week
* @return Matcher that passes for specified day of week
*/
fun beDayOfWeek(dayOfWeek: DayOfWeek): Matcher<LocalDate>
/**
* Create matcher for month validation
* @param month The expected month
* @return Matcher that passes for dates in specified month
*/
fun beInMonth(month: Month): Matcher<LocalDate>
/**
* Create matcher for leap year validation
* @return Matcher that passes for leap year dates
*/
fun beLeapYear(): Matcher<LocalDate>
/**
* Create matcher for month boundary validation
* @return Matcher that passes for first day of month
*/
fun beFirstDayOfMonth(): Matcher<LocalDate>Usage Examples:
import io.kotest.matchers.date.*
import java.time.*
val monday = LocalDate.of(2024, 1, 1) // Assuming this is a Monday
val saturday = LocalDate.of(2024, 1, 6)
val christmas = LocalDate.of(2024, 12, 25)
val leapYearDate = LocalDate.of(2024, 2, 29)
// Day of week validation
monday.shouldBeWeekday()
saturday.shouldBeWeekend()
monday shouldBeDayOfWeek DayOfWeek.MONDAY
// Month and year validation
christmas shouldBeInMonth Month.DECEMBER
christmas shouldBeInYear 2024
// Leap year validation
leapYearDate.shouldBeLeapYear()
// Month boundary validation
val firstDay = LocalDate.of(2024, 1, 1)
firstDay.shouldBeFirstDayOfMonth()
// Using matcher syntax
monday should beWeekday()
saturday should beWeekend()
christmas should beInMonth(Month.DECEMBER)
leapYearDate should beLeapYear()Error Handling
Date and time matchers provide comprehensive error messages for assertion failures:
- Temporal comparison failures: Show expected vs actual dates/times with clear temporal relationship
- Duration failures: Display expected vs actual durations in human-readable format
- Timezone failures: Indicate expected vs actual timezones with offset information
- Proximity failures: Show the actual difference compared to allowed tolerance
- Calendar failures: Clear indication of expected vs actual day/month/year components
- Period failures: Detailed breakdown of period components (years, months, days)
All date/time matchers handle edge cases like leap years, daylight saving transitions, and timezone conversions while providing meaningful error context for temporal assertion failures.
Install with Tessl CLI
npx tessl i tessl/maven-io-kotest--kotest-assertions-core-jvm