tessl/maven-io-kotest--kotest-assertions-core-jvm
Core assertion and matcher library for Kotest testing framework
—
Pending
collections.mddocs/
Collection Matchers
Comprehensive collection assertions for lists, sets, maps, arrays, and sequences including element access, ordering, uniqueness, containment, and size validation with powerful pattern matching capabilities.
Capabilities
Element Access and Indexing
Matchers for accessing and validating elements at specific positions.
/**
* Assert that list has specific element at given index
* @param index The index position to check
* @param element The expected element at that index
* @return The original List for chaining
*/
fun <T> List<T>.shouldHaveElementAt(index: Int, element: T): List<T>
/**
* Assert that array has specific element at given index
* @param index The index position to check
* @param element The expected element at that index
* @return The original Array for chaining
*/
fun <T> Array<T>.shouldHaveElementAt(index: Int, element: T): Array<T>
/**
* Assert that iterable has specific element at given index
* @param index The index position to check (0-based)
* @param element The expected element at that index
* @return The original Iterable for chaining
*/
fun <T> Iterable<T>.shouldHaveElementAt(index: Int, element: T): Iterable<T>
/**
* Create matcher for element at index validation
* @param index The index position to check
* @param element The expected element
* @return Matcher that passes when element exists at specified index
*/
fun <T, L : List<T>> haveElementAt(index: Int, element: T): Matcher<L>
/**
* Assert that list should not have specific element at given index
* @param index The index position to check
* @param element The element that should not be at that index
* @return The original List for chaining
*/
fun <T> List<T>.shouldNotHaveElementAt(index: Int, element: T): List<T>Usage Examples:
import io.kotest.matchers.collections.*
val numbers = listOf(1, 2, 3, 4, 5)
val names = arrayOf("Alice", "Bob", "Charlie")
// Element position validation
numbers.shouldHaveElementAt(0, 1)
numbers.shouldHaveElementAt(2, 3)
names.shouldHaveElementAt(1, "Bob")
// Using matcher syntax
numbers should haveElementAt(4, 5)Existence and Predicate Matching
Matchers for checking element existence based on predicates and conditions.
/**
* Assert that collection contains at least one element matching predicate
* @param p Predicate function to test elements
* @return The original Collection for chaining
*/
infix fun <T> Collection<T>.shouldExist(p: (T) -> Boolean): Collection<T>
/**
* Assert that collection does not contain any element matching predicate
* @param p Predicate function to test elements
* @return The original Collection for chaining
*/
infix fun <T> Collection<T>.shouldNotExist(p: (T) -> Boolean): Collection<T>
/**
* Assert that all elements in collection match the predicate
* @param p Predicate function that should match all elements
* @return The original Collection for chaining
*/
infix fun <T> Collection<T>.shouldForAll(p: (T) -> Boolean): Collection<T>
/**
* Assert that no elements in collection match the predicate
* @param p Predicate function that should match no elements
* @return The original Collection for chaining
*/
infix fun <T> Collection<T>.shouldForNone(p: (T) -> Boolean): Collection<T>
/**
* Assert that exactly one element matches the predicate
* @param p Predicate function to test elements
* @return The original Collection for chaining
*/
infix fun <T> Collection<T>.shouldExistExactlyOnce(p: (T) -> Boolean): Collection<T>
/**
* Create matcher for element existence validation
* @param p Predicate function to test elements
* @return Matcher that passes when at least one element matches
*/
fun <T> exist(p: (T) -> Boolean): Matcher<Collection<T>>
/**
* Create matcher for universal predicate validation
* @param p Predicate function to test all elements
* @return Matcher that passes when all elements match
*/
fun <T> forAll(p: (T) -> Boolean): Matcher<Collection<T>>
/**
* Create matcher for no matches validation
* @param p Predicate function to test elements
* @return Matcher that passes when no elements match
*/
fun <T> forNone(p: (T) -> Boolean): Matcher<Collection<T>>Usage Examples:
import io.kotest.matchers.collections.*
val scores = listOf(85, 92, 78, 96, 88)
val users = listOf(
User("Alice", 25),
User("Bob", 30),
User("Charlie", 35)
)
// Predicate-based existence
scores shouldExist { it > 90 }
users shouldExist { it.age >= 30 }
// Universal conditions
scores shouldForAll { it >= 70 }
users shouldForAll { it.name.isNotEmpty() }
// Exact occurrence
scores shouldExistExactlyOnce { it > 95 }
// Using matcher syntax
scores should exist { it == 85 }
users should forAll { it.age > 18 }Pattern Matching and Ordering
Advanced matchers for validating element patterns and order relationships.
/**
* Assert that list elements match assertions in order
* @param assertions Variable number of assertion functions
* @return The original List for chaining
*/
fun <T> List<T>.shouldMatchInOrder(vararg assertions: (T) -> Unit): List<T>
/**
* Assert that list contains subset of elements matching assertions in order
* @param assertions Variable number of assertion functions
* @return The original List for chaining
*/
fun <T> List<T>.shouldMatchInOrderSubset(vararg assertions: (T) -> Unit): List<T>
/**
* Assert that each list element matches corresponding assertion
* @param assertions Variable number of assertion functions (must match list size)
* @return The original List for chaining
*/
fun <T> List<T>.shouldMatchEach(vararg assertions: (T) -> Unit): List<T>
/**
* Assert that elements exist in the list in specified order
* @param expected List of predicate functions to match in order
* @return The original List for chaining
*/
infix fun <T> List<T>.shouldExistInOrder(expected: List<(T) -> Boolean>): List<T>
/**
* Create matcher for in-order pattern matching
* @param assertions Variable number of assertion functions
* @return Matcher that passes when elements match assertions in order
*/
fun <T> matchInOrder(vararg assertions: (T) -> Unit): Matcher<List<T>>
/**
* Create matcher for subset order matching
* @param assertions Variable number of assertion functions
* @return Matcher that passes when subset matches in order
*/
fun <T> matchInOrderSubset(vararg assertions: (T) -> Unit): Matcher<List<T>>
/**
* Create matcher for each element matching
* @param assertions Variable number of assertion functions
* @return Matcher that passes when each element matches corresponding assertion
*/
fun <T> matchEach(vararg assertions: (T) -> Unit): Matcher<List<T>>Usage Examples:
import io.kotest.matchers.collections.*
import io.kotest.matchers.shouldBe
import io.kotest.matchers.ints.shouldBeGreaterThan
val numbers = listOf(1, 5, 10, 15, 20)
val words = listOf("apple", "banana", "cherry")
// Order-based pattern matching
numbers.shouldMatchInOrder(
{ it shouldBe 1 },
{ it shouldBeGreaterThan 3 },
{ it shouldBe 10 }
)
// Each element validation
words.shouldMatchEach(
{ it.shouldStartWith("a") },
{ it.shouldStartWith("b") },
{ it.shouldStartWith("c") }
)
// Subset order matching
numbers.shouldMatchInOrderSubset(
{ it shouldBe 1 },
{ it shouldBe 20 }
)Containment and Membership
Matchers for checking element containment and membership relationships.
/**
* Assert that collection contains any of the specified elements
* @param ts Variable number of elements to check
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainAnyOf(vararg ts: T): Collection<T>
/**
* Assert that collection contains any element from another collection
* @param elements Collection of elements to check
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainAnyOf(elements: Collection<T>): Collection<T>
/**
* Assert that collection contains all specified elements
* @param ts Variable number of elements that must all be present
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainAll(vararg ts: T): Collection<T>
/**
* Assert that collection contains all elements from another collection
* @param elements Collection of elements that must all be present
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainAll(elements: Collection<T>): Collection<T>
/**
* Assert that collection contains exactly the specified elements (order independent)
* @param ts Variable number of elements that should comprise the collection
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainExactly(vararg ts: T): Collection<T>
/**
* Assert that collection contains exactly elements from another collection
* @param elements Collection that should match exactly
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainExactly(elements: Collection<T>): Collection<T>
/**
* Assert that collection contains exactly the elements in specified order
* @param ts Variable number of elements in expected order
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldContainExactlyInAnyOrder(vararg ts: T): Collection<T>
/**
* Create matcher for any element containment
* @param ts Collection of possible elements
* @return Matcher that passes when collection contains any of the elements
*/
fun <T> containAnyOf(ts: Collection<T>): Matcher<Collection<T>>
/**
* Create matcher for all elements containment
* @param ts Collection of required elements
* @return Matcher that passes when all elements are present
*/
fun <T> containAll(ts: Collection<T>): Matcher<Collection<T>>
/**
* Create matcher for exact element matching
* @param ts Collection of exact elements expected
* @return Matcher that passes when collections contain exactly the same elements
*/
fun <T> containExactly(ts: Collection<T>): Matcher<Collection<T>>
/**
* Create matcher for exact elements in any order
* @param ts Collection of elements (order independent)
* @return Matcher that passes when same elements present regardless of order
*/
fun <T> containExactlyInAnyOrder(ts: Collection<T>): Matcher<Collection<T>>Size and Emptiness
Matchers for validating collection size and emptiness states.
/**
* Assert that collection is empty (contains no elements)
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldBeEmpty(): Collection<T>
/**
* Assert that collection is not empty
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldNotBeEmpty(): Collection<T>
/**
* Assert that collection has exactly specified size
* @param size The expected number of elements
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldHaveSize(size: Int): Collection<T>
/**
* Assert that collection does not have specified size
* @param size The size that should not match
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldNotHaveSize(size: Int): Collection<T>
/**
* Assert that collection size is within specified range
* @param range IntRange for valid size values
* @return The original Collection for chaining
*/
infix fun <T> Collection<T>.shouldHaveSizeBetween(range: IntRange): Collection<T>
/**
* Assert that collection size is between two values (inclusive)
* @param min Minimum size (inclusive)
* @param max Maximum size (inclusive)
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldHaveSizeBetween(min: Int, max: Int): Collection<T>
/**
* Assert that collection has at least specified size
* @param size Minimum required size
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldHaveAtLeastSize(size: Int): Collection<T>
/**
* Assert that collection has at most specified size
* @param size Maximum allowed size
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldHaveAtMostSize(size: Int): Collection<T>
/**
* Create matcher for empty collection validation
* @return Matcher that passes for empty collections
*/
fun <T> beEmpty(): Matcher<Collection<T>>
/**
* Create matcher for size validation
* @param size The expected collection size
* @return Matcher that passes for collections of exact size
*/
fun <T> haveSize(size: Int): Matcher<Collection<T>>
/**
* Create matcher for size range validation
* @param range IntRange for valid size values
* @return Matcher that passes for collections within size range
*/
fun <T> haveSizeBetween(range: IntRange): Matcher<Collection<T>>Usage Examples:
import io.kotest.matchers.collections.*
val items = listOf("apple", "banana", "cherry")
val empty = emptyList<String>()
val numbers = setOf(1, 2, 3, 4, 5)
// Size validation
items.shouldHaveSize(3)
empty.shouldBeEmpty()
numbers.shouldHaveSizeBetween(3..10)
numbers.shouldHaveAtLeastSize(3)
// Containment validation
items.shouldContainAll("apple", "banana")
items.shouldContainAnyOf("apple", "grape", "orange")
numbers.shouldContainExactly(1, 2, 3, 4, 5)
// Using matcher syntax
items should haveSize(3)
numbers should containAll(listOf(1, 2, 3))Single Element and Uniqueness
Matchers for collections with specific element count and uniqueness constraints.
/**
* Assert that collection contains exactly one element
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldBeSingleton(): Collection<T>
/**
* Assert that collection is not a singleton
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldNotBeSingleton(): Collection<T>
/**
* Assert that collection contains exactly one element matching predicate
* @param predicate Function to test elements
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldBeSingleton(predicate: (T) -> Boolean): Collection<T>
/**
* Assert that collection has unique elements (no duplicates)
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldBeUnique(): Collection<T>
/**
* Assert that collection has duplicate elements
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldHaveDuplicates(): Collection<T>
/**
* Assert that collection should not have duplicates
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldNotHaveDuplicates(): Collection<T>
/**
* Create matcher for singleton validation
* @return Matcher that passes for single-element collections
*/
fun <T> beSingleton(): Matcher<Collection<T>>
/**
* Create matcher for singleton with predicate validation
* @param predicate Function to test the single element
* @return Matcher that passes for single-element collections matching predicate
*/
fun <T> beSingleton(predicate: (T) -> Boolean): Matcher<Collection<T>>
/**
* Create matcher for uniqueness validation
* @return Matcher that passes for collections with all unique elements
*/
fun <T> beUnique(): Matcher<Collection<T>>
/**
* Create matcher for duplicate presence validation
* @return Matcher that passes for collections containing duplicates
*/
fun <T> haveDuplicates(): Matcher<Collection<T>>Ordering and Sorting
Matchers for validating element order and sorting properties.
/**
* Assert that collection is sorted in natural ascending order
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> Collection<T>.shouldBeSorted(): Collection<T>
/**
* Assert that collection is not sorted in natural order
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> Collection<T>.shouldNotBeSorted(): Collection<T>
/**
* Assert that collection is sorted using custom comparator
* @param comparator Custom comparison function
* @return The original Collection for chaining
*/
fun <T> Collection<T>.shouldBeSortedBy(comparator: Comparator<T>): Collection<T>
/**
* Assert that collection is sorted in descending order
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> Collection<T>.shouldBeSortedDescending(): Collection<T>
/**
* Assert that collection is monotonically increasing
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> List<T>.shouldBeMonotonicallyIncreasing(): List<T>
/**
* Assert that collection is monotonically decreasing
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> List<T>.shouldBeMonotonicallyDecreasing(): List<T>
/**
* Assert that collection is strictly increasing (no equal adjacent elements)
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> List<T>.shouldBeStrictlyIncreasing(): List<T>
/**
* Assert that collection is strictly decreasing (no equal adjacent elements)
* @return The original Collection for chaining
*/
fun <T : Comparable<T>> List<T>.shouldBeStrictlyDecreasing(): List<T>
/**
* Create matcher for sorted validation
* @return Matcher that passes for naturally sorted collections
*/
fun <T : Comparable<T>> beSorted(): Matcher<Collection<T>>
/**
* Create matcher for custom sort validation
* @param comparator Custom comparison function
* @return Matcher that passes for collections sorted by comparator
*/
fun <T> beSortedBy(comparator: Comparator<T>): Matcher<Collection<T>>
/**
* Create matcher for monotonic increasing validation
* @return Matcher that passes for monotonically increasing sequences
*/
fun <T : Comparable<T>> beMonotonicallyIncreasing(): Matcher<List<T>>
/**
* Create matcher for strict increasing validation
* @return Matcher that passes for strictly increasing sequences
*/
fun <T : Comparable<T>> beStrictlyIncreasing(): Matcher<List<T>>Usage Examples:
import io.kotest.matchers.collections.*
val sortedNumbers = listOf(1, 2, 3, 4, 5)
val reversedNumbers = listOf(5, 4, 3, 2, 1)
val names = listOf("Alice", "Bob", "Charlie")
val duplicates = listOf(1, 2, 2, 3, 3, 3)
// Sorting validation
sortedNumbers.shouldBeSorted()
reversedNumbers.shouldBeSortedDescending()
sortedNumbers.shouldBeStrictlyIncreasing()
// Uniqueness validation
sortedNumbers.shouldBeUnique()
duplicates.shouldHaveDuplicates()
// Single element validation
listOf("only").shouldBeSingleton()
// Using matcher syntax
sortedNumbers should beSorted()
names should beSortedBy(String.CASE_INSENSITIVE_ORDER)Map-Specific Matchers
Special matchers for Map collections including key/value operations.
/**
* Assert that map contains specific key
* @param key The key that should be present
* @return The original Map for chaining
*/
fun <K, V> Map<K, V>.shouldContainKey(key: K): Map<K, V>
/**
* Assert that map does not contain specific key
* @param key The key that should not be present
* @return The original Map for chaining
*/
fun <K, V> Map<K, V>.shouldNotContainKey(key: K): Map<K, V>
/**
* Assert that map contains specific value
* @param value The value that should be present
* @return The original Map for chaining
*/
fun <K, V> Map<K, V>.shouldContainValue(value: V): Map<K, V>
/**
* Assert that map does not contain specific value
* @param value The value that should not be present
* @return The original Map for chaining
*/
fun <K, V> Map<K, V>.shouldNotContainValue(value: V): Map<K, V>
/**
* Assert that map contains specific key-value pair
* @param key The expected key
* @param value The expected value for that key
* @return The original Map for chaining
*/
fun <K, V> Map<K, V>.shouldContain(key: K, value: V): Map<K, V>
/**
* Assert that map does not contain specific key-value pair
* @param key The key to check
* @param value The value that should not be associated with key
* @return The original Map for chaining
*/
fun <K, V> Map<K, V>.shouldNotContain(key: K, value: V): Map<K, V>
/**
* Create matcher for key presence validation
* @param key The key to check for
* @return Matcher that passes when map contains the key
*/
fun <K, V> containKey(key: K): Matcher<Map<K, V>>
/**
* Create matcher for value presence validation
* @param value The value to check for
* @return Matcher that passes when map contains the value
*/
fun <K, V> containValue(value: V): Matcher<Map<K, V>>
/**
* Create matcher for key-value pair validation
* @param key The expected key
* @param value The expected value
* @return Matcher that passes when map contains the key-value pair
*/
fun <K, V> contain(key: K, value: V): Matcher<Map<K, V>>Usage Examples:
import io.kotest.matchers.maps.*
val userMap = mapOf(
"alice" to 25,
"bob" to 30,
"charlie" to 35
)
// Map-specific validations
userMap.shouldContainKey("alice")
userMap.shouldContainValue(30)
userMap.shouldContain("bob", 30)
// Size validation works with maps too
userMap.shouldHaveSize(3)
// Using matcher syntax
userMap should containKey("charlie")
userMap should contain("alice", 25)Error Handling
Collection matchers provide detailed error messages that help identify specific assertion failures:
- Size failures: Show expected vs actual size with element preview
- Element failures: Highlight which elements are missing, unexpected, or in wrong positions
- Ordering failures: Show the sequence where ordering requirements are violated
- Predicate failures: Indicate which elements failed predicate tests with context
- Containment failures: List missing or unexpected elements with clear categorization
- Pattern failures: Show exactly where pattern matching breaks down with element details
All collection matchers handle empty collections, null elements, and edge cases appropriately while maintaining type safety and providing meaningful error context.
Install with Tessl CLI
npx tessl i tessl/maven-io-kotest--kotest-assertions-core-jvm