jlengrand/atrium
1
0
Fork 0
mirror of https://github.com/jlengrand/atrium.git synced 2026-03-10 08:01:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

use expectation instead of assertion in .md files

Browse Source
This commit is contained in:
Robert Stoll
2021-01-14 23:01:32 +01:00
parent 617f8138fc
commit d286111454
5 changed files with 316 additions and 316 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.github/CONTRIBUTING.md vendored
View File

@@ -31,14 +31,14 @@ By participating, you are expected to uphold this code. Please report unacceptab
- Missing a feature?
[Create a feature request](https://github.com/robstoll/atrium/issues/new?template=feature_request.md&title=[Feature]).
- You would like to write an assertion function but you're having trouble starting?
- You would like to write an expectation function but you are having trouble starting?
Please read the section [Your First Code Contribution](#your-first-code-contribution).
If you still have trouble starting, then contact us on
[slack](https://kotlinlang.slack.com/messages/D3CL4DDLG/)
([Invite yourself](https://slack.kotlinlang.org/) in case you do not have an account yet)
and we will try to give you some additional hints.
- You do not have a particular assertion function in mind but would like to contribute with code?
- You do not have a particular expectation function in mind but would like to contribute with code?
Please have a look at the [help wanted issues](https://github.com/robstoll/atrium/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
-- ping us on
[Slack](https://kotlinlang.slack.com/messages/C887ZKGCQ)
@@ -54,7 +54,7 @@ By participating, you are expected to uphold this code. Please report unacceptab
- Found spelling mistakes?
Nice catch :mag: Please fix it and create a pull request.
- You wrote an assertion function and would like to contribute it to Atrium?
- You wrote an expectation function and would like to contribute it to Atrium?
Awesome :+1: please review the [pull request checklist](#pull-request-checklist) and create a pull request
- You would like to support the project financially?

536
README.md
View File

File diff suppressed because it is too large Load Diff

18
apis/differences.md
View File

@@ -12,7 +12,7 @@ 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.
The links point to the KDoc of their included API where you find an overview of all available expectation functions of the API.
- [atrium-fluent-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.fluent.en_-g-b/index.html)
- [atrium-infix-en_GB](https://docs.atriumlib.org/latest#/doc/ch.tutteli.atrium.api.infix.en_-g-b/index.html)
@@ -39,7 +39,7 @@ If you forget to dit it, then the compiler will complain that you have the same
Atrium currently provides two API styles: fluent and infix.
We dit not show every single difference but merely where the APIs differ in naming.
For instance, the assertion function `Expect<T>.toBe`:
For instance, the expectation function `Expect<T>.toBe`:
*atrium-api-fluent-en_GB*
```kotlin
@@ -60,7 +60,7 @@ is toit similar, we will not list it here (ok, we did now but I guess you get th
- [in any order](#iterable-contains-in-any-order)
- [in order](#iterable-contains-in-order)
- [Iterable contains not](#iterable-contains-not)
- [Iterable predicate-like assertions](#iterable-predicate-like-assertions)
- [Iterable predicate-like expectations](#iterable-predicate-like-expectations)
- [List get](#list-get)
- [Map getExisting](#map-getexisting)
- [Map contains](#map-contains)
@@ -111,7 +111,7 @@ expect(x).contains.ignoringCase.notOrAtMost(1).elementsOf(anIterable)
```
Notice that the final steps
`value`, `values` and `regex`
in the sophisticated assertion building process
in the sophisticated expectation building process
are applicable to all shown examples
(e.g. `exactly(1).values("hello", "robert")` could have been finished with `exactly(1).regex("h(e|a)llo")` as well).
@@ -128,7 +128,7 @@ expect(x) contains o ignoring case notOrAtMost 1 elementsOf anIterable
```
Notice that the final steps
`value`, `values(...)`, `regex` and `regexPatterns(..)`
in the sophisticated assertion building process
in the sophisticated expectation building process
are applicable to all shown examples
(e.g. `exactly 1 values("hello", "robert")` could have been finished with `exactly 1 regex "h(e|a)llo"` as well).
@@ -154,7 +154,7 @@ expect(x).contains.inAnyOrder.only.entries({ toBe(3) }, { isLessThan(2) })
```
Notice that the final steps
`value`, `values`, `entry` and `entries`
in the sophisticated assertion building process
in the sophisticated expectation building process
are applicable to all shown examples
(e.g. `butAtMost(2).value(3.2)` could have been finished with `entries(...)` as well)
@@ -178,7 +178,7 @@ Note that `o` is a filler object which is only there so that we can turn extensi
a method with one parameter and thus make it available as infix method.
The final steps `value`, `values(...)`, `entry` and `entries(...)`
in the sophisticated assertion building process,
in the sophisticated expectation building process,
are applicable to all shown examples
(e.g. `butAtMost 2 value 3.2` could have been finished with `entries(...)` as well)
@@ -257,8 +257,8 @@ expect(x) containsNot o entry { it isLessThan 2 }
expect(x) containsNot o the entries(null, { it isLessThan 2 }, { it isGreaterThan 5 })
```
# Iterable predicate-like assertions
For more sophisticated assertions such as "there should be two matches", use the sophisticated assertion builder `contains.inAnyOrder`
# Iterable predicate-like expectations
For more sophisticated expectations such as "there should be two matches", use the sophisticated expectation builder `contains.inAnyOrder`
-&gt; see [Iterable contains in any order](#iterable-contains-in-any-order) for more information
*atrium-api-fluent-en_GB*

4
core/api/atrium-core-api-common/src/main/kotlin/ch/tutteli/atrium/creating/Expect.kt
View File

@@ -89,7 +89,7 @@ interface Expect<T> : @kotlin.Suppress("DEPRECATION") SubjectProvider<T> {
*
* @return An [Expect] for the current subject of the assertion.
*/
//TODO 0.16.0 move to AssertionContainer and deprecate
//TODO 0.16.0 move to AssertionContainer and deprecate, update README
fun createAndAddAssertion(description: String, expected: Any?, test: (T) -> Boolean): Expect<T> =
createAndAddAssertion(Untranslatable(description), expected, test)
@@ -103,7 +103,7 @@ interface Expect<T> : @kotlin.Suppress("DEPRECATION") SubjectProvider<T> {
*
* @return An [Expect] for the current subject of the assertion.
*/
//TODO 0.16.0 move to AssertionContainer and deprecate
//TODO 0.16.0 move to AssertionContainer and deprecate, update README
fun createAndAddAssertion(description: Translatable, expected: Any?, test: (T) -> Boolean): Expect<T> =
addAssertion(assertionBuilder.createDescriptive(this, description, expected, test))
}

68
misc/tools/readme-examples/src/main/kotlin/readme/examples/ReadmeSpec.kt
View File

@@ -59,12 +59,12 @@ class ReadmeSpec : Spek({
}
test("ex-single") {
// two single assertions, only first evaluated
// two single expectations, only first evaluated
expect(4 + 6).isLessThan(5).isGreaterThan(10)
}
test("ex-group") {
// assertion group with two assertions, both evaluated
// expectation group with two expectations, both evaluated
expect(4 + 6) {
isLessThan(5)
isGreaterThan(10)
@@ -121,14 +121,14 @@ class ReadmeSpec : Spek({
//@formatter:off
test("ex-property-methods-group") {
expect(myPerson) { // forms an assertion group block
expect(myPerson) { // forms an expectation group block
feature({ f(it::firstName) }) { // forms an assertion group block
feature({ f(it::firstName) }) { // forms an expectation group block
startsWith("Pe") // fails
endsWith("er") // is evaluated nonetheless
} // fails as a whole
// still evaluated, as it is in outer assertion group block
// still evaluated, as it is in outer expectation group block
feature { f(it::lastName) }.toBe("Dummy")
}
}
@@ -167,7 +167,7 @@ class ReadmeSpec : Spek({
feature(Pair<F, *>::first) { toBe(expected) }
//snippet-within-funs-end
test("ex-within-assertion-functions") {
test("ex-within-expectation-functions") {
//snippet-within-funs-insert
expect(listOf(1 to "a", 2 to "b")).get(10) {
@@ -200,13 +200,13 @@ class ReadmeSpec : Spek({
}
test("ex-type-assertions-1") {
//snippet-type-assertions-insert
test("ex-type-expectations-1") {
//snippet-type-expectations-insert
expect(x).isA<SubType1>()
.feature { f(it::number) }
.toBe(2)
}
test("ex-type-assertions-2") {
test("ex-type-expectations-2") {
expect(x).isA<SubType2> {
feature { f(it::word) }.toBe("goodbye")
feature { f(it::flag) }.toBe(false)
@@ -215,14 +215,14 @@ class ReadmeSpec : Spek({
})
//@formatter:off
//snippet-type-assertions-start
//snippet-type-expectations-start
interface SuperType
data class SubType1(val number: Int) : SuperType
data class SubType2(val word: String, val flag: Boolean) : SuperType
val x: SuperType = SubType2("hello", flag = true)
//snippet-type-assertions-end
//snippet-type-expectations-end
//@formatter:on
object ReadmeSpec2 : Spek({
@@ -233,12 +233,12 @@ object ReadmeSpec2 : Spek({
}
test("ex-nullable-1") {
val slogan1: String? = "postulating assertions made easy"
val slogan1: String? = "postulating expectations made easy"
expect(slogan1).toBe(null)
}
test("ex-nullable-2") {
val slogan2: String? = null
expect(slogan2).toBe("postulating assertions made easy")
expect(slogan2).toBe("postulating expectations made easy")
}
val slogan2: String? = null
test("ex-nullable-3") {
@@ -401,8 +401,8 @@ object ReadmeSpec2 : Spek({
1 to expectLambda<Char> { isLessThan('f') },
2 to expectLambda { toBe('c') },
3 to expectLambda { isGreaterThan('e') }
).forEach { (arg, assertionCreator) ->
feature({ f(::myFun, arg) }, assertionCreator)
).forEach { (arg, expectationCreator) ->
feature({ f(::myFun, arg) }, expectationCreator)
}
}
}
@@ -422,8 +422,8 @@ object ReadmeSpec2 : Spek({
1 to expectLambda { toBe("1") },
2 to expectLambda { endsWith("2") },
Int.MAX_VALUE to expectLambda { toBe("max") }
).forEach { (arg, assertionCreatorOrNull) ->
feature { f(::myNullableFun, arg) }.toBeNullIfNullGivenElse(assertionCreatorOrNull)
).forEach { (arg, expectationCreatorOrNull) ->
feature { f(::myNullableFun, arg) }.toBeNullIfNullGivenElse(expectationCreatorOrNull)
}
}
}
@@ -537,16 +537,16 @@ object OwnPerson : Spek({
//@formatter:off
test("ex-own-compose-5"){
expect(Person("Susanne", "Whitley", 43, listOf(Person("Petra", "Whitley", 12, listOf()))))
.children { // using the fun -> assertion group, ergo sub-assertions don't fail fast
.children { // using the fun -> expectation group, ergo sub-expectations don't fail fast
none { feature { f(it::firstName) }.startsWith("Ro") }
all { feature { f(it::lastName) }.toBe("Whitley") }
} // subject is still Person here
.apply { // only evaluated because the previous assertion group holds
children // using the val -> subsequent assertions are about children and fail fast
.apply { // only evaluated because the previous expectation group holds
children // using the val -> subsequent expectations are about children and fail fast
.hasSize(2)
.any { feature { f(it::age) }.isGreaterThan(18) }
} // subject is still Person here due to the `apply`
.children // using the val -> subsequent assertions are about children and fail fast
.children // using the val -> subsequent expectations are about children and fail fast
.hasSize(2)
}
//@formatter:on
@@ -592,8 +592,8 @@ data class Person(
//snippet-children-start
val Expect<Person>.children: Expect<Collection<Person>> get() = feature(Person::children)
fun Expect<Person>.children(assertionCreator: Expect<Collection<Person>>.() -> Unit): Expect<Person> =
feature(Person::children, assertionCreator)
fun Expect<Person>.children(expectationCreator: Expect<Collection<Person>>.() -> Unit): Expect<Person> =
feature(Person::children, expectationCreator)
//snippet-children-end
@@ -601,21 +601,21 @@ object I18n : Spek({
test("code-i18n-1") {
fun Expect<Int>.isMultipleOf(base: Int): Expect<Int> =
createAndAddAssertion(DescriptionIntAssertion.IS_MULTIPLE_OF, base) { it % base == 0 }
createAndAddAssertion(DescriptionIntExpectation.IS_MULTIPLE_OF, base) { it % base == 0 }
//snippet-DescriptionIntAssertion-insert
//snippet-DescriptionIntExpectation-insert
}
test("code-i18n-2") {
fun Expect<Int>.isEven(): Expect<Int> =
createAndAddAssertion(DescriptionBasic.IS, DescriptionIntAssertions.EVEN) { it % 2 == 0 }
createAndAddAssertion(DescriptionBasic.IS, DescriptionIntExpectations.EVEN) { it % 2 == 0 }
//snippet-DescriptionIntAssertions-insert
//snippet-DescriptionIntExpectations-insert
}
//snippet-i18n-3a-start
fun AssertionContainer<Int>.isMultipleOf(base: Int): Assertion =
createDescriptiveAssertion(DescriptionIntAssertion.IS_MULTIPLE_OF, base) { it % base == 0 }
createDescriptiveAssertion(DescriptionIntExpectation.IS_MULTIPLE_OF, base) { it % base == 0 }
//snippet-i18n-3a-end
test("code-i18n-3a") {
@@ -637,18 +637,18 @@ object I18n : Spek({
}
})
//snippet-DescriptionIntAssertion-start
enum class DescriptionIntAssertion(override val value: String) : StringBasedTranslatable {
//snippet-DescriptionIntExpectation-start
enum class DescriptionIntExpectation(override val value: String) : StringBasedTranslatable {
IS_MULTIPLE_OF("is multiple of")
}
//snippet-DescriptionIntAssertion-end
//snippet-DescriptionIntExpectation-end
//snippet-DescriptionIntAssertions-start
enum class DescriptionIntAssertions(override val value: String) : StringBasedTranslatable {
//snippet-DescriptionIntExpectations-start
enum class DescriptionIntExpectations(override val value: String) : StringBasedTranslatable {
EVEN("an even number")
}
//snippet-DescriptionIntAssertions-end
//snippet-DescriptionIntExpectations-end
object Faq : Spek({
test("code-faq-1") {