CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-jetbrains-kotlin--kotlin-test-common

Common test assertions and utilities for Kotlin multiplatform projects

—

Pending
Overview
Eval results
Files

collection-assertions.mddocs/

Collection and Array Assertions

Content equality and membership testing for collections, arrays, ranges, maps, and strings with comprehensive support for all Kotlin types including primitives and unsigned types. These functions provide structural comparison and containment testing essential for validating data structures in tests.

Capabilities

assertContains - Collections

Tests whether collections and sequences contain specific elements.

/**
 * Asserts that the iterable contains the specified element.
 * @param iterable The iterable collection to search
 * @param element The element to find
 * @param message Optional message to show if assertion fails
 * @since Kotlin 1.5
 */
fun <T> assertContains(iterable: Iterable<T>, element: T, message: String? = null)

/**
 * Asserts that the sequence contains the specified element.
 * @param sequence The sequence to search
 * @param element The element to find
 * @param message Optional message to show if assertion fails
 * @since Kotlin 1.5
 */
fun <T> assertContains(sequence: Sequence<T>, element: T, message: String? = null)

Usage Examples:

import kotlin.test.assertContains

@Test
fun testCollectionContains() {
    // List containment
    val numbers = listOf(1, 2, 3, 4, 5)
    assertContains(numbers, 3, "List should contain 3")
    
    // Set containment
    val colors = setOf("red", "green", "blue")
    assertContains(colors, "red", "Set should contain red")
    
    // Sequence containment
    val sequence = sequenceOf("a", "b", "c")
    assertContains(sequence, "b", "Sequence should contain 'b'")
    
    // Custom objects
    val users = listOf(User("Alice"), User("Bob"), User("Charlie"))
    assertContains(users, User("Bob"), "Users should contain Bob")
}

assertContains - Arrays

Tests whether arrays contain specific elements, supporting all primitive and reference types.

/**
 * Asserts that the array contains the specified element.
 * @since Kotlin 1.5
 */
fun <T> assertContains(array: Array<T>, element: T, message: String? = null)

/**
 * Array contains functions for primitive types.
 * @since Kotlin 1.5
 */
fun assertContains(array: ByteArray, element: Byte, message: String? = null)
fun assertContains(array: ShortArray, element: Short, message: String? = null)
fun assertContains(array: IntArray, element: Int, message: String? = null)
fun assertContains(array: LongArray, element: Long, message: String? = null)
fun assertContains(array: BooleanArray, element: Boolean, message: String? = null)
fun assertContains(array: CharArray, element: Char, message: String? = null)

/**
 * Unsigned array containment (experimental)
 */
fun assertContains(array: UByteArray, element: UByte, message: String? = null)
fun assertContains(array: UShortArray, element: UShort, message: String? = null)
fun assertContains(array: UIntArray, element: UInt, message: String? = null)
fun assertContains(array: ULongArray, element: ULong, message: String? = null)

Usage Examples:

import kotlin.test.assertContains

@Test
fun testArrayContains() {
    // Generic array
    val stringArray = arrayOf("hello", "world", "kotlin")
    assertContains(stringArray, "kotlin", "Array should contain 'kotlin'")
    
    // Primitive arrays
    val intArray = intArrayOf(10, 20, 30, 40)
    assertContains(intArray, 30, "Int array should contain 30")
    
    val charArray = charArrayOf('a', 'b', 'c')
    assertContains(charArray, 'b', "Char array should contain 'b'")
    
    val booleanArray = booleanArrayOf(true, false, true)
    assertContains(booleanArray, false, "Boolean array should contain false")
    
    // Unsigned arrays (experimental)
    val uintArray = uintArrayOf(1u, 2u, 3u)
    assertContains(uintArray, 2u, "UInt array should contain 2u")
}

assertContains - Ranges

Tests whether ranges contain specific values with support for numeric and character ranges.

/**
 * Range containment testing
 */
fun assertContains(range: IntRange, value: Int, message: String? = null)
fun assertContains(range: LongRange, value: Long, message: String? = null)
fun assertContains(range: CharRange, value: Char, message: String? = null)
fun <T : Comparable<T>> assertContains(range: ClosedRange<T>, value: T, message: String? = null)

/**
 * Asserts that the range contains the specified value.
 * @since Kotlin 2.2
 */
fun <T : Comparable<T>> assertContains(range: OpenEndRange<T>, value: T, message: String? = null)

