Kotest Core Matchers

Introduces the types of Kotest core matchers.

Tags:

These matchers are provided by the kotest-assertions-core module.

General
`obj.shouldBe(other)`	Checks that the given `obj` and `other` are equal.
`expr.shouldBeTrue()`	Checks that the expression is true. Equivalent to `expr.shouldBe(true)`.
`expr.shouldBeFalse()`	Checks that the expression is false. Equivalent to `expr.shouldBe(false)`.
`shouldThrow<T> { block }`	Checks that the block throws `T` or a subtype of `T`.
`shouldThrowExactly<T> { block }`	Checks that the block throws exactly `T`.
`shouldThrowAny { block }`	Checks that the block throws any type of `Throwable`.
`shouldThrowMessage(message) { block }`	Checks that the code block throws a `Throwable` with the given message.

Types
`obj.shouldBeSameInstanceAs(other)`	Compares objects by identity, that is, by the same reference.
`obj.shouldBeTypeOf<T>()`	Checks that the reference is exactly type `T`; subclasses fail.
`obj.shouldBeInstanceOf<T>()`	Checks that the reference is type `T` or a subclass of `T`.
`obj.shouldHaveAnnotation(annotationClass)`	Checks that the object has an annotation of the given type.
`obj.shouldBeNull()`	Checks that the reference is null.

Comparables
`comp.shouldBeLessThan(other)`	Uses `compareTo` to check that `comp` is less than `other`.
`comp.shouldBeLessThanOrEqualTo(other)`	Uses `compareTo` to check that `comp` is less than or equal to `other`.
`comp.shouldBeEqualComparingTo(other)`	Uses `compareTo` to check that `comp` equals `other`.
`comp.shouldBeEqualComparingTo(other, comparator)`	Uses `comparator.compare` to check that `comp` equals `other`.
`comp.shouldBeGreaterThan(other)`	Uses `compareTo` to check that `comp` is greater than `other`.
`comp.shouldBeGreaterThanOrEqualTo(other)`	Uses `compareTo` to check that `comp` is greater than or equal to `other`.

Iterator
`iterator.shouldBeEmpty()`	Checks that the iterator has no next value.
`iterator.shouldHaveNext()`	Checks that the iterator has a next value.

Maps
`map.shouldContain("key", "value")`	Checks that the map contains a mapping from `"key"` to `"value"`.
`map.shouldContainAll(other)`	Checks that the map contains all pairs from the given map.
`map.shouldContainExactly(other)`	Checks that the map contains exactly the pairs from the given map and no extra entries.
`map.shouldContainKey(key)`	Checks that the map contains the key with any value.
`map.shouldContainKeys(keys)`	Checks that the map contains mappings for all given keys.
`map.shouldContainValue(value)`	Checks that the map contains at least one mapping with the given value.
`map.shouldContainValues(values)`	Checks that the map contains all given values.
`map.shouldBeEmpty()`	Checks that the map is empty.
`map.shouldMatchAll("k1" to {it shouldBe "v1"}, "k2" to {it shouldBe "v2"}, ...)`	Asserts that all entries in the map can match the provided matchers; extra keys are ignored.
`map.shouldMatchExactly("k1" to {it shouldBe "v1"}, "k2" to {it shouldBe "v2"}, ...)`	Checks that the map entries match the provided matchers exactly.

