atrium-api-infix/ch.tutteli.atrium.api.infix.en_GB/toBe

toBe

infix fun <T : CharSequence> Expect<T>.toBe(empty: empty): Expect<T>(source)

Expects that the subject of this expectation (a CharSequence) CharSequence.kotlin.text.isEmpty.

Return

an Expect for the subject of this expectation.

Parameters

empty

Use the pseudo-keyword empty.

Samples

expect("") toBe empty

fails {
    expect("XYZ") toBe empty
}
infix fun <T : Collection<*>> Expect<T>.toBe(empty: empty): Expect<T>(source)

Expects that the subject of this expectation (a Collection) is an empty Collection.

Return

an Expect for the subject of this expectation.

Parameters

empty

Use the pseudo-keyword empty.

Samples

expect(emptyList<Int>()) toBe empty

fails {
    expect(listOf(1, 2, 3)) toBe empty
}
infix fun <T : Map<*, *>> Expect<T>.toBe(empty: empty): Expect<T>(source)

Expects that the subject of this expectation (a Map) is an empty Map.

Return

an Expect for the subject of this expectation.

Parameters

empty

Use the pseudo-keyword empty.

Samples

expect(emptyMap<Int, String>()) toBe empty

fails { // because the map is not empty
    expect(mapOf(1 to "a")) toBe empty
}
infix fun <E, T : Result<E>> Expect<T>.toBe(aSuccess: aSuccess): Expect<E>(source)

Expects that the subject of this expectation (a Result) is a success (Result.isSuccess) and returns an Expect for the inner type E.

Return

The newly created Expect if the given assertion is success.

Since

1.1.0 (was in kotlin_1_3 extension since 0.17.0)

Samples

expect(Result.success(10)) toBe aSuccess toEqual 10 toBeLessThan 15
//                               | subject is now of type Int (actually 10)


fails { // because sub-expectation fails
    expect(Result.success(10)) toBe aSuccess toBeLessThan 5 toBeGreaterThan 12
    //                               |          |           | not evaluated/reported because `toBeLessThan` already fails
    //                               |          |           | use `toBe aSuccess { ... }` if you want that all expectations are evaluated
    //                               |          | fails
    //                               | subject is now of type Int (actually 10)
}

fails { // because it was a Failure
    expect(
        Result.failure<Int>(ArithmeticException())
    ) toBe aSuccess toBeGreaterThan 12
    //      |           | not evaluated/reported because `toBeASuccess` already fails
    //      |           | use `toBe aSuccess { ... }` if you want that all expectations are evaluated
    //      | fails
}
infix fun <E, T : Result<E>> Expect<T>.toBe(success: SuccessWithCreator<E>): Expect<T>(source)

Expects that the subject of this expectation (a Result) is a success (Result.isSuccess) and that it holds all assertions the given SuccessWithCreator.assertionCreator creates.

Use the function aSuccess { ... } to create a SuccessWithCreator.

Return

an Expect for the subject of this expectation.

Since

1.1.0 (was in kotlin_1_3 extension since 0.12.0)

Samples

expect(Result.success(10)) toBe aSuccess { // subject within this expectation-group is of type Int (actually 10)
    it toEqual 10
    it toBeLessThan 15
} // subject here is back to type Result<Int>

fails { // because sub-expectation fails
    expect(Result.success(10)) toBe aSuccess {
        it toBeGreaterThan 15 // fails
        it toBeLessThan 5     // still evaluated even though `toBeGreaterThan` already fails
        //                       use `.toBeASuccess.` if you want a fail fast behaviour
    }
}

fails { // because it was a Failure, but since we use an expectation-group...
    expect(Result.failure<Int>(ArithmeticException())) toBe aSuccess {
        it toBeGreaterThan 12 // ...reporting mentions that subject was expected `to be greater than: 12`
        //                       use `.toBeASuccess.` if you want a fail fast behaviour
    }

}
infix fun <T : Optional<*>> Expect<T>.toBe(empty: empty): Expect<T>(source)