/**
 * Unsigned range containment
 */
fun assertContains(range: UIntRange, value: UInt, message: String? = null)
fun assertContains(range: ULongRange, value: ULong, message: String? = null)

Usage Examples:

import kotlin.test.assertContains

@Test
fun testRangeContains() {
    // Numeric ranges
    val range1to10 = 1..10
    assertContains(range1to10, 5, "Range 1..10 should contain 5")
    
    val longRange = 100L..200L
    assertContains(longRange, 150L, "Long range should contain 150L")
    
    // Character ranges
    val letterRange = 'a'..'z'
    assertContains(letterRange, 'm', "Letter range should contain 'm'")
    
    // Custom comparable types
    val dateRange = LocalDate.of(2023, 1, 1)..LocalDate.of(2023, 12, 31)
    assertContains(dateRange, LocalDate.of(2023, 6, 15), "Date range should contain mid-year date")
    
    // Unsigned ranges
    val uintRange = 10u..20u
    assertContains(uintRange, 15u, "UInt range should contain 15u")
}

assertContains - Maps and Strings

Tests whether maps contain specific keys and strings contain substrings or patterns.

/**
 * Map key containment
 */
fun <K, V> assertContains(map: Map<K, V>, key: K, message: String? = null)

/**
 * String/character sequence containment
 */
fun assertContains(charSequence: CharSequence, char: Char, ignoreCase: Boolean = false, message: String? = null)
fun assertContains(charSequence: CharSequence, other: CharSequence, ignoreCase: Boolean = false, message: String? = null)
fun assertContains(charSequence: CharSequence, regex: Regex, message: String? = null)

Usage Examples:

import kotlin.test.assertContains

@Test
fun testMapAndStringContains() {
    // Map key containment
    val config = mapOf("host" to "localhost", "port" to 8080, "ssl" to true)
    assertContains(config, "port", "Config should contain port key")
    
    // String character containment
    val text = "Hello, World!"
    assertContains(text, 'W', false, "Text should contain 'W'")
    assertContains(text, 'w', true, "Text should contain 'w' (case insensitive)")
    
    // Substring containment
    assertContains(text, "World", false, "Text should contain 'World'")
    assertContains(text, "hello", true, "Text should contain 'hello' (case insensitive)")
    
    // Regex pattern matching
    val email = "user@example.com"
    val emailPattern = Regex("""[\w._%+-]+@[\w.-]+\.[A-Za-z]{2,}""")
    assertContains(email, emailPattern, "Email should match pattern")
    
    // Phone number validation
    val phone = "+1-555-123-4567"
    val phonePattern = Regex("""\+\d{1,3}-\d{3}-\d{3}-\d{4}""")
    assertContains(phone, phonePattern, "Phone should match international format")
}

assertContentEquals - Collections

Compares the structural content of collections and sequences for equality.

/**
 * Collection content equality testing
 * @since Kotlin 1.5
 */
fun <T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null)

/**
 * Sequence content equality testing
 * @since Kotlin 1.5
 */
fun <T> assertContentEquals(expected: Sequence<T>?, actual: Sequence<T>?, message: String? = null)

/**
 * Set content equality (deprecated - use assertEquals for sets)
 */
@Deprecated("'assertContentEquals' for Set arguments is ambiguous. Use 'assertEquals' to compare content with the unordered set equality, or cast one of arguments to Iterable to compare the set elements in order of iteration.", level = DeprecationLevel.ERROR, replaceWith = ReplaceWith("assertContentEquals(expected, actual?.asIterable(), message)"))
fun <T> assertContentEquals(expected: Set<T>?, actual: Set<T>?, message: String? = null)

Usage Examples:

import kotlin.test.assertContentEquals

@Test
fun testCollectionContentEquals() {
    // List content equality (order matters)
    val expected = listOf(1, 2, 3, 4)
    val actual = mutableListOf(1, 2, 3, 4)
    assertContentEquals(expected, actual, "Lists should have same content")
    
    // Different collection types with same content
    val originalList = listOf("a", "b", "c")
    val arrayList = ArrayList(originalList)
    assertContentEquals(originalList, arrayList, "Different list implementations should be equal")
    
    // Sequence content equality
    val sequence1 = sequenceOf(10, 20, 30)
    val sequence2 = listOf(10, 20, 30).asSequence()
    assertContentEquals(sequence1, sequence2, "Sequences should have same content")
    
    // Null handling
    val nullList: List<String>? = null
    val anotherNullList: List<String>? = null
    assertContentEquals(nullList, anotherNullList, "Both null lists should be equal")
}