Strings
`str.shouldBeBlank()`	Checks that the string is empty or contains only whitespace.
`str.shouldBeEmpty()`	Checks that the string has length 0.
`str.shouldBeLowerCase()`	Checks that the string is all lowercase.
`str.shouldBeUpperCase()`	Checks that the string is all uppercase.
`str.shouldContain("substr")`	Checks that the string contains the given substring. This matcher is case-sensitive.
`str.shouldContain(regex)`	Checks that the string contains the given regular expression.
`str.shouldContainADigit()`	Checks that the string contains at least one digit.
`str.shouldContainIgnoringCase(substring)`	Checks that the string contains the substring ignoring case.
`str.shouldContainOnlyDigits()`	Checks that the string contains only digits or is empty.
`str.shouldBeInteger([radix])`	Checks that the string contains an int and returns it.
`str.shouldContainOnlyOnce(substring)`	Checks that the string contains the substring exactly once.
`str.shouldEndWith(suffix)`	Checks that the string ends with the given suffix.
`str.shouldHaveLength(length)`	Checks that the string has the given length.
`str.shouldHaveLineCount(count)`	Checks that the string has the given number of lines.
`str.shouldHaveMaxLength(max)`	Checks that the string is not longer than the given maximum length.
`str.shouldHaveMinLength(min)`	Checks that the string is not shorter than the given minimum length.
`str.shouldHaveSameLengthAs(anotherString)`	Checks that the string has the same length as another string.
`str.shouldMatch(regex)`	Checks that the string fully matches the given regular expression.
`str.shouldStartWith("prefix")`	Checks that the string starts with the given prefix.
`str.shouldBeEqualIgnoringCase(other)`	Checks that the string equals another string ignoring case.
`str.shouldBeTruthy()`	Checks that the string is truthy: one of `true`, `yes`, `y`, or `1`.
`str.shouldBeFalsy()`	Checks that the string is falsy: one of `false`, `no`, `n`, or `0`.

Integers, Longs, Doubles, and Floats
`number.shouldBeBetween(x, y)`	Checks that the number is between `x` and `y`, inclusive.
`number.shouldBeLessThan(n)`	Checks that the number is less than `n`.
`number.shouldBeLessThanOrEqual(n)`	Checks that the number is less than or equal to `n`.
`number.shouldBeGreaterThan(n)`	Checks that the number is greater than `n`.
`number.shouldBeGreaterThanOrEqual(n)`	Checks that the number is greater than or equal to `n`.
`number.shouldBeInRange(range)`	Checks that the number is in the given range.
`number.shouldBeEven()`	Checks that the number is even.
`number.shouldBeOdd()`	Checks that the number is odd.
`number.shouldBeZero()`	Checks that the number is zero.
`double.shouldBe(value plusOrMinus(tolerance))`	Checks that the double equals the given value within tolerance.
`double.shouldBePositive()`	Checks that the double is positive.
`double.shouldBeNegative()`	Checks that the double is negative.
`double.shouldBePositiveInfinity()`	Checks that the double is positive infinity.
`double.shouldBeNegativeInfinity()`	Checks that the double is negative infinity.
`double.shouldBeNaN()`	Checks that the double is NaN.

BigDecimal
`bigDecimal.shouldHavePrecision(n)`	Checks that the BigDecimal precision equals `n`.
`bigDecimal.shouldHaveScale(n)`	Checks that the BigDecimal scale equals `n`.
`bigDecimal.shouldBePositive()`	Checks that the BigDecimal is positive.
`bigDecimal.shouldBeNegative()`	Checks that the BigDecimal is negative.
`bigDecimal.shouldBeZero()`	Checks that the BigDecimal is zero.
`bigDecimal.shouldBeLessThan(n)`	Checks that the BigDecimal is less than `n`.
`bigDecimal.shouldBeLessThanOrEquals(n)`	Checks that the BigDecimal is less than or equal to `n`.
`bigDecimal.shouldBeGreaterThan(n)`	Checks that the BigDecimal is greater than `n`.
`bigDecimal.shouldBeGreaterThanOrEquals(n)`	Checks that the BigDecimal is greater than or equal to `n`.
`bigDecimal.shouldBeInRange(r)`	Checks that the BigDecimal is in the given range.

Channels
`channel.shouldReceiveWithin(duration)`	Checks that the channel receives within the duration.
`channel.shouldReceiveNoElementsWithin(duration)`	Checks that the channel receives no elements within the duration.
`channel.shouldHaveSize(n)`	Checks that the channel receives exactly `n` elements before closing.
`channel.shouldReceiveAtLeast(n)`	Checks that the channel receives at least `n` elements.
`channel.shouldReceiveAtMost(n)`	Checks that the channel receives at most `n` elements before closing.
`channel.shouldBeClosed()`	Checks that the channel is closed.
`channel.shouldBeOpen()`	Checks that the channel is open.
`channel.shouldBeEmpty()`	Checks that the channel is empty.

