assertk

assertk 是一个受 AssertJ 启发的 Kotlin 流式断言库。

• 文档

为什么需要另一个断言库？

你可能会问："如果已经有 AssertJ 了，为什么还要创建另一个库？"确实，assertk 与 AssertJ 非常相似。但 assertk 是用 Kotlin 编写的，所以它有一个主要优势：扩展方法。这使得添加自己的断言方法变得更加简单。

请参阅下面的自定义断言部分，了解如何实现这一点。

设置

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("com.willowtreeapps.assertk:assertk:0.28.1")
}

assertk 完全支持多平台，可以在 jvm、js 或 native 项目中使用。例如，使用多平台插件进行设置：

plugins {
    kotlin("multiplatform")
}

kotlin {
    sourceSets {
        val commonTest by getting {
            dependencies {
                implementation("com.willowtreeapps.assertk:assertk:0.28.1")
            }
        }
    }
}

使用方法

简单的用法是将你要测试的值或属性包装在 assertThat() 中，并在结果上调用断言方法。

import assertk.assertThat
import assertk.assertions.*

class PersonTest {
    val person = Person(name = "Bob", age = 18)

    @Test
    fun testName() {
        assertThat(person.name).isEqualTo("Alice")
        // -> 期望:<["Alice"]> 但实际是:<["Bob"]>
    }

    @Test
    fun testAge() {
        assertThat(person.age, "age").isGreaterThan(20)
        // -> 期望 [age] 大于:<20> 但实际是:<18>
    }

    @Test
    fun testNameProperty() {
        assertThat(person::name).isEqualTo("Alice")
        // -> 期望 [name]:<["Alice"]> 但实际是:<["Bob"]>
    }
}

你可以在文档中查看所有内置断言。

可空性

由于 null 在 Kotlin 的类型系统中是一等公民，你需要在断言中明确处理它。

val nullString: String? = null
assertThat(nullString).hasLength(4)

这段代码无法编译，因为 hasLength() 只对非空值有意义。你可以链接 isNotNull() 来处理这种情况。

val nullString: String? = null
assertThat(nullString).isNotNull().hasLength(4)
// -> 期望不为 null

这将首先确保字符串不为 null，然后再运行任何其他检查。

多重断言

你可以通过提供一个 lambda 作为第二个参数来对单个值进行多个断言。即使第一个断言失败，所有断言也会运行。

val string = "Test"
assertThat(string).all {
    startsWith("L")
    hasLength(3)
}
// -> 以下 2 个断言失败：
//    - 期望以:<"L">开头，但实际是:<"Test">
//    - 期望长度为:<3>，但实际是:<"Test"> (4)

你可以将多个断言包装在 assertAll 中，以确保它们都被运行，而不仅仅是第一个。

assertAll {
    assertThat(false).isTrue()
    assertThat(true).isFalse()
}
// -> 以下 2 个断言失败：
//    - 期望为 true
//    - 期望为 false

可迭代对象/列表断言

你可以使用各种 contains* 函数对 Iterable/List 的内容进行断言。它们具有不同的语义，如下所示：

断言	描述
containsAtLeast	断言可迭代对象至少包含预期的元素，顺序不限。集合中可能还包含其他额外元素。
containsSubList	断言集合包含一个子集，元素顺序相同，但列表中可能有额外元素。
containsOnly	断言可迭代对象仅包含预期的元素，顺序不限。预期和实际中的重复值会被忽略。
containsExactlyInAnyOrder	断言可迭代对象恰好包含预期的元素，顺序不限。预期中的每个值必须与实际中的匹配值一一对应，反之亦然。
containsExactly	断言列表恰好包含预期的元素。它们必须顺序相同，且不能有任何额外元素。
containsNone	断言可迭代对象不包含任何预期的元素。

提取数据

有几种方法可以提取你想要断言的数据。虽然你可以在调用断言之前自己完成这个操作，但这些方法会在失败消息中添加额外的上下文信息，这可能会很有帮助。

最简单的方法是使用prop()。它可以接受一个属性（或函数，或名称和lambda表达式）并返回对该属性的断言。

val person = Person(age = 22)
assertThat(person).prop(Person::age).isEqualTo(20)

// -> expected [age]:<2[0]> but was:<2[2]> (Person(age=22))

对于集合，你可以使用index()从列表中提取特定索引，使用key()从映射中提取特定值。

assertThat(listOf(1, 2, 3)).index(1).isEqualTo(1)

// -> expected: [[1]]:<1> but was:<2> ([1, 2, 3])

assertThat(mapOf("one" to 1, "two" to 2, "three" to 3)).key("two").isEqualTo(1)

// -> expected: [["two"]]:<1> but was:<2> ({"one"=1, "two"=2, "three"=3})

你还可以使用extracting()从集合中提取属性。

val people = listOf(Person(name = "Sue"), Person(name = "Bob"))
assertThat(people)
    .extracting(Person::name)
    .containsExactly("Sue", "Bob")

异常

如果你期望抛出异常，可以使用assertFailure，它接受一个lambda表达式。

assertFailure {
    throw Exception("error")
}.hasMessage("wrong")
// -> expected [message] to be:<["wrong"]> but was:<["error"]>

表格断言

如果你有多组想要测试的值，可以创建一个表格断言。

tableOf("a", "b", "result")
    .row(0, 0, 1)
    .row(1, 2, 4)
    .forAll { a, b, result ->
        assertThat(a + b).isEqualTo(result)
    }
// -> the following 2 assertions failed:
//    on row:(a=<0>,b=<0>,result=<1>)
//    - expected:<[1]> but was:<[0]>
//    on row:(a=<1>,b=<2>,result=<4>)
//    - expected:<[4]> but was:<[3]>

支持最多4列。

自定义断言

这个库的目标之一是让自定义断言变得简单。所有断言都只是扩展方法。

fun Assert<Person>.hasAge(expected: Int) {
    prop(Person::age).isEqualTo(expected)
}

assertThat(person).hasAge(20)
// -> expected [age]:<2[0]> but was:<2[2]> (Person(age=22))

对于完全自定义的断言，你有几个构建块。given会给你实际值进行断言，expected()和show()会帮助你格式化失败消息。

fun Assert<Person>.hasAge(expected: Int) = given { actual ->
    if (actual.age == expected) return
    expected("age:${show(expected)} but was age:${show(actual.age)}")
}

assertThat(person).hasAge(20)
// -> expected age:<20> but was age:<22>

你还可以使用transform构建可链式调用的断言。这允许你既对实际值进行断言，又返回更具体的内容，以便可以链接额外的断言。

fun Assert<Person>.hasMiddleName(): Assert<String> = transform(appendName("middleName", separator = ".")) { actual ->
    if (actual.middleName != null) {
        actual.middleName
    } else {
        expected("to not be null")
    }
}

assertThat(person).hasMiddleName().isEqualTo("Lorie")

// -> expected [middleName]:to not be null

注意：这是一个有点勉强的例子，因为你可能更愿意使用现有的断言来构建它。

fun Assert<Person>.hasMiddleName(): Assert<String> = prop(Person::middleName).isNotNull()

一般的经验法则是，除非你能给出更有意义的错误消息，否则更倾向于使用现有的断言来构建。

额外工具

• Assertk Lint - 一组鼓励正确使用assertk的lint规则。

为assertk做贡献

我们非常欢迎贡献！请查阅贡献指南，并请注意遵守我们的行为准则。