atrium/apis/differences.md

List of APIs

Atrium provides different APIs where the API differ in its style and the language in which it is written. You have the choice which one(s) you want to use. Hence it is up to you if you want to mix and match different styles or enforce just one style.

Atrium provides so called bundle-modules which merely bundle dependencies (they do not provide additional functionality). These modules bundle:

• an API module
• a translation module (the language used in reporting)
• an implementation of the domain of Atrium
• an implementation of the core of Atrium

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
• atrium-infix-en_GB

---

Following an excerpt of a build.gradle file which uses twit APIs (see README#Installation for the rest):

dependencies {
    testCompile "ch.tutteli:atrium-fluent-en_GB:$atrium_version"
    testCompile "ch.tutteli:atrium-api-infix-en_GB:$atrium_version"
}

The first dependency points to a bundle-module, the second one just adds the infix-API in addition.

⚠️ if you want to use the same API in different languages, then you have to make sure that you exclude all translation modules but one (I suggest you keep the one which is your primary language). If you forget to dit it, then the compiler will complain that you have the same enums multiple times on your classpath.

Different API styles

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:

atrium-api-fluent-en_GB

expect(x).toBe(2)

atrium-api-infix-en_GB

expect(x) toBe 2

is toit similar, we will not list it here (ok, we did now but I guess you get the point).

Table of Content

• Empty CharSequence / Collection
• and property
• CharSequence contains
• Iterable contains
  • in any order
  • in order
• Iterable contains not
• Iterable predicate-like assertions
• List get
• Map getExisting
• Map contains

Empty CharSequence / Collection

atrium-api-fluent-en_GB

expect(x).isEmpty()
expect(x).isNotEmpty()

atrium-api-infix-en_GB

expect(x) toBe empty
expect(x) notToBe empty

and property

atrium-api-fluent-en_GB

expect(x).isGreaterThan(1).and.isLessThan(10)
expect(x) { /*...*/ } and { /*...*/ }

atrium-api-infix-en_GB

expect(x) isGreaterThan 1 and o isLessThan 10
expect(x) { /*...*/ } and { /*...*/ }

Note that o is a filler object which is only there so that we can turn extension methods without parameters into a method with one parameter and thus make it available as infix method.

CharSequence contains

atrium-api-fluent-en_GB

expect(x).contains("hello", "world")
expect(x).contains.atLeast(1).butAtMost(2).value("hello")
expect(x).contains.exactly(1).values("hello", "robert")
expect(x).contains.atMost(2).regex("h(e|a)llo")
expect(x).contains.atMost(2).regex(Regex("h(e|a)llo"))
expect(x).contains.ignoringCase.regex("h(e|a)llo", "[Rr]obert")
expect(x).contains.ignoringCase.notOrAtMost(1).elementsOf(anIterable)

Notice that the final steps value, values and regex in the sophisticated assertion 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).

atrium-api-infix-en_GB

expect(x) contains values("hello", "world")
expect(x) contains o atLeast 1 butAtMost 2 value "hello"
expect(x) contains o exactly 1 the values("hello", "robert")
expect(x) contains o atMost 2 regex "h(e|a)llo"
expect(x) contains o atMost 2 matchFor Regex("h(e|a)llo")
expect(x) contains o ignoring case notOrAtMost 1 the regexPatterns("h(e|a)llo", "[Rr]obert")
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 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).

Iterable contains

Iterable contains in any order

atrium-api-fluent-en_GB

expect(x).contains(1.2)
expect(x).contains(1.2, 5.7)
expect(x).contains { isLessThan(2) }
expect(x).contains({ isLessThan(2) }, { isGreaterThan(5) })

expect(x).contains.inAnyOrder.atLeast(1).butAtMost(2).value(3.2)
expect(x).contains.inAnyOrder.exactly(1).values("hello", "robert")
expect(x).contains.inAnyOrder.atMost(2).entry { isLessOrEquals(2) }
expect(x).contains.inAnyOrder.notOrAtMost(2).entries({ notToBe(3) }, { isGreaterOrEquals(2) })
expect(x).contains.inAnyOrder.only.value("hello")
expect(x).contains.inAnyOrder.only.values(personA, personB)
expect(x).contains.inAnyOrder.only.entry { isLessThan(2) }
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 are applicable to all shown examples (e.g. butAtMost(2).value(3.2) could have been finished with entries(...) as well)

atrium-api-infix-en_GB

expect(x) contains 1.2
expect(x) contains values(1.2, 5.7) // or Objects as alternative
expect(x) contains { it isLessThan 2 }
expect(x) contains entries({ it isLessThan 2 }, { it isGreaterThan 5 })

expect(x) contains o inAny order atLeast 1 butAtMost 2 value 3.2
expect(x) contains o inAny order exactly 1 the values("hello", "robert")
expect(x) contains o inAny order atMost 2 entry { it isLessOrEquals 2 }
expect(x) contains o inAny order notOrAtMost 2 the entries({ it notToBe 3 }, { it isGreaterOrEquals 2 })
expect(x) contains o inAny order but only value "hello"
expect(x) contains o inAny order but only the values(personA, personB)
expect(x) contains o inAny order but only entry { it isLessThan 2 } 
expect(x) contains o inAny order but only the entries({ it toBe 3 }, { it isLessThan 2 })

Note that o is a filler object which is only there so that we can turn extension methods without parameters into 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, are applicable to all shown examples (e.g. butAtMost 2 value 3.2 could have been finished with entries(...) as well)

