Kotlin多平台断言库Atrium完全指南：为什么它比AssertJ更能告诉你测试为什么失败

Kotlin多平台断言库Atrium完全指南为什么它比AssertJ更能告诉你测试为什么失败【免费下载链接】atriumA multiplatform expectation library for Kotlin项目地址: https://gitcode.com/gh_mirrors/atr/atriumAtrium 是一款开源的 Kotlin 多平台断言库同时支持 JVM、JS 和 Android。与常见的断言工具不同它的设计目标只有一个当测试失败时用尽可能详细、可读的方式告诉你哪里错了、为什么错。本指南面向刚接触 Kotlin 测试的新手带你快速理解 Atrium 的核心能力以及它相比 AssertJ 在失败报告上的独特优势。 断言测试的痛点为什么失败传统断言失败时你往往只得到一行冰冷的提示例如expecting [1, 2, 3] to contain exactly [1, 3]问题很抽象实际值和期望值混在一起看不出多出来的元素在哪、顺序对不对、类型是什么。调试时间就此拉长。Atrium 的思路是让每一条失败信息都能像现场取证一样回答以下问题你想知道的Atrium 如何回答实际值是什么首行固定打印 subject被测对象及其真实类型我期望了什么以◆开头的行逐条列出所有期望差在哪用✔/✘/❗❗符号标注每个元素的匹配情况还有额外线索吗附送类型信息、误差计算、堆栈摘要等提示 第一个断言像读句子一样写测试Atrium 的断言以expect(...)开头后续的动词链式调用像一句自然语言。例如期望10等于9import ch.tutteli.atrium.api.fluent.en_GB.* import ch.tutteli.atrium.api.verbs.expect val x 10 expect(x).toEqual(9)失败报告如下第一行是实际值◆行是你提出的期望I expected subject: 10 (kotlin.Int 1234789) ◆ to equal: 9 (kotlin.Int 1234789)读起来就是我期望被测对象 10 应该等于 9——失败原因一目了然。单个断言 vs 断言组链式调用是快速失败前一个期望失败后后面的不再执行。如果你希望同一个对象的多个期望全部执行、一次性汇报所有失败可以用断言组expectation-group语法expect(4 6) { toBeLessThan(5) toBeGreaterThan(10) }I expected subject: 10 (kotlin.Int 1234789) ◆ to be less than: 5 (kotlin.Int 1234789) ◆ to be greater than: 10 (kotlin.Int 1234789) 这里体现了 Atrium 与 AssertJ 的一个重要差异AssertJ 要一次性汇报多个失败通常需要用assertSoftly额外工具包裹并重复书写被测对象而 Atrium 的断言组是内置在任何层级的语法无需额外工具也不用重复 subject。 失败报告深度解析比 AssertJ 多告诉你什么这是本文的核心。Atrium 官方将其称为 Ready to Help随时提供帮助具体体现在三件事上。1️⃣ 集合断言逐元素标注匹配情况对列表listOf(1, 2, 3)期望按顺序只包含 1 和 3expect(listOf(1, 2, 3)).toContain.inOrder.only.values(1, 3)报告如下I expected subject: [1, 2, 3] (java.util.Arrays.ArrayList 1234789) ◆ ▶ size: 3 (kotlin.Int 1234789) ◾ to equal: 2 (kotlin.Int 1234789) ◆ to contain only, in order: ✔ ▶ element 0: 1 (kotlin.Int 1234789) ◾ to equal: 1 (kotlin.Int 1234789) ✘ ▶ element 1: 2 (kotlin.Int 1234789) ◾ to equal: 3 (kotlin.Int 1234789) ❗❗ additional elements detected: ⚬ element 2: 3 (kotlin.Int 1234789)Atrium 一次性给出了四重信息✔ / ✘每个位置是否匹配index 1 的2不匹配期望的3隐含的 size 断言实际 3 个元素期望只有 2 个❗❗ 额外元素提示多出的element 2: 3被明确标出类型信息每个值后面括号里标注了真实类型2️⃣ 浮点断言连误差计算过程都展示expect(9.99f).toEqualWithErrorTolerance(10.0f, 0.01f)I expected subject: 9.99 (kotlin.Float 1234789) ◆ to equal (error ± 0.01): 10.0 (kotlin.Float 1234789) » failure might be due to using kotlin.Float, see exact check on the next line » exact check was |9.989999771118164 - 10.0| 0.010000228881835938 ≤ 0.009999999776482582这个断言第一眼看起来应该过但实际失败了。如果没有额外信息你甚至会怀疑是断言库有 bug。Atrium 不仅指出是kotlin.Float精度问题还把精确误差计算过程打印出来——这是多数断言库做不到的。3️⃣ 异常断言告诉你实际抛了什么期望抛出IllegalStateException但代码实际抛出了IllegalArgumentExceptionI expected subject: () - kotlin.Nothing (...) ◆ ▶ thrown exception when called: java.lang.IllegalArgumentException ◾ to be an instance of type: IllegalStateException (java.lang.IllegalStateException) ℹ Properties of the unexpected IllegalArgumentException » message: no no no... 1234789 » stacktrace: ⚬ readme.examples.MostExamples$ex-add-info-3$1.invoke(MostExamples.kt:117) ... » cause: java.lang.UnsupportedOperationException » message: not supported 1234789除了类型不对报告还附上了实际异常的完整属性消息、过滤后的堆栈、甚至 cause 链。堆栈默认过滤掉断言库和测试框架JUnit、Kotest、TestNG 等自身的帧只保留你关心的部分。️ 主动防范常见坑断言库替你把关Atrium 不只汇报失败还会主动拦截你的写法陷阱这是它和其他断言库最大的设计差异之一。陷阱一BigDecimal 的 scale 比较。BigDecimal(10)和BigDecimal(10.0)数值相等但精度不同用普通的toEqual很容易踩坑。Atrium 干脆把针对BigDecimal的toEqual/notToEqual标记为弃用并抛出提示异常强制你明确选择toEqualNumerically数值比较或toEqualIncludingScale含精度比较。即便你选了后者且因此失败报告里还有贴心提示I expected subject: 10 (java.math.BigDecimal 1234789) ◆ is equal (including scale): 10.0 (java.math.BigDecimal 1234789) notice, if you used toEqualNumerically then the expectation would have been met.陷阱二空的断言 lambda。比如手滑写了expect(listOf(1)).get(0) {}Atrium 会明确提醒你忘记在 lambda 里定义期望了并给出替代写法建议而不是静默通过。 两种 API 风格fluent 与 infixAtrium 提供两种可自由选择的 API 风格对应不同的依赖包风格包名写法示例特点fluentatrium-fluentexpect(x).toEqual(2)纯方法链代码补全引导体验最佳infixatrium-infixexpect(x) toEqual 2Kotlin 中缀语法更像写句子两种风格功能对等甚至可以混用。fluent 风格在设计时优先考虑了与 IDE 代码补全的协同配合每个断言函数都附带的 KDoc 示例你能在输入时直接获得上下文帮助。 快速安装与多平台支持Atrium 发布在 Maven Central最低要求Kotlin 1.4、JVM 11。在build.gradle.kts中添加依赖即可repositories { mavenCentral() } dependencies { testImplementation(ch.tutteli.atrium:atrium-fluent:1.2.0) }多平台项目则加在commonTest源集kotlin { sourceSets { val commonTest by getting { implementation(ch.tutteli.atrium:atrium-fluent:1.2.0) } } }由于支持 Kotlin Multiplatform同一份测试代码可以跑在 JVM、JS 和 Android 上这对 KMP 项目尤其友好。项目内提供了 JUnit5、Kotest、TestNG、Maven、JS kotlin-test 等多种测试框架的示例工程位于samples/目录下如samples/jvm/junit5、samples/multiplatform/kotlin-test可作为接入参考。️ 项目结构速览了解模块划分有助于按需深入源码。Atrium 的分层非常清晰atrium-core—— 核心层负责断言模型与失败报告的文本格式化源码在atrium-core/src/commonMain/kotlin/ch/tutteli/atrium/reporting/logic/atrium-logic—— 逻辑层所有内置断言函数的实现集合、Map、浮点数、异常等入口文件如logic/atrium-logic/src/commonMain/kotlin/ch/tutteli/atrium/logic/IterableLikeAssertions.ktapis/fluent 与 apis/infix—— 两种 API 风格的具体定义apis/differences.md记录了二者在命名上的全部差异translations/atrium-translations-en_GB—— 报告文案的翻译模块Atrium 的报告措辞是可翻译、可定制的misc/atrium-test-factory—— 为断言库自身测试提供的工厂工具misc/atrium-specs—— 规范化的断言测试套件这种core / logic / api / 翻译分离的设计意味着你可以替换几乎任何组件自定义报告风格、接入自己的断言动词甚至把 AssertJ 的断言通过toHoldThirdPartyExpectation集成进 Atrium 的报告体系中方便渐进式迁移。⚖️ 总结Atrium 值得尝试的理由失败即诊断逐元素 ✔/✘ 标注、隐含 size 断言、误差计算、异常属性全量展示失败报告本身就是排查线索防坑设计对 BigDecimal、空 lambda 等经典陷阱主动拦截并给出改进建议多平台一致体验Kotlin 多平台支持同一份断言代码跨 JVM / JS / Android灵活可扩展fluent/infix 双风格、报告文案可翻译、组件可替换、可集成第三方断言迁移友好弃用 API 附带ReplaceWith提示与迁移指南渐进式升级如果你正被测试失败后不知道为什么失败所困扰Atrium 值得在你的下一个 Kotlin 项目中一试。【免费下载链接】atriumA multiplatform expectation library for Kotlin项目地址: https://gitcode.com/gh_mirrors/atr/atrium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考