assertContentEquals - Arrays

Compares the structural content of arrays for equality, supporting all array types.

/**
 * Array content equality testing
 */
fun <T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null)
fun assertContentEquals(expected: ByteArray?, actual: ByteArray?, message: String? = null)
fun assertContentEquals(expected: ShortArray?, actual: ShortArray?, message: String? = null)
fun assertContentEquals(expected: IntArray?, actual: IntArray?, message: String? = null)
fun assertContentEquals(expected: LongArray?, actual: LongArray?, message: String? = null)
fun assertContentEquals(expected: FloatArray?, actual: FloatArray?, message: String? = null)
fun assertContentEquals(expected: DoubleArray?, actual: DoubleArray?, message: String? = null)
fun assertContentEquals(expected: BooleanArray?, actual: BooleanArray?, message: String? = null)
fun assertContentEquals(expected: CharArray?, actual: CharArray?, message: String? = null)

/**
 * Unsigned array content equality (experimental)
 */
fun assertContentEquals(expected: UByteArray?, actual: UByteArray?, message: String? = null)
fun assertContentEquals(expected: UShortArray?, actual: UShortArray?, message: String? = null)
fun assertContentEquals(expected: UIntArray?, actual: UIntArray?, message: String? = null)
fun assertContentEquals(expected: ULongArray?, actual: ULongArray?, message: String? = null)

Usage Examples:

import kotlin.test.assertContentEquals

@Test
fun testArrayContentEquals() {
    // Generic arrays
    val expected = arrayOf("apple", "banana", "cherry")
    val actual = arrayOf("apple", "banana", "cherry")
    assertContentEquals(expected, actual, "String arrays should have same content")
    
    // Primitive arrays
    val expectedInts = intArrayOf(1, 2, 3, 4, 5)
    val aktualInts = intArrayOf(1, 2, 3, 4, 5)
    assertContentEquals(expectedInts, aktualInts, "Int arrays should have same content")
    
    val expectedChars = charArrayOf('h', 'e', 'l', 'l', 'o')
    val actualChars = "hello".toCharArray()
    assertContentEquals(expectedChars, actualChars, "Char arrays should have same content")
    
    // Floating point arrays
    val expectedFloats = floatArrayOf(1.0f, 2.5f, 3.7f)
    val actualFloats = floatArrayOf(1.0f, 2.5f, 3.7f)
    assertContentEquals(expectedFloats, actualFloats, "Float arrays should have same content")
    
    // Unsigned arrays
    val expectedUInts = uintArrayOf(1u, 2u, 3u)
    val actualUInts = uintArrayOf(1u, 2u, 3u)
    assertContentEquals(expectedUInts, actualUInts, "UInt arrays should have same content")
    
    // Null arrays
    val nullArray: IntArray? = null
    val anotherNullArray: IntArray? = null
    assertContentEquals(nullArray, anotherNullArray, "Both null arrays should be equal")
}

Error Handling

Collection and array assertion functions will throw an AssertionError when conditions fail:

  • assertContains: Throws when element/key/pattern is not found in the collection/array/range/map/string
  • assertContentEquals: Throws when collections/arrays have different content or structure

Error messages provide detailed information about the mismatch:

// This will throw: AssertionError: Expected the collection to contain <5>, but it doesn't: <[1, 2, 3, 4]>
assertContains(listOf(1, 2, 3, 4), 5)

// This will throw: AssertionError: Expected <[1, 2, 3]>, actual <[1, 2, 3, 4]>
assertContentEquals(listOf(1, 2, 3), listOf(1, 2, 3, 4))

Performance Considerations

  • Collection containment: Uses the collection's native contains() method for optimal performance
  • Array containment: Performs linear search through array elements
  • Content comparison: Compares elements sequentially, stopping at first difference
  • Sequence operations: May consume the entire sequence during comparison
  • Regex matching: Pattern compilation and matching can be expensive for complex patterns

Install with Tessl CLI

npx tessl i tessl/maven-org-jetbrains-kotlin--kotlin-test-common

docs

boolean-assertions.md

collection-assertions.md

equality-assertions.md

exception-testing.md

framework-integration.md

index.md

test-annotations.md

test-utilities.md

type-null-assertions.md

tile.json