Expects that the subject of this expectation (an Optional) is empty (not present).

Shortcut for more or less something like feature(Optional<T>::isEmpty) { it toEqual true } depends on the underlying implementation though.

Return

an Expect for the subject of this expectation.

Since

0.12.0

infix fun <E : Any, T : Optional<E>> Expect<T>.toBe(present: present): FeatureExpect<T, E>(source)

Expects that the subject of this expectation (an Optional) is present and returns an Expect for the inner type E.

Shortcut for more or less something like feature(Optional<T>::get) but with error handling; yet it depends on the underlying implementation though.

Return

the newly created Expect for the inner type E.

Since

0.12.0

infix fun <E : Any, T : Optional<E>> Expect<T>.toBe(present: PresentWithCreator<E>): Expect<T>(source)

Expects that the subject of this expectation (an Optional) is present and that the wrapped value of type E holds all assertions the given PresentWithCreator.assertionCreator creates.

Return

an Expect for the subject of this expectation.

Since

0.12.0

infix fun <T : Path> Expect<T>.toBe(existing: existing): Expect<T>(source)

Expects that the subject of this expectation (a Path) exists; meaning that there is a file system entry at the location the Path points to.

This assertion resolves symbolic links. Therefore, if a symbolic link exists at the location the subject points to, then the search will continue at that location.

Return

an Expect for the subject of this expectation.

Since

0.12.0

Samples

val dir = tempDir.newDirectory("test_dir")

expect(dir) toBe existing

fails {
    expect(Paths.get("non_existing_dir")) toBe existing
}
infix fun <T : Path> Expect<T>.toBe(readable: readable): Expect<T>(source)

Expects that the subject of this expectation (a Path) is readable; meaning that there is a file system entry at the location the Path points to and that the current thread has the permission to read from it.

This assertion resolves symbolic links. Therefore, if a symbolic link exists at the location the subject points to, search will continue at the location the link points at.

This assertion is not atomic with respect to concurrent file system operations on the paths the assertion works on. Its result, in particular its extended explanations, may be wrong if such concurrent file system operations take place.

Return

an Expect for the subject of this expectation.

Since

0.12.0

Samples

val dir = tempDir.newDirectory("test_dir")

expect(dir) toBe readable

fails {
    expect(Paths.get("non_existing_dir")) toBe readable
}
infix fun <T : Path> Expect<T>.toBe(writable: writable): Expect<T>(source)

Expects that the subject of this expectation (a Path) is writable; meaning that there is a file system entry at the location the Path points to and that the current thread has the permission to write to it.

This assertion resolves symbolic links. Therefore, if a symbolic link exists at the location the subject points to, search will continue at the location the link points at.

Return

an Expect for the subject of this expectation.

Since

0.12.0

Samples

val dir = tempDir.newDirectory("test_dir")

expect(dir) toBe writable

fails {
    expect(Paths.get("non_existing_dir")) toBe writable
}
infix fun <T : Path> Expect<T>.toBe(executable: executable): Expect<T>(source)

Expects that the subject of this expectation (a Path) is executable; meaning that there is a file system entry at the location the Path points to and that the current thread has the permission to execute it.

The semantics of “permission to execute it” may differ when checking access to a directory. For example, on UNIX systems, it means that the Java virtual machine has permission to search the directory in order to access file or subdirectories.

This assertion resolves symbolic links. Therefore, if a symbolic link exists at the location the subject points to, search will continue at the location the link points at.

Return

an Expect for the subject of this expectation.

Since

0.14.0

Samples

val dir = tempDir.newDirectory("test_dir")

expect(dir) toBe executable

fails {
    expect(Paths.get("non_existing_dir")) toBe executable
}
infix fun <T : Path> Expect<T>.toBe(aRegularFile: aRegularFile): Expect<T>(source)

Expects that the subject of this expectation (a Path) is a file; meaning that there is a file system entry at the location the Path points to and that is a regular file.