URIs
`uri.shouldHaveAuthority(fragment)`	Checks that the URI has the given authority.
`uri.shouldHaveFragment(fragment)`	Checks that the URI has the given fragment.
`uri.shouldHaveHost(scheme)`	Checks that the URI has the given host.
`uri.shouldHaveParameter(scheme)`	Checks that the URI query string contains the given parameter.
`uri.shouldHavePath(scheme)`	Checks that the URI has the given path.
`uri.shouldHavePort(scheme)`	Checks that the URI has the given port.
`uri.shouldHaveQuery(fragment)`	Checks that the URI has the given query.
`uri.shouldHaveScheme(scheme)`	Checks that the URI has the given scheme.

Files
`file.shouldBeAbsolute()`	Checks that the file represents an absolute path.
`file.shouldBeADirectory()`	Checks that the file represents a directory.
`file.shouldBeAFile()`	Checks that the file represents a file.
`file.shouldBeCanonical()`	Checks that the file is in canonical form.
`file.shouldBeEmpty()`	Checks that the file exists and is empty.
`file.shouldBeExecutable()`	Checks that the current process can execute the file.
`file.shouldBeHidden()`	Checks that the file exists on disk and is hidden.
`file.shouldBeReadable()`	Checks that the current process can read the file.
`file.shouldBeRelative()`	Checks that the file represents a relative path.
`file.shouldBeSmaller(file)`	Checks that this file is smaller than the given file.
`file.shouldBeLarger(file)`	Checks that this file is larger than the given file.
`file.shouldBeWriteable()`	Checks that the current process can write the file.
`dir.shouldBeNonEmptyDirectory()`	Checks that the file is a directory and is not empty.
`dir.shouldContainFile(name)`	Checks that the directory contains a file with the given name.
`dir.shouldContainNFiles(name)`	Checks that the directory contains exactly `n` files.
`file.shouldExist()`	Checks that the file exists on disk as a directory or file.
`file.shouldHaveExtension(ext)`	Checks that the file ends with the given extension.
`file.shouldHaveFileSize(size)`	Checks that the file has the given size.
`file.shouldHaveName(name)`	Checks that the file name matches the given name.
`file.shouldHavePath(path)`	Checks that the file path matches the given path.
`file.shouldStartWithPath(prefix)`	Checks that the file path starts with the given prefix.
`dir.shouldContainFileDeep(name)`	Checks that the directory or one of its subdirectories contains a file with the given name.
`dir.shouldContainFiles(name1, name2, ..., nameN)`	Checks that the directory contains all files with the given names.
`file.shouldBeSymbolicLink()`	Checks that the file is a symbolic link.
`file.shouldHaveParent(name)`	Checks that the file has a parent with the given name.

Date and time
`date.shouldHaveSameYearAs(otherDate)`	Checks that the date has the same year as the given date.
`date.shouldHaveSameMonthAs(otherDate)`	Checks that the date has the same month as the given date.
`date.shouldBeBefore(otherDate)`	Checks that the date is before the given date.
`date.shouldBeAfter(otherDate)`	Checks that the date is after the given date.
`date.shouldBeWithin(duration, otherDate)`	Checks that the date is within the duration of the given date.
`date.shouldBetween(firstDate, secondDate)`	Checks that the date is between the first and second dates.
`date.shouldHaveYear(year)`	Checks that the date has the given year.
`date.shouldHaveMonth(month)`	Checks that the date has the given month.
`date.shouldHaveDayOfYear(day)`	Checks that the date has the given day of year.
`date.shouldHaveDayOfMonth(day)`	Checks that the date has the given day of month.
`date.shouldHaveDayOfWeek(day)`	Checks that the date has the given day of week.
`date.shouldHaveHour(hour)`	Checks that the date has the given hour.
`date.shouldHaveMinute(minute)`	Checks that the date has the given minute.
`date.shouldHaveSecond(second)`	Checks that the date has the given second.
`date.shouldHaveNano(nano)`	Checks that the date has the given nanosecond.
`zonedDateTime.shouldBeToday()`	Checks that the `ZonedDateTime` is today.
`zonedDateTime.shouldHaveSameInstantAs(other: ZonedDateTime)`	Checks that the `ZonedDateTime` is the same instant as another `ZonedDateTime`.
`offsetDateTime.shouldBeToday()`	Checks that the `OffsetDateTime` is today.
`offsetDateTime.shouldHaveSameInstantAs(other: OffsetDateTime)`	Checks that the `OffsetDateTime` is the same instant as another `OffsetDateTime`.
`time.shouldBeBefore(otherTime)`	Checks that the time is before the given time.
`time.shouldBeAfter(otherTime)`	Checks that the time is after the given time.
`time.shouldBeBetween(firstTime, secondTime)`	Checks that the time is between `firstTime` and `secondTime`.
`instant.shouldBeAfter(anotherInstant)`	Checks that the instant occurs after another instant.
`instant.shouldBeBefore(anotherInstant)`	Checks that the instant occurs before another instant.
`instant.shouldBeBetween(fromInstant, toInstant)`	Checks that the instant is between `fromInstant` and `toInstant`.
`instant.shouldBeCloseTo(anotherInstant, duration)`	Checks that the instant is close to another instant within the duration.

