tessl/maven-io-kotest--kotest-assertions-core-jvm
Core assertion and matcher library for Kotest testing framework
—
Pending
filesystem.mddocs/
File System Matchers
JVM file system operations including existence checks, permissions validation, content verification, size comparisons, and directory structure analysis for comprehensive file-based testing.
Capabilities
Existence and Type Validation
Matchers for validating file and directory existence and type classification.
/**
* Assert that file or directory exists on the file system
* @return The original File for chaining
*/
fun File.shouldExist(): File
/**
* Assert that file or directory does not exist
* @return The original File for chaining
*/
fun File.shouldNotExist(): File
/**
* Assert that path represents a directory
* @return The original File for chaining
*/
fun File.shouldBeADirectory(): File
/**
* Assert that path does not represent a directory
* @return The original File for chaining
*/
fun File.shouldNotBeADirectory(): File
/**
* Assert that path represents a regular file
* @return The original File for chaining
*/
fun File.shouldBeAFile(): File
/**
* Assert that path does not represent a regular file
* @return The original File for chaining
*/
fun File.shouldNotBeAFile(): File
/**
* Create matcher for existence validation
* @return Matcher that passes when file exists
*/
fun exist(): Matcher<File>
/**
* Create matcher for directory type validation
* @return Matcher that passes when path is a directory
*/
fun aDirectory(): Matcher<File>
/**
* Create matcher for file type validation
* @return Matcher that passes when path is a regular file
*/
fun aFile(): Matcher<File>Usage Examples:
import io.kotest.matchers.file.*
import java.io.File
val configFile = File("/etc/config.txt")
val dataDirectory = File("/var/data")
val tempFile = File.createTempFile("test", ".tmp")
// Existence validation
configFile.shouldExist()
tempFile.shouldExist()
// Type validation
dataDirectory.shouldBeADirectory()
configFile.shouldBeAFile()
// Using matcher syntax
configFile should exist()
dataDirectory should aDirectory()
tempFile should aFile()Content and Emptiness
Matchers for validating file content, size, and emptiness states.
/**
* Assert that file is empty (size == 0 bytes)
* @return The original File for chaining
*/
fun File.shouldBeEmpty(): File
/**
* Assert that file is not empty (size > 0 bytes)
* @return The original File for chaining
*/
fun File.shouldNotBeEmpty(): File
/**
* Assert that directory is empty (contains no files or subdirectories)
* @return The original File for chaining
*/
fun File.shouldBeEmptyDirectory(): File
/**
* Assert that directory is not empty
* @return The original File for chaining
*/
fun File.shouldNotBeEmptyDirectory(): File
/**
* Assert that directory contains exactly specified number of files
* @param n Expected number of files in directory
* @return The original File for chaining
*/
infix fun File.shouldContainNFiles(n: Int): File
/**
* Assert that directory does not contain specified number of files
* @param n Number of files that should not match
* @return The original File for chaining
*/
infix fun File.shouldNotContainNFiles(n: Int): File
/**
* Assert that directory contains specified file by name
* @param name Name of file that should be present
* @return The original File for chaining
*/
infix fun File.shouldContainFile(name: String): File
/**
* Assert that directory does not contain specified file by name
* @param name Name of file that should not be present
* @return The original File for chaining
*/
infix fun File.shouldNotContainFile(name: String): File
/**
* Create matcher for empty file validation
* @return Matcher that passes for empty files
*/
fun beEmpty(): Matcher<File>
/**
* Create matcher for empty directory validation
* @return Matcher that passes for empty directories
*/
fun beEmptyDirectory(): Matcher<File>
/**
* Create matcher for directory file count validation
* @param n Expected number of files
* @return Matcher that passes when directory contains exactly n files
*/
fun containNFiles(n: Int): Matcher<File>
/**
* Create matcher for file presence in directory
* @param name Name of file to check for
* @return Matcher that passes when directory contains the named file
*/
fun containFile(name: String): Matcher<File>Usage Examples:
import io.kotest.matchers.file.*
import java.io.File
val emptyFile = File("empty.txt").apply { writeText("") }
val dataDir = File("data/")
val configDir = File("config/")
// Emptiness validation
emptyFile.shouldBeEmpty()
dataDir.shouldNotBeEmptyDirectory()
// Directory content validation
configDir shouldContainNFiles 3
configDir shouldContainFile "settings.json"
// Using matcher syntax
emptyFile should beEmpty()
dataDir should containFile("users.db")Size and Comparison
Matchers for file size validation and comparative operations.
/**
* Assert that file has exactly specified size in bytes
* @param size Expected file size in bytes
* @return The original File for chaining
*/
infix fun File.shouldHaveFileSize(size: Long): File
/**
* Assert that file does not have specified size
* @param size Size in bytes that should not match
* @return The original File for chaining
*/
infix fun File.shouldNotHaveFileSize(size: Long): File
/**
* Assert that file is smaller than another file
* @param other File to compare against
* @return The original File for chaining
*/
infix fun File.shouldBeSmaller(other: File): File
/**
* Assert that file is not smaller than another file
* @param other File to compare against
* @return The original File for chaining
*/
infix fun File.shouldNotBeSmaller(other: File): File
/**
* Assert that file is larger than another file
* @param other File to compare against
* @return The original File for chaining
*/
infix fun File.shouldBeLarger(other: File): File
/**
* Assert that file is not larger than another file
* @param other File to compare against
* @return The original File for chaining
*/
infix fun File.shouldNotBeLarger(other: File): File
/**
* Create matcher for exact file size validation
* @param size Expected size in bytes
* @return Matcher that passes for files of exact size
*/
fun haveFileSize(size: Long): Matcher<File>
/**
* Create matcher for file size comparison (smaller)
* @param other File to compare against
* @return Matcher that passes when file is smaller than other
*/
fun beSmaller(other: File): Matcher<File>
/**
* Create matcher for file size comparison (larger)
* @param other File to compare against
* @return Matcher that passes when file is larger than other
*/
fun beLarger(other: File): Matcher<File>Permissions and Properties
Matchers for file permissions, attributes, and system properties.
/**
* Assert that file is readable by current process
* @return The original File for chaining
*/
fun File.shouldBeReadable(): File
/**
* Assert that file is not readable
* @return The original File for chaining
*/
fun File.shouldNotBeReadable(): File
/**
* Assert that file is writable by current process
* @return The original File for chaining
*/
fun File.shouldBeWriteable(): File
/**
* Assert that file is not writable
* @return The original File for chaining
*/
fun File.shouldNotBeWriteable(): File
/**
* Assert that file is executable by current process
* @return The original File for chaining
*/
fun File.shouldBeExecutable(): File
/**
* Assert that file is not executable
* @return The original File for chaining
*/
fun File.shouldNotBeExecutable(): File
/**
* Assert that file is hidden (system attribute)
* @return The original File for chaining
*/
fun File.shouldBeHidden(): File
/**
* Assert that file is not hidden
* @return The original File for chaining
*/
fun File.shouldNotBeHidden(): File
/**
* Assert that path is absolute (not relative)
* @return The original File for chaining
*/
fun File.shouldBeAbsolute(): File
/**
* Assert that path is not absolute (is relative)
* @return The original File for chaining
*/
fun File.shouldNotBeAbsolute(): File
/**
* Assert that path is relative (not absolute)
* @return The original File for chaining
*/
fun File.shouldBeRelative(): File
/**
* Assert that path is not relative (is absolute)
* @return The original File for chaining
*/
fun File.shouldNotBeRelative(): File
/**
* Create matcher for readable permission validation
* @return Matcher that passes for readable files
*/
fun beReadable(): Matcher<File>
/**
* Create matcher for writable permission validation
* @return Matcher that passes for writable files
*/
fun beWriteable(): Matcher<File>
/**
* Create matcher for executable permission validation
* @return Matcher that passes for executable files
*/
fun beExecutable(): Matcher<File>
/**
* Create matcher for hidden attribute validation
* @return Matcher that passes for hidden files
*/
fun beHidden(): Matcher<File>
/**
* Create matcher for absolute path validation
* @return Matcher that passes for absolute paths
*/
fun beAbsolute(): Matcher<File>
/**
* Create matcher for relative path validation
* @return Matcher that passes for relative paths
*/
fun beRelative(): Matcher<File>Usage Examples:
import io.kotest.matchers.file.*
import java.io.File
val executableScript = File("/usr/bin/script.sh")
val configFile = File("config/app.properties")
val logFile = File("/var/log/app.log")
// Permission validation
executableScript.shouldBeReadable()
executableScript.shouldBeExecutable()
logFile.shouldBeWriteable()
// Path type validation
executableScript.shouldBeAbsolute()
configFile.shouldBeRelative()
// Size comparison
val smallFile = File("small.txt")
val largeFile = File("large.txt")
smallFile shouldBeSmaller largeFile
largeFile shouldHaveFileSize 1024L
// Using matcher syntax
executableScript should beExecutable()
configFile should beRelative()Path Type and Links
Advanced matchers for path resolution and symbolic link handling.
/**
* Assert that path is in canonical form (resolved, no symbolic links)
* @return The original File for chaining
*/
fun File.shouldBeCanonical(): File
/**
* Assert that path is not in canonical form
* @return The original File for chaining
*/
fun File.shouldNotBeCanonical(): File
/**
* Assert that file is a symbolic link
* @return The original File for chaining
*/
fun File.shouldBeSymbolicLink(): File
/**
* Assert that file is not a symbolic link
* @return The original File for chaining
*/
fun File.shouldNotBeSymbolicLink(): File
/**
* Create matcher for canonical path validation
* @return Matcher that passes for canonical paths
*/
fun beCanonical(): Matcher<File>
/**
* Create matcher for symbolic link validation
* @return Matcher that passes for symbolic links
*/
fun beSymbolicLink(): Matcher<File>Directory Structure Comparison
Advanced matchers for comparing directory structures and content.
/**
* Assert that directory has same structure as another directory
* Compares file and directory names recursively, ignoring content
* @param file The directory to compare structure against
* @return The original File for chaining
*/
infix fun File.shouldHaveSameStructureAs(file: File): File
/**
* Assert that directory does not have same structure as another
* @param file The directory to compare structure against
* @return The original File for chaining
*/
infix fun File.shouldNotHaveSameStructureAs(file: File): File
/**
* Assert that directory has same structure and content as another directory
* Compares both structure and file content recursively
* @param file The directory to compare against completely
* @return The original File for chaining
*/
infix fun File.shouldHaveSameStructureAndContentAs(file: File): File
/**
* Assert that directory does not have same structure and content
* @param file The directory to compare against
* @return The original File for chaining
*/
infix fun File.shouldNotHaveSameStructureAndContentAs(file: File): File
/**
* Create matcher for directory structure comparison
* @param expected The directory structure to compare against
* @return Matcher that passes when structures match
*/
fun haveSameStructureAs(expected: File): Matcher<File>
/**
* Create matcher for complete directory comparison
* @param expected The directory to compare completely against
* @return Matcher that passes when structure and content match
*/
fun haveSameStructureAndContentAs(expected: File): Matcher<File>Usage Examples:
import io.kotest.matchers.file.*
import java.io.File
val sourceDir = File("src/")
val backupDir = File("backup/")
val templateDir = File("template/")
// Structure comparison
sourceDir shouldHaveSameStructureAs backupDir
// Complete comparison (structure + content)
backupDir shouldHaveSameStructureAndContentAs templateDir
// Path resolution validation
val linkFile = File("/tmp/link")
val canonicalFile = File("/home/user/document.txt")
linkFile.shouldBeSymbolicLink()
canonicalFile.shouldBeCanonical()
// Using matcher syntax
sourceDir should haveSameStructureAs(templateDir)Content-Based Validation
Matchers for validating file content and text-based operations.
/**
* Assert that file contains specified text content
* @param text The text that should be present in the file
* @return The original File for chaining
*/
infix fun File.shouldContainText(text: String): File
/**
* Assert that file does not contain specified text
* @param text The text that should not be present
* @return The original File for chaining
*/
infix fun File.shouldNotContainText(text: String): File
/**
* Assert that file content matches regular expression
* @param regex The pattern to match against file content
* @return The original File for chaining
*/
infix fun File.shouldMatchContent(regex: Regex): File
/**
* Assert that file content does not match regular expression
* @param regex The pattern that should not match
* @return The original File for chaining
*/
infix fun File.shouldNotMatchContent(regex: Regex): File
/**
* Assert that text file has specified number of lines
* @param lines Expected line count
* @return The original File for chaining
*/
infix fun File.shouldHaveLineCount(lines: Int): File
/**
* Create matcher for text content validation
* @param text The expected text content
* @return Matcher that passes when file contains the text
*/
fun containText(text: String): Matcher<File>
/**
* Create matcher for content pattern validation
* @param regex The pattern to match against
* @return Matcher that passes when file content matches pattern
*/
fun matchContent(regex: Regex): Matcher<File>
/**
* Create matcher for line count validation
* @param lines Expected number of lines
* @return Matcher that passes when file has exact line count
*/
fun haveLineCount(lines: Int): Matcher<File>Usage Examples:
import io.kotest.matchers.file.*
import java.io.File
val configFile = File("config.properties")
val logFile = File("application.log")
val csvFile = File("data.csv")
// Content validation
configFile shouldContainText "database.url="
logFile shouldMatchContent """ERROR.*\d{4}-\d{2}-\d{2}""".toRegex()
csvFile shouldHaveLineCount 100
// Using matcher syntax
configFile should containText("server.port=8080")
logFile should matchContent("""INFO.*started""".toRegex())Error Handling
File system matchers provide comprehensive error information for assertion failures:
- Existence failures: Clear indication of which files/directories don't exist with path details
- Permission failures: Specific information about which permissions are missing or unexpected
- Size failures: Expected vs actual size with human-readable format (bytes, KB, MB)
- Content failures: Line-by-line differences for text content with highlighting
- Structure failures: Tree-like display of directory structure differences
- Path resolution failures: Clear explanation of canonical path vs actual path issues
All file system matchers handle I/O exceptions appropriately and convert them to meaningful assertion failures with context about the attempted operation.
Install with Tessl CLI
npx tessl i tessl/maven-io-kotest--kotest-assertions-core-jvm