This assertion resolves symbolic links. Therefore, if a symbolic link exists at the location the subject points to, search will continue at the location the link points at.

This assertion is not atomic with respect to concurrent file system operations on the paths the assertion works on. Its result, in particular its extended explanations, may be wrong if such concurrent file system operations take place.

Return

an Expect for the subject of this expectation.

Since

0.12.0

Samples

val file = tempDir.newFile("test_file")
val dir = tempDir.newDirectory("test_dir")

expect(file) toBe aRegularFile

fails {
    expect(dir) toBe aRegularFile
}
infix fun <T : Path> Expect<T>.toBe(aDirectory: aDirectory): Expect<T>(source)

Expects that the subject of this expectation (a Path) is a directory; meaning that there is a file system entry at the location the Path points to and that is a directory.

This assertion resolves symbolic links. Therefore, if a symbolic link exists at the location the subject points to, search will continue at the location the link points at.

This assertion is not atomic with respect to concurrent file system operations on the paths the assertion9 works on. Its result, in particular its extended explanations, may be wrong if such concurrent file system operations take place.

Return

an Expect for the subject of this expectation.

Since

0.12.0

Samples

val file = tempDir.newFile("test_file")
val dir = tempDir.newDirectory("test_dir")

expect(dir) toBe aDirectory

fails {
    expect(file) toBe aDirectory
}
infix fun <T : Path> Expect<T>.toBe(anEmptyDirectory: anEmptyDirectory): Expect<T>(source)

Expects that the subject of this expectation (a Path) is an empty directory; meaning that there is a file system entry at the location the Path points to and that is an empty directory.

Return

an Expect for the subject of this expectation.

Since

0.16.0

Samples

val dir = tempDir.newDirectory("test_dir")
expect(dir) toBe anEmptyDirectory

dir.newFile("test_file.txt")
fails {
    expect(dir) toBe anEmptyDirectory
}
infix fun <T : Path> Expect<T>.toBe(aSymbolicLink: aSymbolicLink): Expect<T>(source)

Expects that the subject of this expectation (a Path) is a symbolic link; meaning that there is a file system entry at the location the Path points to and that is a symbolic link.

This assertion is not atomic with respect to concurrent file system operations on the paths the assertion works on. Its result, in particular its extended explanations, may be wrong if such concurrent file system operations take place.

Return

an Expect for the subject of this expectation.

Since

0.16.0

Samples

val target = tempDir.newFile("target")
val link = Files.createSymbolicLink(tempDir.resolve("link"), target)

// Passes, because subject `link` is a symbolic link
expect(link) toBe aSymbolicLink

val file = tempDir.newFile("somePath")

fails { // because subject `path` is a not a symbolic link
    expect(file) toBe aSymbolicLink
}
infix fun <T : Path> Expect<T>.toBe(absolute: absolute): Expect<T>(source)

Expects that the subject of this expectation (a Path) is an absolute path; meaning that the Path specified in this instance starts at the file system root.

Return

an Expect for the subject of this expectation.

Since

0.14.0

Samples

val s = FileSystems.getDefault().separator
val prefix = if (s == "\\") "C:" else "" // if (s == "\\") => true current os is windows
expect(Paths.get("$prefix${s}absolute${s}path")) toBe absolute

fails {
    expect(Paths.get("relative/path")) toBe absolute
}
infix fun <T : Path> Expect<T>.toBe(relative: relative): Expect<T>(source)

Expects that the subject of this expectation (a Path) is a relative path; meaning that the Path specified in this instance does not start at the file system root.

Return

an Expect for the subject of this expectation.

Since

0.14.0

Samples

expect(Paths.get("relative/path")) toBe relative

fails {
    val s = FileSystems.getDefault().separator
    val prefix = if (s == "\\") "C:" else "" // if (s == "\\") => true current os is windows
    expect(Paths.get("$prefix${s}absolute${s}path")) toBe relative
}