From b87c86fb1c391169b3d78180472711011857dddc Mon Sep 17 00:00:00 2001 From: Robert Stoll Date: Wed, 26 Aug 2020 22:11:17 +0200 Subject: [PATCH] v0.13.0 --- .github/CONTRIBUTING.md | 2 +- README.md | 226 ++++++++++++++++++++-------------------- apis/differences.md | 6 +- build.gradle | 4 +- 4 files changed, 119 insertions(+), 119 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 50ed2eb378..147443f656 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -12,7 +12,7 @@ Following a few guidelines so that others can quickly benefit from your contribu ## Code of Conduct This project and everyone participating in it is governed by Atrium's -[Code of Conduct](https://github.com/robstoll/atrium/tree/master/.github/CODE_OF_CONDUCT.md). +[Code of Conduct](https://github.com/robstoll/atrium/tree/v0.13.0/.github/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to info@tutteli.ch ## How to Contribute diff --git a/README.md b/README.md index fae041db85..f2bd1da5a0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + - + # Atrium Atrium is an open-source multiplatform assertion library for Kotlin with support for JVM, JS and Android. @@ -30,12 +30,12 @@ Atrium currently provides two [API Styles](#api-styles): pure fluent and infix where both of them have their design focus on usability in conjunction with code completion functionality provided by your IDE. See [Examples](#examples) below to get a feel for how you could benefit from Atrium. ---- + **Table of Content** - [Installation](#installation) @@ -104,8 +104,8 @@ dependencies { We have defined a dependency to the bundle `atrium-fluent-en_GB` in the above example which provides a pure fluent API (in en_GB) for the JVM platform. -Have a look at the [JVM sample projects](https://github.com/robstoll/atrium/tree/master/samples/jvm) for a quick setup, or -[Maven sample project](https://github.com/robstoll/atrium/tree/master/samples/maven) if you prefer Maven to Gradle. +Have a look at the [JVM sample projects](https://github.com/robstoll/atrium/tree/v0.13.0/samples/jvm) for a quick setup, or +[Maven sample project](https://github.com/robstoll/atrium/tree/v0.13.0/samples/maven) if you prefer Maven to Gradle. We currently provide the following extensions for the JVM platform: - kotlin_1_3: assertion functions for Kotlin 1.3 specific types (e.g. for [Result](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-result/index.html)). @@ -148,7 +148,7 @@ dependencies { *maven*: Because maven is a bit more verbose than gradle, the example is not listed here but a -[sample maven project](https://github.com/robstoll/atrium/tree/master/samples/maven) +[sample maven project](https://github.com/robstoll/atrium/tree/v0.13.0/samples/maven) is provided which shows all necessary setup. That is all, you are all set. Jump to [Examples](#examples) which shows how to use Atrium. @@ -173,19 +173,19 @@ dependencies { We have defined a dependency to the bundle `atrium-fluent-en_GB-js` in the above example which provides a pure fluent API (in en_GB) for the JS platform. -Have a look at the [JS sample projects](https://github.com/robstoll/atrium/tree/master/samples/jvm) for a quick setup. +Have a look at the [JS sample projects](https://github.com/robstoll/atrium/tree/v0.13.0/samples/jvm) for a quick setup. Otherwise, you need to setup an explicit dependency on `atrium-fluent-en_GB-js` in your test code in order that you can use Atrium. This is due to the loosely coupled design of Atrium and dead code elimination performed by the Kotlin compiler for JS. Atrium itself is using mocha as well -(see [build.gradle -> createJsTestTask](https://github.com/robstoll/atrium/tree/master/build.gradle#L290)) +(see [build.gradle -> createJsTestTask](https://github.com/robstoll/atrium/tree/v0.13.0/build.gradle#L290)) and has tests written in JS modules -(see [AdjustStackTest](https://github.com/robstoll/atrium/tree/master/core/robstoll-lib/atrium-core-robstoll-lib-js/src/test/kotlin/ch/tutteli/atrium/core/robstoll/lib/reporting/AdjustStackTest.kt)) -as well as tests written in common modules (e.g. [SmokeTest](https://github.com/robstoll/atrium/tree/master/bundles/fluent-en_GB/atrium-fluent-en_GB-common/src/test/kotlin/SmokeTest.kt)) +(see [AdjustStackTest](https://github.com/robstoll/atrium/tree/v0.13.0/core/robstoll-lib/atrium-core-robstoll-lib-js/src/test/kotlin/ch/tutteli/atrium/core/robstoll/lib/reporting/AdjustStackTest.kt)) +as well as tests written in common modules (e.g. [SmokeTest](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/fluent-en_GB/atrium-fluent-en_GB-common/src/test/kotlin/SmokeTest.kt)) which are executed on the JS platform as well (actually on all platforms -> JVM uses JUnit for this purpose, see -[build.gradle -> useJupiter](https://github.com/robstoll/atrium/tree/master/build.gradle#L342)). +[build.gradle -> useJupiter](https://github.com/robstoll/atrium/tree/v0.13.0/build.gradle#L342)). We currently provide the following extensions for the JS platform: - kotlin_1_3: assertion functions for Kotlin 1.3 specific types (e.g. for [Result](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-result/index.html)). @@ -238,16 +238,16 @@ The setup for using Atrium in a common module of a multiplatform project is basi For instance `atrium-fluent-en_GB-common` instead of `atrium-fluent-en_GB`. Have a look at [JVM](#jvm), [JS](#js) or [Android](#android) to see how the setup of a specific platform has to be done. -You might want to have a look at the [Multiplatform sample project](https://github.com/robstoll/atrium/tree/master/samples/multiplatform) +You might want to have a look at the [Multiplatform sample project](https://github.com/robstoll/atrium/tree/v0.13.0/samples/multiplatform) as well for a quick setup. # Examples We are using the API provided by the bundle module -[atrium-fluent-en_GB](https://github.com/robstoll/atrium/tree/master/bundles/fluent-en_GB/atrium-fluent-en_GB/build.gradle) +[atrium-fluent-en_GB](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/fluent-en_GB/atrium-fluent-en_GB/build.gradle) in the following examples. It provides a pure fluent API for the JVM platform. Have a look at -[apis/differences.md](https://github.com/robstoll/atrium/tree/master/apis/differences.md) +[apis/differences.md](https://github.com/robstoll/atrium/tree/v0.13.0/apis/differences.md) to see how the infix API looks like, how they differ respectively. ## Your First Assertion @@ -262,7 +262,7 @@ import ch.tutteli.atrium.api.verbs.expect val x = 10 expect(x).toBe(9) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L53) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L53) ↓ Output ```text expected that subject: 10 (kotlin.Int <1234789>) ◆ equals: 9 (kotlin.Int <1234789>) @@ -275,7 +275,7 @@ where `◆ ...` represents a single assertion for the subject (`10` in the above In this sense the report can be read as `I expected that the subject of the assertion, which is 10, equals 9` -- and needless to say, this assertion is wrong and thus the thrown error. -We are using the bundle [atrium-fluent-en_GB](https://github.com/robstoll/atrium/tree/master/bundles/fluent-en_GB/atrium-fluent-en_GB/build.gradle) +We are using the bundle [atrium-fluent-en_GB](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/fluent-en_GB/atrium-fluent-en_GB/build.gradle) and the predefined assertion verb `expect` in the examples. Thus the corresponding `import`s at the beginning of the file in the above example. We will omit the `import` statements in the remaining examples for brevity. @@ -304,7 +304,7 @@ The next section shows how you can define multiple assertions for the same subje // two single assertions, only first evaluated expect(4 + 6).isLessThan(5).isGreaterThan(10) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L60) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L60) ↓ Output ```text expected that subject: 10 (kotlin.Int <1234789>) ◆ is less than: 5 (kotlin.Int <1234789>) @@ -336,7 +336,7 @@ expect(4 + 6) { isGreaterThan(10) } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L65) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L65) ↓ Output ```text expected that subject: 10 (kotlin.Int <1234789>) ◆ is less than: 5 (kotlin.Int <1234789>) @@ -367,7 +367,7 @@ expect { throw IllegalArgumentException("name is empty") }.toThrow() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L73) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L73) ↓ Output ```text expected that subject: () -> kotlin.Nothing (readme.examples.ReadmeSpec$1$4$1 <1234789>) ◆ ▶ thrown exception when called: java.lang.IllegalArgumentException @@ -402,7 +402,7 @@ expect { throw IllegalArgumentException() }.toThrow().message.startsWith("firstName") ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L80) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L80) ↓ Output ```text expected that subject: () -> kotlin.Nothing (readme.examples.ReadmeSpec$1$5$1 <1234789>) ◆ ▶ thrown exception when called: java.lang.IllegalArgumentException @@ -422,7 +422,7 @@ expect { message { startsWith("firstName") } } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L86) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L86) ↓ Output ```text expected that subject: () -> kotlin.Nothing (readme.examples.ReadmeSpec$1$6$1 <1234789>) ◆ ▶ thrown exception when called: java.lang.IllegalArgumentException @@ -445,7 +445,7 @@ expect { throw IllegalArgumentException("name is empty", RuntimeException("a cause")) }.notToThrow() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L94) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L94) ↓ Output ```text expected that subject: () -> kotlin.Nothing (readme.examples.ReadmeSpec$1$7$1 <1234789>) ◆ does not: throw when called @@ -465,7 +465,7 @@ expected that subject: () -> kotlin.Nothing (readme.examples.ReadmeSpec$1 Notice that stacks are filtered so that you only see what is of interest. Filtering can be configured via [`ReporterBuilder`](#reporterbuilder) by choosing an appropriate -[AtriumErrorAdjuster](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.reporting/-atrium-error-adjuster/index.html). +[AtriumErrorAdjuster](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.reporting/-atrium-error-adjuster/index.html). Stack frames of Atrium and of test runners (Spek, Kotlintest and JUnit for JVM, mocha and jasmine for JS) are excluded per default. [Create a Feature Request](https://github.com/robstoll/atrium/issues/new?template=feature_request.md&title=[Feature]) in case you use a different runner, we can add yours to the list as well. @@ -498,7 +498,7 @@ expect(myPerson) .feature { f(it::fullName) } // not evaluated anymore, subject String afterwards .startsWith("rob") // not evaluated anymore ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L113) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L113) ↓ Output ```text expected that subject: Person(firstName=Robert, lastName=Stoll, isStudent=false) (readme.examples.ReadmeSpec$1$Person <1234789>) ◆ ▶ isStudent: false @@ -550,7 +550,7 @@ Feature assertions follow the common pattern of having two overloads: feature { f(it::lastName) }.toBe("Dummy") } ``` - ↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L122) ↓ Output + ↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L122) ↓ Output ```text expected that subject: Person(firstName=Robert, lastName=Stoll, isStudent=false) (readme.examples.ReadmeSpec$1$Person <1234789>) ◆ ▶ firstName: "Robert" <1234789> @@ -600,7 +600,7 @@ expect(myPerson) .toBe("Robert aka. Stoll") // fails .startsWith("llotS") // not evaluated anymore ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L136) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L136) ↓ Output ```text expected that subject: Person(firstName=Robert, lastName=Stoll, isStudent=false) (readme.examples.ReadmeSpec$1$Person <1234789>) ◆ ▶ nickname(false): "Mr. Robert" <1234789> @@ -630,7 +630,7 @@ in case you miss a shortcut. 💬 Write own feature assertion functions with additional checks. Atrium provides a feature extractor which allows to make feature assertions in a safe way in case the extraction is only valid for certain subjects. -It is for instance used for [`List.get`](https://github.com/robstoll/atrium/tree/master/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultListAssertions.kt#L13) +It is for instance used for [`List.get`](https://github.com/robstoll/atrium/tree/v0.13.0/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultListAssertions.kt#L13) @@ -652,7 +652,7 @@ expect(myFamily) .feature("first member's name") { members.first().name } // subject narrowed to String .toBe("Peter") ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L153) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L153) ↓ Output ```text expected that subject: Family(members=[FamilyMember(name=Robert)]) (readme.examples.ReadmeSpec$1$Family <1234789>) ◆ ▶ first member's name: "Robert" <1234789> @@ -698,7 +698,7 @@ expect(listOf(1 to "a", 2 to "b")).get(10) { firstToBe(1) } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L169) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L169) ↓ Output ```text expected that subject: [(1, a), (2, b)] (java.util.Arrays.ArrayList <1234789>) ◆ ▶ get(10): ❗❗ index out of bounds @@ -784,7 +784,7 @@ expect(x).isA() .feature { f(it::number) } .toBe(2) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L202) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L202) ↓ Output ```text expected that subject: SubType2(word=hello, flag=true) (readme.examples.SubType2 <1234789>) ◆ is instance of type: SubType1 (readme.examples.SubType1) @@ -805,7 +805,7 @@ expect(x).isA { feature { f(it::flag) }.toBe(false) } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L208) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L208) ↓ Output ```text expected that subject: SubType2(word=hello, flag=true) (readme.examples.SubType2 <1234789>) ◆ ▶ word: "hello" <1234789> @@ -833,7 +833,7 @@ Let us look at the case where the subject of the assertion has a [nullable type] val slogan1: String? = "postulating assertions made easy" expect(slogan1).toBe(null) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L234) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L234) ↓ Output ```text expected that subject: "postulating assertions made easy" <1234789> ◆ equals: null @@ -846,7 +846,7 @@ expected that subject: "postulating assertions made easy" <1234789> val slogan2: String? = null expect(slogan2).toBe("postulating assertions made easy") ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L238) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L238) ↓ Output ```text expected that subject: null ◆ equals: "postulating assertions made easy" <1234789> @@ -866,7 +866,7 @@ expect(slogan2) // subject has type String? .notToBeNull() // subject narrowed to String .startsWith("atrium") ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L243) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L243) ↓ Output ```text expected that subject: null ◆ is instance of type: String (kotlin.String) -- Class: java.lang.String @@ -882,7 +882,7 @@ one without (example above) and one with `assertionCreator`-lambda (example belo ```kotlin expect(slogan2).notToBeNull { startsWith("atrium") } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L248) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L248) ↓ Output ```text expected that subject: null ◆ is instance of type: String (kotlin.String) -- Class: java.lang.String @@ -917,7 +917,7 @@ The following sub sections show both use cases by examples. ```kotlin expect(listOf(1, 2, 2, 4)).contains(2, 3) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L252) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L252) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains, in any order: @@ -936,7 +936,7 @@ This is reflected in the output, which tells us that we expected that the `numbe Exactly, what about the expected value `2`, why do we not see anything about it in the output? The output does not show anything about the expected value `2` because the predefined assertion verbs have configured [`ReporterBuilder`](#reporterbuilder) -to use an [Only Failure Reporter](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.core/-core-factory/new-only-failure-reporter.html) +to use an [Only Failure Reporter](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.core/-core-factory/new-only-failure-reporter.html) which shows us only assertions (or sub assertions) which failed. Back to the shortcut functions. @@ -957,7 +957,7 @@ expect(listOf(1, 2, 2, 4)).contains( { isGreaterThan(2).isLessThan(4) } ) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L256) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L256) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains, in any order: @@ -996,7 +996,7 @@ Following each in action: ```kotlin expect(listOf(1, 2, 3, 4)).any { isLessThan(0) } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L263) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L263) ↓ Output ```text expected that subject: [1, 2, 3, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains, in any order: @@ -1012,7 +1012,7 @@ expected that subject: [1, 2, 3, 4] (java.util.Arrays.ArrayList <1234789> ```kotlin expect(listOf(1, 2, 3, 4)).none { isGreaterThan(2) } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L266) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L266) ↓ Output ```text expected that subject: [1, 2, 3, 4] (java.util.Arrays.ArrayList <1234789>) ◆ does not contain: @@ -1030,7 +1030,7 @@ expected that subject: [1, 2, 3, 4] (java.util.Arrays.ArrayList <1234789> ```kotlin expect(listOf(1, 2, 3, 4)).all { isGreaterThan(2) } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L269) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L269) ↓ Output ```text expected that subject: [1, 2, 3, 4] (java.util.Arrays.ArrayList <1234789>) ◆ all entries: @@ -1059,7 +1059,7 @@ Following on the last section we will start with an `inOrder` example: ```kotlin expect(listOf(1, 2, 2, 4)).contains.inOrder.only.entries({ isLessThan(3) }, { isLessThan(2) }) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L273) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L273) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains only, in order: @@ -1109,7 +1109,7 @@ and we happily answer your question there. ```kotlin expect(listOf(1, 2, 2, 4)).contains.inOrder.only.values(1, 2, 2, 3, 4) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L276) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L276) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains only, in order: @@ -1133,7 +1133,7 @@ expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789> ```kotlin expect(listOf(1, 2, 2, 4)).contains.inAnyOrder.atLeast(1).butAtMost(2).entries({ isLessThan(3) }) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L279) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L279) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains, in any order: @@ -1149,7 +1149,7 @@ expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789> ```kotlin expect(listOf(1, 2, 2, 4)).contains.inAnyOrder.only.values(1, 2, 3, 4) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L282) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L282) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains only, in any order: @@ -1169,7 +1169,7 @@ expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789> ```kotlin expect(listOf(1, 2, 2, 4)).contains.inAnyOrder.only.values(4, 3, 2, 2, 1) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L285) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L285) ↓ Output ```text expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789>) ◆ contains only, in any order: @@ -1191,7 +1191,7 @@ expected that subject: [1, 2, 2, 4] (java.util.Arrays.ArrayList <1234789> ```kotlin expect(mapOf("a" to 1, "b" to 2)).contains("c" to 2, "a" to 1, "b" to 1) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L289) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L289) ↓ Output ```text expected that subject: {a=1, b=2} (java.util.LinkedHashMap <1234789>) ◆ contains, in any order: @@ -1217,7 +1217,7 @@ expect(mapOf("a" to 1, "b" to 2)).contains( KeyValue("b") { isLessThan(2) } ) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L292) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L292) ↓ Output ```text expected that subject: {a=1, b=2} (java.util.LinkedHashMap <1234789>) ◆ contains, in any order: @@ -1248,7 +1248,7 @@ expect(mapOf("bernstein" to bernstein)) feature { f(it::firstName) }.toBe("Albert") } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L304) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L304) ↓ Output ```text expected that subject: {bernstein=Person(firstName=Leonard, lastName=Bernstein, age=50)} (java.util.Collections.SingletonMap <1234789>) ◆ ▶ get("bernstein"): Person(firstName=Leonard, lastName=Bernstein, age=50) (readme.examples.ReadmeSpec2$1$Person <1234789>) @@ -1267,7 +1267,7 @@ expect(mapOf("a" to 1, "b" to 2)) { values { none { isGreaterThan(1) } } } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L316) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L316) ↓ Output ```text expected that subject: {a=1, b=2} (java.util.LinkedHashMap <1234789>) ◆ ▶ keys: [a, b] (java.util.LinkedHashMap.LinkedKeySet <1234789>) @@ -1303,7 +1303,7 @@ expect(linkedMapOf("a" to 1, "b" to 2)).asEntries().contains.inOrder.only.entrie } ) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L322) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L322) ↓ Output ```text expected that subject: {a=1, b=2} (java.util.LinkedHashMap <1234789>) ◆ contains only, in order: @@ -1327,7 +1327,7 @@ expected that subject: {a=1, b=2} (java.util.LinkedHashMap <1234789>) `isKeyValue` as well as `key` and `value` are assertion functions defined for `Map.Entry`. There are more assertion functions, a full list can be found in -[KDoc of atrium-api-fluent-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html). +[KDoc of atrium-api-fluent-en_GB](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html). In case you should miss an assertion function, then please [open a feature request](https://github.com/robstoll/atrium/issues/new?template=feature_request.md&title=[Feature]). @@ -1344,7 +1344,7 @@ For example, `exists` will explain which entry was the first one missing: ```kotlin expect(Paths.get("/usr/bin/noprogram")).exists() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L332) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L332) ↓ Output ```text expected that subject: /usr/bin/noprogram (sun.nio.fs.UnixPath <1234789>) ◆ to: exist @@ -1359,7 +1359,7 @@ Atrium will give details about why something cannot be accessed, for example whe ```kotlin expect(Paths.get("/root/.ssh/config")).isWritable() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L336) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L336) ↓ Output ```text expected that subject: /root/.ssh/config (sun.nio.fs.UnixPath <1234789>) ◆ is: writable @@ -1381,7 +1381,7 @@ val filePointer = Files.createSymbolicLink(directory.resolve("directory"), file) expect(filePointer.resolve("subfolder/file")).isRegularFile() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L341) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L341) ↓ Output ```text expected that subject: /tmp/atrium-path/directory/subfolder/file (sun.nio.fs.UnixPath <1234789>) ◆ is: a file @@ -1418,7 +1418,7 @@ expect("calling myFun with...") { } } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L354) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L354) ↓ Output ```text expected that subject: "calling myFun with..." <1234789> ◆ ▶ myFun(1): 'b' @@ -1452,7 +1452,7 @@ expect("calling myFun with ...") { } } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L368) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L368) ↓ Output ```text expected that subject: "calling myFun with ..." <1234789> ◆ ▶ myFun(3): 'd' @@ -1492,7 +1492,7 @@ expect("calling myNullableFun with ...") { } } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L386) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L386) ↓ Output ```text expected that subject: "calling myNullableFun with ..." <1234789> ◆ ▶ myNullableFun(-2147483648): null @@ -1510,20 +1510,20 @@ expected that subject: "calling myNullableFun with ..." <1234789> Atrium supports further assertion builders (e.g, for `CharSequence`) as well as assertion functions which have not been shown in the examples. -Have a look at [apis/differences.md](https://github.com/robstoll/atrium/tree/master/apis/differences.md) for a few more examples. +Have a look at [apis/differences.md](https://github.com/robstoll/atrium/tree/v0.13.0/apis/differences.md) for a few more examples. This site contains also a list of all APIs with links to their assertion function catalogs. You can also have a look at the -[specifications](https://github.com/robstoll/atrium/tree/master/misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs) +[specifications](https://github.com/robstoll/atrium/tree/v0.13.0/misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs) for more examples. # Sample Projects -Have a look into the [samples](https://github.com/robstoll/atrium/tree/master/samples) +Have a look into the [samples](https://github.com/robstoll/atrium/tree/v0.13.0/samples) folder, it currently contains sample projects for - [jvm](https://github.com/robstoll/atrium/tree/master/samples/jvm/), - [js](https://github.com/robstoll/atrium/tree/master/samples/js/) - as well as a [multiplatform project](https://github.com/robstoll/atrium/tree/master/samples/multiplatform/). + [jvm](https://github.com/robstoll/atrium/tree/v0.13.0/samples/jvm/), + [js](https://github.com/robstoll/atrium/tree/v0.13.0/samples/js/) + as well as a [multiplatform project](https://github.com/robstoll/atrium/tree/v0.13.0/samples/multiplatform/). Are you using a different runner? A PR would be appreciated 😊. @@ -1558,7 +1558,7 @@ We try to provide a workaround whenever possible._ There is, but IntelliJ will not show it to you due to [this bug](https://youtrack.jetbrains.com/issue/KT-24836) (please upvote it). You should be able to see the KDoc of other functions without problems. -But in case, you can also browse the online documentation, e.g. [KDoc of toBe](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.cc.en_-g-b/to-be.html). +But in case, you can also browse the online documentation, e.g. [KDoc of toBe](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.cc.en_-g-b/to-be.html). @@ -1631,7 +1631,7 @@ expect { } }.toThrow { messageContains("no no no") } ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L410) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L410) ↓ Output ```text expected that subject: () -> kotlin.Nothing (readme.examples.ReadmeSpec2$1$31$1 <1234789>) ◆ ▶ thrown exception when called: java.lang.IllegalArgumentException @@ -1673,7 +1673,7 @@ then Atrium reminds us of the possible pitfall. For instance: ```kotlin expect(BigDecimal.TEN).isEqualIncludingScale(BigDecimal("10.0")) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L420) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L420) ↓ Output ```text expected that subject: 10 (java.math.BigDecimal <1234789>) ◆ is equal (including scale): 10.0 (java.math.BigDecimal <1234789>) @@ -1690,7 +1690,7 @@ For instance: ```kotlin expect(listOf(1)).get(0) {} ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L423) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L423) ↓ Output ```text expected that subject: [1] (java.util.Collections.SingletonList <1234789>) ◆ ▶ get(0): 1 (kotlin.Int <1234789>) @@ -1766,7 +1766,7 @@ and its usage: ```kotlin expect(12).isMultipleOf(5) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L435) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L435) ↓ Output ```text expected that subject: 12 (kotlin.Int <1234789>) ◆ is multiple of: 5 (kotlin.Int <1234789>) @@ -1781,9 +1781,9 @@ Let us see how we actually defined `isMultipleOf`. the assertion to itself (creating alone is not enough, it needs to be added in order that it is evaluated). The method `createAndAddAssertion` returns itself (the same `Expect`) making it easy for you to provide a fluent API as well. - The method [createAndAddAssertion](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.creating/-assertion-plant/create-and-add-assertion.html) + The method [createAndAddAssertion](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.creating/-assertion-plant/create-and-add-assertion.html) expects: - - a either a `String` or a [Translatable](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.reporting.translating/-translatable/index.html) + - a either a `String` or a [Translatable](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.reporting.translating/-translatable/index.html) as description of your assertion. - the representation of the expected value. - and the actual check as lambda where you typically use `it` which refers to the subject of the assertion. @@ -1806,7 +1806,7 @@ fun Expect.isEven() = ``` -We are using a [Text](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.reporting/-text/index.html) +We are using a [Text](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.reporting/-text/index.html) here so that `"an even number"` is not treated as a `String` in reporting. Its usage looks then as follows: @@ -1815,7 +1815,7 @@ Its usage looks then as follows: ```kotlin expect(13).isEven() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L446) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L446) ↓ Output ```text expected that subject: 13 (kotlin.Int <1234789>) ◆ is: an even number @@ -1913,7 +1913,7 @@ Its usage is then as follows: expect(Person("Susanne", "Whitley", 43, listOf())) .hasNumberOfChildren(2) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L485) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L485) ↓ Output ```text expected that subject: Person(firstName=Susanne, lastName=Whitley, age=43, children=[]) (readme.examples.Person <1234789>) ◆ ▶ children: [] (kotlin.collections.EmptyList <1234789>) @@ -1946,7 +1946,7 @@ but we do not have to, as `all` already checks that there is at least one elemen expect(Person("Susanne", "Whitley", 43, listOf())) .hasAdultChildren() ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L500) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L500) ↓ Output ```text expected that subject: Person(firstName=Susanne, lastName=Whitley, age=43, children=[]) (readme.examples.Person <1234789>) ◆ ▶ children: [] (kotlin.collections.EmptyList <1234789>) @@ -1987,7 +1987,7 @@ expect(Person("Susanne", "Whitley", 43, listOf(Person("Petra", "Whitley", 12, li .children // using the val -> subsequent assertions are about children and fail fast .hasSize(2) ``` -↑ [Example](https://github.com/robstoll/atrium/tree/master/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L510) ↓ Output +↑ [Example](https://github.com/robstoll/atrium/tree/v0.13.0/samples/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt#L510) ↓ Output ```text expected that subject: Person(firstName=Susanne, lastName=Whitley, age=43, children=[Person(firstName=Petra, lastName=Whitley, age=12, children=[])]) (readme.examples.Person <1234789>) ◆ ▶ children: [Person(firstName=Petra, lastName=Whitley, age=12, children=[])] (java.util.Collections.SingletonList <1234789>) @@ -2048,7 +2048,7 @@ fun >> Expect.sameInitialsAs( There are a few additional methods which you can call after `mapArguments`. -See [KDoc of ArgumentMapperBuilder](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.domain.builders.utils/-argument-mapper-builder/index.html). +See [KDoc of ArgumentMapperBuilder](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.domain.builders.utils/-argument-mapper-builder/index.html). In case you want to provide your own implementation it suffices to create an extension function for `ArgumentMapperBuilder`. @@ -2058,20 +2058,20 @@ extension function for `ArgumentMapperBuilder`. Yet, sometimes we would like to create functions which have a better error reporting than the one we get when we compose assertion functions. -[`_logic`](https://github.com/robstoll/atrium/tree/master/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/logic.kt#L21) +[`_logic`](https://github.com/robstoll/atrium/tree/v0.13.0/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/logic.kt#L21) is the entry point to `AssertionContainer` which is the equivalent of `Expect` but on a lower level. Following a quick overview what extension methods could be useful: - all assertion functions on the logic level (what you have seen in [Compose-assertion-functions](#compose-assertion-functions) was the API level) so that you can reuse and compose them in other ways. - `changeSubject` which allows to change the subject either: - - `unreported`; meaning it does not show up in reporting (e.g. `Expect>.asList()` uses it, see [arrayAssertions](https://github.com/robstoll/atrium/tree/master/apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/arrayAssertions.kt#L19)) - - reported, using `reportBuilder`; meaning a subject transformation which is shown in reporting as it incorporates a transformation (e.g. `isA` uses it, see [AnyAssertions](https://github.com/robstoll/atrium/tree/master/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultAnyAssertions.kt#L52)) -- `collect` which allows to collect assertions - especially helpful in composing assertions (see [mapAssertions](https://github.com/robstoll/atrium/tree/master/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultMapAssertions.kt#L49)) -- `extractFeature` for feature assertions which are not always save to extract (see [`List.get`](https://github.com/robstoll/atrium/tree/master/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultListAssertions.kt#L13)) + - `unreported`; meaning it does not show up in reporting (e.g. `Expect>.asList()` uses it, see [arrayAssertions](https://github.com/robstoll/atrium/tree/v0.13.0/apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/arrayAssertions.kt#L19)) + - reported, using `reportBuilder`; meaning a subject transformation which is shown in reporting as it incorporates a transformation (e.g. `isA` uses it, see [AnyAssertions](https://github.com/robstoll/atrium/tree/v0.13.0/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultAnyAssertions.kt#L52)) +- `collect` which allows to collect assertions - especially helpful in composing assertions (see [mapAssertions](https://github.com/robstoll/atrium/tree/v0.13.0/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultMapAssertions.kt#L49)) +- `extractFeature` for feature assertions which are not always save to extract (see [`List.get`](https://github.com/robstoll/atrium/tree/v0.13.0/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultListAssertions.kt#L13)) Besides, the `assertionBuilder` allows to create different kinds of assertions -(see [AssertionBuilder](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.assertions.builders/-assertion-builder/index.html) for more information) +(see [AssertionBuilder](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.assertions.builders/-assertion-builder/index.html) for more information) which can be used to create very specific assertion functions. You can find an example in [floatingPointAssertions](https://github.com/robstoll/atrium/blob/master/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultFloatingPointAssertions.kt#L72) @@ -2086,7 +2086,7 @@ Unfortunately we do not have the time to cover all cases, so let us know if you Do you want to write an own sophisticated assertion builder (or extend a current with more options) instead of an assertion function? Great, we do not provide documentation yet (had only one question about it so far). Therefore, please have a look at the implementation, for instance how the sophisticated assertion builders for `Iterable` are defined: -[ch.tutteli.atrium.creating.iterable.contains](https://github.com/robstoll/atrium/tree/master/domain/api/atrium-domain-api-common/src/main/kotlin/ch/tutteli/atrium/domain/creating/iterable/contains). +[ch.tutteli.atrium.creating.iterable.contains](https://github.com/robstoll/atrium/tree/v0.13.0/domain/api/atrium-domain-api-common/src/main/kotlin/ch/tutteli/atrium/domain/creating/iterable/contains). Notice that the implementation supports [Internationalization](#internationalization-1). We are willing to provide more documentation if you need it (please open an issue). @@ -2100,7 +2100,7 @@ Atrium offers three assertion verbs out of the box: `expect`, `assert` and `asse But you can also define your own set of assertion verbs if they do not suite you or if you do not want that all of them are available in your classpath. In order to create an own assertion verb it is sufficient to: - 1. Copy the file content of [atriumVerbs.kt](https://github.com/robstoll/atrium/tree/master/misc/verbs-internal/atrium-verbs-internal-common/src/main/kotlin/ch.tutteli.atrium.api.verbs.internal/atriumVerbs.kt) + 1. Copy the file content of [atriumVerbs.kt](https://github.com/robstoll/atrium/tree/v0.13.0/misc/verbs-internal/atrium-verbs-internal-common/src/main/kotlin/ch.tutteli.atrium.api.verbs.internal/atriumVerbs.kt) 2. Create your own atriumVerbs.kt and paste the previously copied content -- notice that you can also use a `String` for the assertion verb in case you do not care about [Internationalization](#internationalization-1) 3. Adjust package name and `import`s and rename `expect` as desired (you can also leave it that way of course). @@ -2141,7 +2141,7 @@ What are the drawbacks: The `ReporterBuilder` lets you choose among different options to configure the style of the reporting. For instance, in case you are not happy with the predefined bullet points, then you can change them via the `ReporterBuilder`. -Have a look at [atriumVerbs.kt of atrium-api-infix-en_GB](https://github.com/robstoll/atrium/tree/master/apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/infix/en_GB/testutils/AsciiBulletPointReporterFactory.kt) +Have a look at [atriumVerbs.kt of atrium-api-infix-en_GB](https://github.com/robstoll/atrium/tree/v0.13.0/apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/infix/en_GB/testutils/AsciiBulletPointReporterFactory.kt) where you can find an example. Or if you prefer multi-line reporting over single-line reporting, @@ -2174,7 +2174,7 @@ You can provide your custom configured `Reporter` by providing a `ReporterFactor This is done via [ServiceLoader](https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html) -mechanism on JVM and by calling `registerService` on JS where the call has to be before your tests run. An example for JVM is given in [AsciiBulletPointReporterFactory](https://github.com/robstoll/atrium/blob/master/misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs/testutils/AsciiBulletPointReporterFactory.kt). -An example of how you can make sure your code is called earlier than the tests run is given in [testSetup.kt of atrium-core-robstoll-lib](https://github.com/robstoll/atrium/tree/master/core/robstoll-lib/atrium-core-robstoll-lib-js/src/test/kotlin/testSetup.kt). +An example of how you can make sure your code is called earlier than the tests run is given in [testSetup.kt of atrium-core-robstoll-lib](https://github.com/robstoll/atrium/tree/v0.13.0/core/robstoll-lib/atrium-core-robstoll-lib-js/src/test/kotlin/testSetup.kt). # Internationalization @@ -2204,24 +2204,24 @@ enum class DescriptionIntAssertion(override val value: String) : StringBasedTran Typically you would put `DescriptionIntAssertion` into an own module (jar) so that it could be replaced (with zero performance cost) by another language representation. For instance, -[atrium-fluent-en_GB-common](https://github.com/robstoll/atrium/tree/master/bundles/fluent-en_GB/atrium-fluent-en_GB-common/build.gradle) +[atrium-fluent-en_GB-common](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/fluent-en_GB/atrium-fluent-en_GB-common/build.gradle) uses `atrium-translations-en_GB-common` whereas tests of -[atrium-infix_en_GB-common](https://github.com/robstoll/atrium/tree/master/bundles/infix-en_GB/atrium-infix-en_GB-common/build.gradle) +[atrium-infix_en_GB-common](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/infix-en_GB/atrium-infix-en_GB-common/build.gradle) uses `atrium-translations-de_CH-common`.
💬 Using a TranslationSupplier Next to providing translations via code you can also use a -[TranslationSupplier](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.reporting.translating/-translation-supplier/index.html) -based [Translator](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.reporting.translating/-translator/index.html) +[TranslationSupplier](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.reporting.translating/-translation-supplier/index.html) +based [Translator](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.reporting.translating/-translator/index.html) by configuring the [`ReporterBuilder`](#reporterbuilder) accordingly (e.g. use `withDefaultTranslationSupplier` instead of `withoutTranslations`). Atrium supports a properties files based `TranslationSupplier` for JVM (a supplier for JS will follow) which is more or less what [ResourceBundle](https://docs.oracle.com/javase/tutorial/i18n/resbundle/propfile.html) provides out of the box. Yet, a `Translator` uses a more enhanced fallback mechanism compared to a `ResourceBundle`. -For further technical information have a look at the KDoc of [Translator](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.reporting.translating/-translator/index.html). +For further technical information have a look at the KDoc of [Translator](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.reporting.translating/-translator/index.html). Notice though, that we plan to move away from the `ResourceBundle`-inspired approach due to enconding problems and missing implementations on other platforms than JVM. @@ -2263,7 +2263,7 @@ We split up the function in two parts: API and logic merely appends the assertion created by the logic to the `Expect`. Typically, you put the API function in one module (jar) and the logic in another (so that the API can be exchanged). -In the logic module we define and extension method for [AssertionContainer](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.creating/-assertion-container/index.html) +In the logic module we define and extension method for [AssertionContainer](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.creating/-assertion-container/index.html) @@ -2275,7 +2275,7 @@ fun AssertionContainer.isMultipleOf(base: Int): Assertion = ``` -In the above example we created a simple [DescriptiveAssertion](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.assertions/-descriptive-assertion/index.html) +In the above example we created a simple [DescriptiveAssertion](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.assertions/-descriptive-assertion/index.html) with the help of `createDescriptiveAssertion` defined on AssertionContainer. We pass in a description (`IS_MULTIPLE_OF`), use `base` as representation of the assertion and defined a lambda which implements a test to define whether the assertion holds or not. @@ -2315,17 +2315,17 @@ Both have their design focus on interoperability with code completion functional -- so that you can let your IDE do some of the work. Atrium is -[built up by different modules](https://docs.atriumlib.org/latest#/doc/) +[built up by different modules](https://docs.atriumlib.org/0.13.0/doc/) and it is your choice which implementation you want to use. However, this is more intended for advanced user with special requirements. Atrium provides bundle modules which bundle API, logic, core, translation as well as predefined assertion verbs, so that you just have to have a dependency on one of those bundles (kind a bit like a BOM pom in the maven world): -- [atrium-fluent-en_GB](https://github.com/robstoll/atrium/tree/master/bundles/fluent-en_GB/atrium-fluent-en_GB-common/build.gradle) -- [atrium-infix-en_GB](https://github.com/robstoll/atrium/tree/master/bundles/infix-en_GB/atrium-infix-en_GB-common/build.gradle) +- [atrium-fluent-en_GB](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/fluent-en_GB/atrium-fluent-en_GB-common/build.gradle) +- [atrium-infix-en_GB](https://github.com/robstoll/atrium/tree/v0.13.0/bundles/infix-en_GB/atrium-infix-en_GB-common/build.gradle) Have a look at -[apis/differences.md](https://github.com/robstoll/atrium/tree/master/apis/differences.md) +[apis/differences.md](https://github.com/robstoll/atrium/tree/v0.13.0/apis/differences.md) for more information and to see how the API styles differ. @@ -2340,15 +2340,15 @@ Therefore you want to turn the platform type into the nullable version. You need to use a cast to do this. But depending on your return type this might be cumbersome especially if you deal with type parameters. Thus, Atrium provides the following functions to ease dealing with Java Code at least for some standard cases: -- [`nullable`](https://github.com/robstoll/atrium/tree/master/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L19) +- [`nullable`](https://github.com/robstoll/atrium/tree/v0.13.0/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L19) turns a type into a nullable type. -- [`nullableContainer`](https://github.com/robstoll/atrium/tree/master/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L40) +- [`nullableContainer`](https://github.com/robstoll/atrium/tree/v0.13.0/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L40) turns an `Iterable` into an iterable with nullable element type, likewise it does the same for `Array`. -- [`nullableKeyMap`](https://github.com/robstoll/atrium/tree/master/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L66) +- [`nullableKeyMap`](https://github.com/robstoll/atrium/tree/v0.13.0/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L66) turns a `Map` into a map with a nullable key type. -- [`nullableValueMap`](https://github.com/robstoll/atrium/tree/master/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L79) +- [`nullableValueMap`](https://github.com/robstoll/atrium/tree/v0.13.0/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L79) turns a `Map` into a map with a nullable value type. -- [`nullableKeyValueMap`](https://github.com/robstoll/atrium/tree/master/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L92) +- [`nullableKeyValueMap`](https://github.com/robstoll/atrium/tree/v0.13.0/domain/builders/atrium-domain-builders-common/src/main/kotlin/ch/tutteli/atrium/domain/builders/utils/nullable.kt#L92) turns a `Map` into a map with a nullable key and nullable value type. @@ -2404,14 +2404,14 @@ expect(sequenceOf(1, 2, 3)).feature { f(it::asIterable) }.contains(2) ## Where do I find a list of all available functions? Atrium provides KDoc for all APIs - have a look at their KDoc: -- [atrium-api-fluent-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html) -- [atrium-api-infix-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.infix.en_-g-b/index.html) +- [atrium-api-fluent-en_GB](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html) +- [atrium-api-infix-en_GB](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.infix.en_-g-b/index.html) Deprecated APIs: -- [atrium-api-cc-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.cc.en_-g-b/index.html) -- [atrium-api-cc-en_UK](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.cc.en_-u-k/index.html) -- [atrium-api-cc-de_CH](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.cc.de_-d-e/index.html) -- [atrium-api-cc-infix-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.cc.infix.en_-g-b/index.html) +- [atrium-api-cc-en_GB](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.cc.en_-g-b/index.html) +- [atrium-api-cc-en_UK](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.cc.en_-u-k/index.html) +- [atrium-api-cc-de_CH](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.cc.de_-d-e/index.html) +- [atrium-api-cc-infix-en_GB](https://docs.atriumlib.org/0.13.0/doc/ch.tutteli.atrium.api.cc.infix.en_-g-b/index.html) ## Problems in conjunction with `feature` @@ -2447,7 +2447,7 @@ You are more than welcome to contribute as well: if you would like to code (ping us on [Slack](https://kotlinlang.slack.com/messages/C887ZKGCQ) if there are not any). Please have a look at -[CONTRIBUTING.md](https://github.com/robstoll/atrium/tree/master/.github/CONTRIBUTING.md) +[CONTRIBUTING.md](https://github.com/robstoll/atrium/tree/v0.13.0/.github/CONTRIBUTING.md) for further suggestions and guidelines. # Sponsors diff --git a/apis/differences.md b/apis/differences.md index bd20f97810..023bad654e 100644 --- a/apis/differences.md +++ b/apis/differences.md @@ -14,13 +14,13 @@ These modules bundle: Following a list of the available bundle-modules. The links point to the KDoc of their included API where you find an overview of all available assertion functions of the API. -- [atrium-fluent-en_GB](https://robstoll.github.io/atrium/latest#/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html) -- [atrium-infix-en_GB](https://robstoll.github.io/atrium/latest#/doc/ch.tutteli.atrium.api.infix.en_-g-b/index.html) +- [atrium-fluent-en_GB](https://robstoll.github.io/atrium/0.13.0/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html) +- [atrium-infix-en_GB](https://robstoll.github.io/atrium/0.13.0/doc/ch.tutteli.atrium.api.infix.en_-g-b/index.html) ---- Following an excerpt of a build.gradle file which uses twit APIs (see -[README#Installation](https://github.com/robstoll/atrium/tree/master/README.md#installation) +[README#Installation](https://github.com/robstoll/atrium/tree/v0.13.0/README.md#installation) for the rest): ``` dependencies { diff --git a/build.gradle b/build.gradle index 723b040cd8..831f025f22 100644 --- a/build.gradle +++ b/build.gradle @@ -1,5 +1,5 @@ buildscript { - rootProject.version = '0.13.0-SNAPSHOT' + rootProject.version = '0.13.0' rootProject.group = 'ch.tutteli.atrium' def toolProjectsFun = subprojects.findAll { @@ -44,7 +44,7 @@ buildscript { ghPages_version = rootProject.version srcKotlin = 'src/main/kotlin' github_url = "https://github.com/robstoll/${rootProject.name}" - dokka_sourceMapping = "tree/master" + dokka_sourceMapping = "tree/v0.13.0" toolProjects = toolProjectsFun