Iterable contains in order

atrium-api-fluent-en_GB

expect(x).containsExactly(1.2)
expect(x).containsExactly(1.2, 5.7)
expect(x).containsExactly({ isLessThan(2) })
expect(x).containsExactly({ isLessThan(2) }, { isGreaterThan 5 })

expect(x).contains.inOrder.only.value("hello")
expect(x).contains.inOrder.only.values("hello", "world")
expect(x).contains.inOrder.only.entry { isLessThan(2) }
expect(x).contains.inOrder.only.entries({ toBe(3) }, { isLessThan(2) })
expect(x).contains.inOrder.only.grouped.within.inAnyOrder(
    value(1), 
    values(1, 2), 
    values(3, 4)
)
expect(x).contains.inOrder.only.grouped.within.inAnyOrder(
    entry { toBe(1) }, 
    entries({ isLessThan(2) },{ isGreaterThan(2) }), 
    entries({ toBe(3) }, { toBe(4) })
)

atrium-api-infix-en_GB

expect(x) containsExactly 1.2
expect(x) containsExactly values(1.2, 5.7) // or Objects as alternative
expect(x) containsExactly { it isLessThan 2 }
expect(x) containsExactly entries({ it isLessThan 2 }, { it isGreaterThan 5 })

expect(x) contains o inGiven order and only value "hello"
expect(x) contains o inGiven order and only the values("hello", "world")
expect(x) contains o inGiven order and only entry { it isLessThan 2 }
expect(x) contains o inGiven order and only the entries({ it toBe 3 }, { it isLessThan 2 })
expect(x) contains o inGiven order and only grouped entries within group inAny Order(
    value(1), 
    values(1, 2), 
    values(3, 4)
)
expect(x) contains o inGiven order and only grouped entries within group inAny Order(
    entry { it toBe 1 }, 
    entries({ it isLessThan 2 },{ it isGreaterThan 2 }), 
    entries({ it toBe 3 }, { it toBe 4 })
)

Note that o is a filler object which is only there so that we can turn extension methods without parameters into a method with one parameter and thus make it available as infix method.

Iterable contains not

atrium-api-fluent-en_GB

expect(x).containsNot(1.2)
expect(x).containsNot(1.2, 5.7)

expect(x).containsNot.value(null)
expect(x).containsNot.values(null, 1)
expect(x).containsNot.entry { isLessThan(2) }
expect(x).containsNot.entries(null, { isLessThan(2) }, { isGreaterThan 5 })

atrium-api-infix-en_GB

expect(x) containsNot 1.2
expect(x) containsNot values(1.2, 5.7)

expect(x) containsNot o value null
expect(x) containsNot o the values(null, 1)
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 -> see Iterable contains in any order for more information

atrium-api-fluent-en_GB

expect(x).any { startsWith("hello") }
expect(x).none { endsWith(".") }
expect(x).all { isNumericallyEqualTo(12.2) }

expect(x).any(null)
expect(x).none(null)
expect(x).all(null)

atrium-api-infix-en_GB

expect(x) any { it startsWith "hello" }
expect(x) none { it endsWith "." }
expect(x) all { it isNumericallyEqualTo 12.2 }

expect(x) any null
expect(x) none null
expect(x) all null

List get

atrium-api-fluent-en_GB

expect(x).get(0).isLessThan(1)
expect(x).get(0) { isGreaterThan(1) }

//in case of a nullable element type
expect(x).get(0).toBe(null)

atrium-api-infix-en_GB

expect(x) get 0 isLessThan 1
expect(x) get index(0) { it isGreaterThan 1 }

//in case of a nullable element type
expect(x) get 0 toBe null

Map getExisting

atrium-api-fluent-en_GB

expect(x).getExisting("a").isLessThan(1)
expect(x).getExisting("a") { isGreaterThan(1) }

//in case of a nullable value type
expect(x).getExisting("a").notToBeNull { isGreaterThan(1) }

atrium-api-infix-en_GB

expect(x) getExisting "a" isLessThan 1
expect(x) getExisting key("a") { it isGreaterThan 1 }

//in case of a nullable value type
expect(x) getExisting "a" notToBeNull { it isGreaterThan 1 }

Map contains

atrium-api-fluent-en_GB

expect(x).contains("a" to 1)
expect(x).contains("a" to 1, "b" to 2)
expect(x).contains(KeyValue("a") { isGreaterThan(3).and.isLessThan(10) })
expect(x).contains(KeyValue("a") { toBe(2) }, KeyValue("b") { isLessThan(3) })

//in case of a nullable value type
expect(x).contains("a" to null)
expect(x).contains("a" to null, "b" to 2)
expect(x).contains(KeyValue("a", null))
expect(x).contains(
  KeyValue("a", null) 
  KeyValue("b") { isLessThan(2) }
)

atrium-api-infix-en_GB

expect(x) contains ("a" to 1)
expect(x) contains pairs("a" to 1, "b" to 2)
expect(x) contains keyValue("a") { 
  it isGreaterThan 3
  it isLessThan 10 
}
expect(x) contains all(keyValue("a") { it toBe 2 }, keyValue("b") { it isLessThan 3 })

//in case of a nullable value type
expect(x) contains ("a" to null)
expect(x) contains pairs("a" to null, "b" to 2)
expect(x) contains keyValue("a", null)
expect(x) contains all(
  keyValue("a", null), 
  keyValue("b") { it isLessThan 2 }
)