Concurrent, futures, and threads
`shouldCompleteWithin(timeout, unit, function)`	Checks that the function completes within the given duration.
`shouldTimeout(timeout, unit, function)`	Checks that the function does not complete within the given duration.
`shouldTimeout(duration, suspensableFunction)`	Checks that the suspendable function does not complete within the given duration.
`future.shouldBeCancelled()`	Checks that the future was cancelled.
`future.shouldBeCompleted()`	Checks that the future completed.
`future.shouldBeCompletedExceptionally()`	Checks that the future completed exceptionally.
`future.shouldCompleteExceptionallyWith(throwable)`	Checks that the future completed with the given exception.
`thread.shouldBeBlocked()`	Checks that the thread is currently blocked.
`thread.shouldBeDaemon()`	Checks that the thread is a daemon thread.
`thread.shouldBeAlive()`	Checks that the thread is alive.
`thread.shouldBeTerminating()`	Checks that the thread has terminated.

Throwables / Exceptions
`throwable.shouldHaveMessage(message)`	Checks that the throwable message equals the given message.
`throwable.shouldHaveCause()`	Checks that the throwable has a cause.
`throwable.shouldHaveCause { block }`	Checks that the throwable has a cause and passes it to the block.
`throwable.shouldHaveCauseInstanceOf<T>()`	Checks that the throwable has a cause that is type `T` or a subtype of `T`.
`throwable.shouldHaveCauseOfType<T>()`	Checks that the throwable has a cause that is exactly type `T`.

Result and Optional
`result.shouldBeSuccess()`	Checks that the result is success.
`result.shouldBeSuccess(value)`	Checks that the result is success and has the given value.
`result.shouldBeSuccess(block)`	Assumes the result is success and runs the block with the result value.
`result.shouldBeFailure()`	Checks that the result is failure.
`result.shouldBeFailureOfType<Type : Throwable>()`	Checks that the result is failure with the given exception class.
`result.shouldBeFailure(block)`	Assumes the result is failure and runs the block with the exception.
`optional.shouldBePresent()`	Checks that the `Optional` is present.
`optional.shouldBePresent { value -> .. }`	Checks that the `Optional` is present and runs the block with its value.
`optional.shouldBeEmpty()`	Checks that the `Optional` is empty.

Reflection
`kclass.shouldHaveAnnotations()`	Checks that the class has annotations.
`kclass.shouldHaveAnnotations(n)`	Checks that the class has exactly `n` annotations.
`kclass.shouldBeAnnotatedWith<T>()`	Checks that the class is annotated with the given type.
`kclass.shouldHaveFunction(name)`	Checks that the class has a function with the given name.
`kclass.shouldHaveMemberProperty(name)`	Checks that the class has a member property with the given name.
`kclass.shouldBeSubtypeOf<T>()`	Checks that the class is a subtype of `T`.
`kclass.shouldBeSupertypeOf<T>()`	Checks that the class is a supertype of `T`.
`kclass.shouldBeData()`	Checks that the class is a data class.
`kclass.shouldBeSealed()`	Checks that the class is a sealed class.
`kclass.shouldBeCompanion()`	Checks that the class is a companion object.
`kclass.shouldHavePrimaryConstructor()`	Checks that the class has a primary constructor.
`kclass.shouldHaveVisibility(visibility)`	Checks that the class has the given visibility.
`kfunction.shouldHaveReturnType<T>()`	Checks that the function returns the given type.
`kfunction.shouldBeInline()`	Checks that the function is inline.
`kfunction.shouldBeInfix()`	Checks that the function is infix.
`kproperty.shouldBeOfType<T>()`	Checks that the property has the given type.
`kproperty.shouldBeConst()`	Checks that the property is `const`.
`kproperty.shouldBeLateInit()`	Checks that the property is a `lateinit var`.
`kcallable.shouldHaveVisibility(visibility)`	Checks that the member has the given visibility.
`kcallable.shouldBeFinal()`	Checks that the member is final.
`kcallable.shouldBeOpen()`	Checks that the member is open.
`kcallable.shouldBeAbstract()`	Checks that the member is abstract.
`kcallable.shouldBeSuspendable()`	Checks that the member is suspendable.
`kcallable.shouldAcceptParameters(parameters)`	Checks that the member can be called with the given parameters.
`kcallable.shouldHaveParametersWithName(parameters)`	Checks that the member has parameters with the given names.
`ktype.shouldBeOfType<T>()`	Checks that the `KType` is `T`.

