tessl/maven-io-kotest--kotest-assertions-core-jvm
Core assertion and matcher library for Kotest testing framework
—
Pending
strings.mddocs/
String Matchers
Comprehensive string validation including content checks, pattern matching, case sensitivity, length validation, and multi-line operations for robust text assertion capabilities.
Capabilities
Content Validation
Matchers for validating string content and character composition.
/**
* Assert that string contains only digits (0-9)
* @return The original String value for chaining
*/
fun String?.shouldContainOnlyDigits(): String?
/**
* Assert that string does not contain only digits
* @return The original String value for chaining
*/
fun String?.shouldNotContainOnlyDigits(): String?
/**
* Assert that string contains at least one digit
* @return The original String value for chaining
*/
fun String?.shouldContainADigit(): String?
/**
* Assert that string contains no digits
* @return The original String value for chaining
*/
fun String?.shouldNotContainADigit(): String?
/**
* Assert that substring appears exactly once in the string
* @param substr The substring to search for
* @return The original String value for chaining
*/
infix fun String?.shouldContainOnlyOnce(substr: String): String?
/**
* Assert that substring does not appear exactly once
* @param substr The substring to search for
* @return The original String value for chaining
*/
infix fun String?.shouldNotContainOnlyOnce(substr: String): String?
/**
* Create matcher for strings containing only digits
* @return Matcher that passes for digit-only strings
*/
fun containOnlyDigits(): Matcher<String?>
/**
* Create matcher for strings containing at least one digit
* @return Matcher that passes for strings with digits
*/
fun containADigit(): Matcher<String?>
/**
* Create matcher for substring occurrence validation
* @param substring The substring to check occurrence count
* @return Matcher that passes when substring appears exactly once
*/
fun containOnlyOnce(substring: String): Matcher<String?>Usage Examples:
import io.kotest.matchers.string.*
val phoneNumber = "1234567890"
val mixedText = "abc123def"
val uniqueId = "user_123_admin"
// Content validation
phoneNumber.shouldContainOnlyDigits()
mixedText.shouldContainADigit()
uniqueId shouldContainOnlyOnce "123"
// Using matcher syntax
phoneNumber should containOnlyDigits()
mixedText should containADigit()Emptiness and Whitespace
Matchers for checking string emptiness and blank states.
/**
* Assert that string is empty (length == 0)
* @return The original String value for chaining
*/
fun String?.shouldBeEmpty(): String?
/**
* Assert that string is not empty
* @return The original String value for chaining
*/
fun String?.shouldNotBeEmpty(): String?
/**
* Assert that string is blank (empty or contains only whitespace)
* @return The original String value for chaining
*/
fun String?.shouldBeBlank(): String?
/**
* Assert that string is not blank
* @return The original String value for chaining
*/
fun String?.shouldNotBeBlank(): String?
/**
* Create matcher for empty string validation
* @return Matcher that passes for empty strings
*/
fun beEmpty(): Matcher<String?>
/**
* Create matcher for blank string validation
* @return Matcher that passes for blank strings (empty or whitespace)
*/
fun beBlank(): Matcher<String?>Usage Examples:
import io.kotest.matchers.string.*
val empty = ""
val whitespace = " \t\n"
val content = "hello"
empty.shouldBeEmpty()
whitespace.shouldBeBlank()
content.shouldNotBeEmpty()
content.shouldNotBeBlank()Length Validation
Matchers for string length assertions and ranges.
/**
* Assert that string has exact length
* @param length The expected length
* @return The original String value for chaining
*/
fun String?.shouldHaveLength(length: Int): String?
/**
* Assert that string does not have specified length
* @param length The length that should not match
* @return The original String value for chaining
*/
fun String?.shouldNotHaveLength(length: Int): String?
/**
* Assert that string length is within specified range
* @param range IntRange for valid length values
* @return The original String value for chaining
*/
infix fun String?.shouldHaveLengthBetween(range: IntRange): String?
/**
* Assert that string length is between two values (inclusive)
* @param min Minimum length (inclusive)
* @param max Maximum length (inclusive)
* @return The original String value for chaining
*/
fun String?.shouldHaveLengthBetween(min: Int, max: Int): String?
/**
* Assert that string length is at least specified value
* @param length Minimum required length
* @return The original String value for chaining
*/
fun String?.shouldHaveMinLength(length: Int): String?
/**
* Assert that string length is at most specified value
* @param length Maximum allowed length
* @return The original String value for chaining
*/
fun String?.shouldHaveMaxLength(length: Int): String?
/**
* Create matcher for exact length validation
* @param length The expected length
* @return Matcher that passes for strings of exact length
*/
fun haveLength(length: Int): Matcher<String?>
/**
* Create matcher for length range validation
* @param range IntRange for valid length values
* @return Matcher that passes for strings within length range
*/
fun haveLengthBetween(range: IntRange): Matcher<String?>
/**
* Create matcher for minimum length validation
* @param length Minimum required length
* @return Matcher that passes for strings with at least specified length
*/
fun haveMinLength(length: Int): Matcher<String?>
/**
* Create matcher for maximum length validation
* @param length Maximum allowed length
* @return Matcher that passes for strings with at most specified length
*/
fun haveMaxLength(length: Int): Matcher<String?>Usage Examples:
import io.kotest.matchers.string.*
val password = "secret123"
val username = "user"
password.shouldHaveLength(9)
username shouldHaveLengthBetween 3..20
password.shouldHaveMinLength(8)
username.shouldHaveMaxLength(50)
// Using matcher syntax
password should haveLength(9)
username should haveLengthBetween(3..20)Case Sensitivity
Matchers for uppercase and lowercase validation.
/**
* Assert that string is all uppercase
* @return The original String value for chaining
*/
fun String?.shouldBeUpperCase(): String?
/**
* Assert that string is not all uppercase
* @return The original String value for chaining
*/
fun String?.shouldNotBeUpperCase(): String?
/**
* Assert that string is all lowercase
* @return The original String value for chaining
*/
fun String?.shouldBeLowerCase(): String?
/**
* Assert that string is not all lowercase
* @return The original String value for chaining
*/
fun String?.shouldNotBeLowerCase(): String?
/**
* Create matcher for uppercase validation
* @return Matcher that passes for uppercase strings
*/
fun beUpperCase(): Matcher<String?>
/**
* Create matcher for lowercase validation
* @return Matcher that passes for lowercase strings
*/
fun beLowerCase(): Matcher<String?>Prefix and Suffix
Matchers for string start and end validation.
/**
* Assert that string starts with specified prefix
* @param prefix The expected prefix
* @return The original String value for chaining
*/
fun String?.shouldStartWith(prefix: String): String?
/**
* Assert that string does not start with specified prefix
* @param prefix The prefix that should not match
* @return The original String value for chaining
*/
fun String?.shouldNotStartWith(prefix: String): String?
/**
* Assert that string ends with specified suffix
* @param suffix The expected suffix
* @return The original String value for chaining
*/
fun String?.shouldEndWith(suffix: String): String?
/**
* Assert that string does not end with specified suffix
* @param suffix The suffix that should not match
* @return The original String value for chaining
*/
fun String?.shouldNotEndWith(suffix: String): String?
/**
* Assert that string starts with prefix (case-insensitive)
* @param prefix The expected prefix
* @return The original String value for chaining
*/
fun String?.shouldStartWithIgnoringCase(prefix: String): String?
/**
* Assert that string ends with suffix (case-insensitive)
* @param suffix The expected suffix
* @return The original String value for chaining
*/
fun String?.shouldEndWithIgnoringCase(suffix: String): String?
/**
* Create matcher for prefix validation
* @param prefix The expected prefix
* @return Matcher that passes for strings starting with prefix
*/
fun startWith(prefix: String): Matcher<String?>
/**
* Create matcher for suffix validation
* @param suffix The expected suffix
* @return Matcher that passes for strings ending with suffix
*/
fun endWith(suffix: String): Matcher<String?>
/**
* Create matcher for case-insensitive prefix validation
* @param prefix The expected prefix
* @return Matcher that passes for strings starting with prefix (ignoring case)
*/
fun startWithIgnoringCase(prefix: String): Matcher<String?>
/**
* Create matcher for case-insensitive suffix validation
* @param suffix The expected suffix
* @return Matcher that passes for strings ending with suffix (ignoring case)
*/
fun endWithIgnoringCase(suffix: String): Matcher<String?>Usage Examples:
import io.kotest.matchers.string.*
val url = "https://example.com"
val filename = "report.PDF"
// Case-sensitive prefix/suffix
url.shouldStartWith("https://")
filename.shouldEndWith("PDF")
// Case-insensitive matching
filename.shouldEndWithIgnoringCase("pdf")
// Using matcher syntax
url should startWith("https://")
filename should endWithIgnoringCase("pdf")Containment and Substring
Matchers for substring presence and containment checks.
/**
* Assert that string contains specified substring
* @param substr The substring to search for
* @return The original String value for chaining
*/
infix fun String?.shouldContain(substr: String): String?
/**
* Assert that string does not contain specified substring
* @param substr The substring that should not be present
* @return The original String value for chaining
*/
infix fun String?.shouldNotContain(substr: String): String?
/**
* Assert that string contains substring (case-insensitive)
* @param substr The substring to search for
* @return The original String value for chaining
*/
fun String?.shouldContainIgnoringCase(substr: String): String?
/**
* Assert that string contains all specified substrings
* @param substrings Variable number of substrings to check
* @return The original String value for chaining
*/
fun String?.shouldContainAll(vararg substrings: String): String?
/**
* Assert that string contains any of the specified substrings
* @param substrings Variable number of substrings to check
* @return The original String value for chaining
*/
fun String?.shouldContainAnyOf(vararg substrings: String): String?
/**
* Create matcher for substring containment
* @param substr The substring to search for
* @return Matcher that passes for strings containing the substring
*/
fun contain(substr: String): Matcher<String?>
/**
* Create matcher for case-insensitive substring containment
* @param substr The substring to search for
* @return Matcher that passes for strings containing the substring (ignoring case)
*/
fun containIgnoringCase(substr: String): Matcher<String?>
/**
* Create matcher for multiple substring containment
* @param substrings Variable number of required substrings
* @return Matcher that passes when all substrings are present
*/
fun containAll(vararg substrings: String): Matcher<String?>
/**
* Create matcher for any substring containment
* @param substrings Variable number of possible substrings
* @return Matcher that passes when any substring is present
*/
fun containAnyOf(vararg substrings: String): Matcher<String?>Regular Expression Matching
Matchers for pattern matching using regular expressions.
/**
* Assert that string matches the regular expression
* @param regex The regular expression pattern
* @return The original String value for chaining
*/
fun String?.shouldMatch(regex: Regex): String?
/**
* Assert that string matches the regular expression pattern
* @param pattern The regex pattern as string
* @return The original String value for chaining
*/
fun String?.shouldMatch(pattern: String): String?
/**
* Assert that string does not match the regular expression
* @param regex The regular expression pattern
* @return The original String value for chaining
*/
fun String?.shouldNotMatch(regex: Regex): String?
/**
* Assert that string fully matches the regular expression
* @param regex The regular expression pattern
* @return The original String value for chaining
*/
fun String?.shouldFullyMatch(regex: Regex): String?
/**
* Create matcher for regex pattern matching
* @param regex The regular expression to match against
* @return Matcher that passes for strings matching the pattern
*/
fun match(regex: Regex): Matcher<String?>
/**
* Create matcher for regex pattern string matching
* @param pattern The regex pattern as string
* @return Matcher that passes for strings matching the pattern
*/
fun match(pattern: String): Matcher<String?>
/**
* Create matcher for full regex matching (entire string)
* @param regex The regular expression for full matching
* @return Matcher that passes when entire string matches pattern
*/
fun fullyMatch(regex: Regex): Matcher<String?>Usage Examples:
import io.kotest.matchers.string.*
val email = "user@example.com"
val phoneNumber = "+1-555-123-4567"
val text = "Hello World 123"
// Regex matching
val emailRegex = """^[\w\.-]+@[\w\.-]+\.\w+$""".toRegex()
email.shouldMatch(emailRegex)
// Pattern string matching
phoneNumber.shouldMatch("""\+\d{1}-\d{3}-\d{3}-\d{4}""")
// Full match validation
text.shouldFullyMatch("""Hello World \d+""".toRegex())
// Using matcher syntax
email should match(emailRegex)
text should fullyMatch("""Hello World \d+""".toRegex())Multi-line String Operations
Matchers for handling multi-line strings and line-based operations.
/**
* Assert that string has exactly specified number of lines
* @param count The expected line count
* @return The original String value for chaining
*/
fun String?.shouldHaveLineCount(count: Int): String?
/**
* Assert that string does not have specified line count
* @param count The line count that should not match
* @return The original String value for chaining
*/
fun String?.shouldNotHaveLineCount(count: Int): String?
/**
* Assert that string is a single line (no line breaks)
* @return The original String value for chaining
*/
fun String?.shouldBeSingleLine(): String?
/**
* Assert that string contains multiple lines
* @return The original String value for chaining
*/
fun String?.shouldBeMultiLine(): String?
/**
* Create matcher for line count validation
* @param count The expected number of lines
* @return Matcher that passes for strings with exact line count
*/
fun haveLineCount(count: Int): Matcher<String?>
/**
* Create matcher for single line validation
* @return Matcher that passes for single-line strings
*/
fun beSingleLine(): Matcher<String?>
/**
* Create matcher for multi-line validation
* @return Matcher that passes for multi-line strings
*/
fun beMultiLine(): Matcher<String?>Equality with Variations
Enhanced equality matchers with case and whitespace handling.
/**
* Assert that string equals another string ignoring case
* @param other The expected string value
* @return The original String value for chaining
*/
fun String?.shouldEqualIgnoringCase(other: String): String?
/**
* Assert that string equals another string ignoring whitespace
* @param other The expected string value
* @return The original String value for chaining
*/
fun String?.shouldEqualIgnoringWhitespace(other: String): String?
/**
* Assert that string equals another string ignoring both case and whitespace
* @param other The expected string value
* @return The original String value for chaining
*/
fun String?.shouldEqualIgnoringCaseAndWhitespace(other: String): String?
/**
* Create matcher for case-insensitive equality
* @param expected The expected string value
* @return Matcher that passes for case-insensitive equality
*/
fun equalIgnoringCase(expected: String): Matcher<String?>
/**
* Create matcher for whitespace-insensitive equality
* @param expected The expected string value
* @return Matcher that passes ignoring whitespace differences
*/
fun equalIgnoringWhitespace(expected: String): Matcher<String?>
/**
* Create matcher for case and whitespace insensitive equality
* @param expected The expected string value
* @return Matcher that passes ignoring case and whitespace differences
*/
fun equalIgnoringCaseAndWhitespace(expected: String): Matcher<String?>Usage Examples:
import io.kotest.matchers.string.*
val text1 = "Hello World"
val text2 = "HELLO WORLD"
val text3 = "Hello\n\tWorld "
// Case-insensitive equality
text1.shouldEqualIgnoringCase(text2)
// Whitespace-insensitive equality
text1.shouldEqualIgnoringWhitespace(text3)
// Combined case and whitespace insensitive
text2.shouldEqualIgnoringCaseAndWhitespace(text3)
// Multi-line validation
val multilineText = """
Line 1
Line 2
Line 3
""".trimIndent()
multilineText.shouldHaveLineCount(3)
multilineText.shouldBeMultiLine()Error Handling
String matchers provide comprehensive error messages for assertion failures:
- Content failures: Show expected vs actual content with highlighting
- Length failures: Display expected vs actual length with clear bounds
- Case failures: Indicate case sensitivity requirements and actual case
- Regex failures: Show the pattern and explain why matching failed
- Substring failures: Highlight missing or unexpected substrings with position information
- Multi-line failures: Show line-by-line differences for complex text comparisons
All string matchers handle null values appropriately and provide null-safe assertions with clear error messages when null handling is incorrect.
Install with Tessl CLI
npx tessl i tessl/maven-io-kotest--kotest-assertions-core-jvm