tessl/maven-io-kotest--kotest-assertions-core-jvm
Core assertion and matcher library for Kotest testing framework
—
Pending
primitives.mddocs/
Primitive Matchers
Comprehensive matchers for all Kotlin primitive types including Boolean, Integer, Long, Short, Byte, Character, Float, and Double values with type-specific validations, comparisons, and range operations.
Capabilities
Boolean Matchers
Simple true/false assertions for Boolean values.
/**
* Assert that this Boolean value is true
* @return The original Boolean value for chaining
*/
fun Boolean.shouldBeTrue(): Boolean
/**
* Assert that this Boolean value is not true (false or null)
* @return The original Boolean value for chaining
*/
fun Boolean.shouldNotBeTrue(): Boolean
/**
* Assert that this Boolean value is false
* @return The original Boolean value for chaining
*/
fun Boolean.shouldBeFalse(): Boolean
/**
* Assert that this Boolean value is not false (true or null)
* @return The original Boolean value for chaining
*/
fun Boolean.shouldNotBeFalse(): Boolean
/**
* Create a matcher that checks if value is true
* @return Matcher that passes for true values
*/
fun beTrue(): Matcher<Boolean>
/**
* Create a matcher that checks if value is false
* @return Matcher that passes for false values
*/
fun beFalse(): Matcher<Boolean>Usage Examples:
import io.kotest.matchers.booleans.*
val isValid = true
val isComplete = false
isValid.shouldBeTrue()
isComplete.shouldBeFalse()
// Using with should syntax
isValid should beTrue()
isComplete should beFalse()Integer Matchers
Comprehensive matchers for Int values including comparisons, ranges, and percentage tolerance.
/**
* Assert that this Int is between two values (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return The original Int value for chaining
*/
fun Int.shouldBeBetween(a: Int, b: Int): Int
/**
* Assert that this Int is not between two values
* @param a Lower bound
* @param b Upper bound
* @return The original Int value for chaining
*/
fun Int.shouldNotBeBetween(a: Int, b: Int): Int
/**
* Assert that this Int is within the specified range
* @param range IntRange to check membership
* @return The original Int value for chaining
*/
infix fun Int.shouldBeInRange(range: IntRange): Int
/**
* Assert that this Int is not within the specified range
* @param range IntRange to check non-membership
* @return The original Int value for chaining
*/
infix fun Int.shouldNotBeInRange(range: IntRange): Int
/**
* Assert that this Int is within percentage tolerance of another value
* @param other The target value to compare against
* @param percentage The allowed percentage difference (0.0 to 100.0)
* @return The original Int value for chaining
*/
fun Int.shouldBeWithinPercentageOf(other: Int, percentage: Double): Int
/**
* Assert that this Int is not within percentage tolerance of another value
* @param other The target value to compare against
* @param percentage The percentage threshold (0.0 to 100.0)
* @return The original Int value for chaining
*/
fun Int.shouldNotBeWithinPercentageOf(other: Int, percentage: Double): IntInteger Comparison Matchers
/**
* Create a matcher for less than comparison
* @param x The upper bound (exclusive)
* @return Matcher that passes for values less than x
*/
fun lt(x: Int): Matcher<Int>
/**
* Create a matcher for less than comparison (alias for lt)
* @param x The upper bound (exclusive)
* @return Matcher that passes for values less than x
*/
fun beLessThan(x: Int): Matcher<Int>
/**
* Create a matcher for less than or equal comparison
* @param x The upper bound (inclusive)
* @return Matcher that passes for values less than or equal to x
*/
fun lte(x: Int): Matcher<Int>
/**
* Create a matcher for less than or equal comparison (alias for lte)
* @param x The upper bound (inclusive)
* @return Matcher that passes for values less than or equal to x
*/
fun beLessThanOrEqualTo(x: Int): Matcher<Int>
/**
* Create a matcher for greater than comparison
* @param x The lower bound (exclusive)
* @return Matcher that passes for values greater than x
*/
fun gt(x: Int): Matcher<Int>
/**
* Create a matcher for greater than comparison (alias for gt)
* @param x The lower bound (exclusive)
* @return Matcher that passes for values greater than x
*/
fun beGreaterThan(x: Int): Matcher<Int>
/**
* Create a matcher for greater than or equal comparison
* @param x The lower bound (inclusive)
* @return Matcher that passes for values greater than or equal to x
*/
fun gte(x: Int): Matcher<Int>
/**
* Create a matcher for greater than or equal comparison (alias for gte)
* @param x The lower bound (inclusive)
* @return Matcher that passes for values greater than or equal to x
*/
fun beGreaterThanOrEqualTo(x: Int): Matcher<Int>
/**
* Create a matcher for exact value comparison
* @param x The exact value to match
* @return Matcher that passes for the exact value
*/
fun exactly(x: Int): Matcher<Int>
/**
* Create a matcher for range membership
* @param range The IntRange to check membership
* @return Matcher that passes for values within the range
*/
fun beInRange(range: IntRange): Matcher<Int>
/**
* Create a matcher for between comparison (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return Matcher that passes for values between a and b
*/
fun between(a: Int, b: Int): Matcher<Int>
/**
* Create a matcher for percentage tolerance comparison
* @param other The target value
* @param percentage The allowed percentage difference
* @return Matcher that passes for values within percentage of target
*/
fun beWithinPercentageOf(other: Int, percentage: Double): Matcher<Int>Usage Examples:
import io.kotest.matchers.ints.*
val score = 85
val count = 42
// Range assertions
score.shouldBeBetween(80, 90)
count shouldBeInRange 40..50
// Comparison assertions
score should beGreaterThan(80)
score should beLessThanOrEqualTo(100)
// Percentage tolerance
score.shouldBeWithinPercentageOf(90, 10.0) // Within 10% of 90
// Exact value
count should exactly(42)Long Matchers
Similar pattern to Int matchers but for Long and ULong types.
/**
* Assert that this Long is between two values (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return The original Long value for chaining
*/
fun Long.shouldBeBetween(a: Long, b: Long): Long
/**
* Assert that this Long is within the specified range
* @param range LongRange to check membership
* @return The original Long value for chaining
*/
infix fun Long.shouldBeInRange(range: LongRange): Long
/**
* Assert that this Long is within percentage tolerance of another value
* @param other The target value to compare against
* @param percentage The allowed percentage difference (0.0 to 100.0)
* @return The original Long value for chaining
*/
fun Long.shouldBeWithinPercentageOf(other: Long, percentage: Double): Long
// Comparison functions follow same pattern as Int
fun lt(x: Long): Matcher<Long>
fun gt(x: Long): Matcher<Long>
fun lte(x: Long): Matcher<Long>
fun gte(x: Long): Matcher<Long>
fun exactly(x: Long): Matcher<Long>
fun between(a: Long, b: Long): Matcher<Long>Short Matchers
Similar pattern to Int matchers but for Short and UShort types.
/**
* Assert that this Short is between two values (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return The original Short value for chaining
*/
fun Short.shouldBeBetween(a: Short, b: Short): Short
// Range and comparison functions follow same pattern as Int
infix fun Short.shouldBeInRange(range: IntRange): Short
fun Short.shouldBeWithinPercentageOf(other: Short, percentage: Double): Short
fun lt(x: Short): Matcher<Short>
fun gt(x: Short): Matcher<Short>
fun exactly(x: Short): Matcher<Short>Byte Matchers
Similar pattern to Int matchers but for Byte and UByte types.
/**
* Assert that this Byte is between two values (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return The original Byte value for chaining
*/
fun Byte.shouldBeBetween(a: Byte, b: Byte): Byte
// Range and comparison functions follow same pattern as Int
infix fun Byte.shouldBeInRange(range: IntRange): Byte
fun Byte.shouldBeWithinPercentageOf(other: Byte, percentage: Double): Byte
fun lt(x: Byte): Matcher<Byte>
fun gt(x: Byte): Matcher<Byte>
fun exactly(x: Byte): Matcher<Byte>Character Matchers
Character-specific matchers for ASCII validation, case checking, and character categories.
/**
* Assert that this Char is a letter (alphabetic character)
* @return The original Char value for chaining
*/
fun Char.shouldBeLetter(): Char
/**
* Assert that this Char is not a letter
* @return The original Char value for chaining
*/
fun Char.shouldNotBeLetter(): Char
/**
* Assert that this Char is a digit (0-9)
* @return The original Char value for chaining
*/
fun Char.shouldBeDigit(): Char
/**
* Assert that this Char is not a digit
* @return The original Char value for chaining
*/
fun Char.shouldNotBeDigit(): Char
/**
* Assert that this Char is uppercase
* @return The original Char value for chaining
*/
fun Char.shouldBeUpperCase(): Char
/**
* Assert that this Char is lowercase
* @return The original Char value for chaining
*/
fun Char.shouldBeLowerCase(): Char
/**
* Assert that this Char is whitespace
* @return The original Char value for chaining
*/
fun Char.shouldBeWhitespace(): Char
/**
* Assert that this Char is an ASCII character (0-127)
* @return The original Char value for chaining
*/
fun Char.shouldBeAscii(): Char
/**
* Create matcher for letter validation
* @return Matcher that passes for alphabetic characters
*/
fun beLetter(): Matcher<Char>
/**
* Create matcher for digit validation
* @return Matcher that passes for numeric characters (0-9)
*/
fun beDigit(): Matcher<Char>
/**
* Create matcher for uppercase validation
* @return Matcher that passes for uppercase characters
*/
fun beUpperCase(): Matcher<Char>
/**
* Create matcher for lowercase validation
* @return Matcher that passes for lowercase characters
*/
fun beLowerCase(): Matcher<Char>
/**
* Create matcher for whitespace validation
* @return Matcher that passes for whitespace characters
*/
fun beWhitespace(): Matcher<Char>
/**
* Create matcher for ASCII validation
* @return Matcher that passes for ASCII characters (0-127)
*/
fun beAscii(): Matcher<Char>Usage Examples:
import io.kotest.matchers.char.*
val letter = 'A'
val digit = '5'
val space = ' '
// Character category assertions
letter.shouldBeLetter()
letter.shouldBeUpperCase()
letter.shouldBeAscii()
digit.shouldBeDigit()
space.shouldBeWhitespace()
// Using matcher syntax
letter should beLetter()
digit should beDigit()Float Matchers
Floating-point matchers with tolerance support for precision handling.
/**
* Assert that this Float is between two values (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return The original Float value for chaining
*/
fun Float.shouldBeBetween(a: Float, b: Float): Float
/**
* Assert that this Float equals another value within default tolerance
* @param other The expected value
* @return The original Float value for chaining
*/
infix fun Float.shouldBeExactly(other: Float): Float
/**
* Assert that this Float equals another value within specified tolerance
* @param other The expected value
* @param tolerance The maximum allowed difference
* @return The original Float value for chaining
*/
fun Float.shouldBeWithinTolerance(other: Float, tolerance: Float): Float
/**
* Assert that this Float is positive (greater than 0)
* @return The original Float value for chaining
*/
fun Float.shouldBePositive(): Float
/**
* Assert that this Float is negative (less than 0)
* @return The original Float value for chaining
*/
fun Float.shouldBeNegative(): Float
/**
* Assert that this Float is zero (within tolerance)
* @return The original Float value for chaining
*/
fun Float.shouldBeZero(): Float
/**
* Assert that this Float is NaN (Not a Number)
* @return The original Float value for chaining
*/
fun Float.shouldBeNaN(): Float
/**
* Assert that this Float is infinite
* @return The original Float value for chaining
*/
fun Float.shouldBeInfinite(): Float
/**
* Create matcher for exact equality with tolerance
* @param expected The expected value
* @param tolerance The maximum allowed difference
* @return Matcher that passes for values within tolerance
*/
fun beExactly(expected: Float, tolerance: Float = 0.0001f): Matcher<Float>
/**
* Create matcher for positive number validation
* @return Matcher that passes for positive values
*/
fun bePositive(): Matcher<Float>
/**
* Create matcher for negative number validation
* @return Matcher that passes for negative values
*/
fun beNegative(): Matcher<Float>
/**
* Create matcher for zero validation with tolerance
* @return Matcher that passes for zero (within default tolerance)
*/
fun beZero(): Matcher<Float>
/**
* Create matcher for NaN validation
* @return Matcher that passes for NaN values
*/
fun beNaN(): Matcher<Float>
/**
* Create matcher for infinity validation
* @return Matcher that passes for infinite values
*/
fun beInfinite(): Matcher<Float>Double Matchers
Double precision matchers with enhanced tolerance support.
/**
* Assert that this Double is between two values (inclusive)
* @param a Lower bound (inclusive)
* @param b Upper bound (inclusive)
* @return The original Double value for chaining
*/
fun Double.shouldBeBetween(a: Double, b: Double): Double
/**
* Assert that this Double equals another value within default tolerance
* @param other The expected value
* @return The original Double value for chaining
*/
infix fun Double.shouldBeExactly(other: Double): Double
/**
* Assert that this Double equals another value within specified tolerance
* @param other The expected value
* @param tolerance The maximum allowed difference
* @return The original Double value for chaining
*/
fun Double.shouldBeWithinTolerance(other: Double, tolerance: Double): Double
/**
* Assert that this Double is within percentage of another value
* @param other The target value
* @param percentage The allowed percentage difference (0.0 to 100.0)
* @return The original Double value for chaining
*/
fun Double.shouldBeWithinPercentageOf(other: Double, percentage: Double): Double
/**
* Assert that this Double is positive (greater than 0)
* @return The original Double value for chaining
*/
fun Double.shouldBePositive(): Double
/**
* Assert that this Double is negative (less than 0)
* @return The original Double value for chaining
*/
fun Double.shouldBeNegative(): Double
/**
* Assert that this Double is zero (within tolerance)
* @return The original Double value for chaining
*/
fun Double.shouldBeZero(): Double
/**
* Assert that this Double is NaN (Not a Number)
* @return The original Double value for chaining
*/
fun Double.shouldBeNaN(): Double
/**
* Assert that this Double is infinite
* @return The original Double value for chaining
*/
fun Double.shouldBeInfinite(): Double
// Matcher factory functions follow same pattern as Float
fun beExactly(expected: Double, tolerance: Double = 0.000000001): Matcher<Double>
fun beWithinPercentageOf(other: Double, percentage: Double): Matcher<Double>
fun bePositive(): Matcher<Double>
fun beNegative(): Matcher<Double>
fun beZero(): Matcher<Double>
fun beNaN(): Matcher<Double>
fun beInfinite(): Matcher<Double>Usage Examples:
import io.kotest.matchers.doubles.*
import io.kotest.matchers.floats.*
val price = 19.99
val calculation = 0.1 + 0.2
// Tolerance-based equality
price.shouldBeWithinTolerance(20.0, 0.01)
calculation.shouldBeExactly(0.3) // Uses default tolerance
// Percentage comparison
price.shouldBeWithinPercentageOf(20.0, 5.0) // Within 5% of 20.0
// Sign validation
price.shouldBePositive()
(-price).shouldBeNegative()
// Special value validation
val invalid = Double.NaN
invalid.shouldBeNaN()
// Using matcher syntax
price should beWithinPercentageOf(20.0, 10.0)
calculation should beExactly(0.3, 0.0001)Error Handling
Primitive matchers provide detailed error messages for failures:
- Numeric comparisons: Show expected vs actual values with clear comparison operators
- Range failures: Indicate the range bounds and actual value position
- Tolerance failures: Display the expected value, actual value, tolerance, and actual difference
- Character category failures: Specify which category check failed and the actual character
- Special value failures: Clear messages for NaN, infinity, and other special cases
All matchers preserve type safety and provide meaningful error messages that help identify the specific assertion failure.
Install with Tessl CLI
npx tessl i tessl/maven-io-kotest--kotest-assertions-core-jvm