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规则。