Statistic
`collection.shouldHaveMean(mean)`	Checks that the collection has the given mean with default precision 4.
`collection.shouldHaveMean(mean, precision)`	Checks that the collection has the given mean with the given precision.
`collection.shouldHaveVariance(mean)`	Checks that the collection has the given variance with default precision 4.
`collection.shouldHaveVariance(mean, precision)`	Checks that the collection has the given variance with the given precision.
`collection.shouldHaveStandardDeviation(mean)`	Checks that the collection has the given standard deviation with default precision 4.
`collection.shouldHaveStandardDeviation(mean, precision)`	Checks that the collection has the given standard deviation with the given precision.

Regex
`regex.shouldBeRegex(anotherRegex)`	Checks that the regex equals another regex by comparing the pattern and options.
`regex.shouldHavePattern(regexPattern)`	Checks that the regex has the given pattern.
`regex.shouldHaveExactRegexOptions(regexOptions)`	Checks that the regex has exactly the given options.
`regex.shouldIncludeRegexOption(regexOption)`	Checks that the regex includes the given option.
`regex.shouldIncludeRegexOptions(regexOptions)`	Checks that the regex includes the given options.

Selective Matchers
`any.shouldBeEqualToUsingFields(other: T, vararg properties: KProperty<*>)`	Checks equality against `other` using only the given properties.
`any.shouldBeEqualToIgnoringFields(other: T, vararg properties: KProperty<*>)`	Checks equality against `other` while ignoring the given properties.

Field by Field Comparison Matchers
`any.shouldBeEqualToComparingFields(other: T)`	Checks equality against `other` by comparing fields instead of using `equals`, ignoring private fields.
`any.shouldBeEqualToComparingFields(other: T, ignorePrivateFields: Boolean)`	Checks equality against `other` by comparing fields instead of using `equals`, including private fields when configured.
~~`any.shouldBeEqualToComparingFieldsExcept(...)`~~	Deprecated. Use `shouldBeEqualToComparingFields` or `shouldBeEqualToIgnoringFields` instead.

Resource Matchers
`str shouldMatchResource "/path/to/test_resource.txt"`	Checks that the string equals the given resource, ignoring line separator differences.
`str shouldNotMatchResource "/path/to/test_resource.txt"`	Checks that the string does not equal the given resource, ignoring line separator differences.
`str.shouldMatchResource("/path/to/test_resource.txt", ::providedMatcher)`	Uses `providedMatcher` to check that the string matches the given resource.
`str.shouldNotMatchResource("/path/to/test_resource.txt", ::providedMatcher)`	Uses `providedMatcher` to check that the string does not match the given resource.
`byteArray shouldMatchResource "/path/to/test_resource.bin"`	Checks that the byte array equals the given resource.
`byteArray shouldNotMatchResource "/path/to/test_resource.bin"`	Checks that the byte array does not equal the given resource.
`byteArray.shouldMatchResource("/path/to/test_resource.bin", ::providedMatcher)`	Uses `providedMatcher` to check that the byte array matches the given resource.
`byteArray.shouldNotMatchResource("/path/to/test_resource.bin", ::providedMatcher)`	Uses `providedMatcher` to check that the byte array does not match the given resource.

References

Core Matchers | Kotest