Requirements

This page shall show which requirements Atrium wants to fulfil, why and for whom.

Personas

We see roughly three Personas using Atrium:

1. Newcomer, a developer which uses only built-in functionality provided by Atrium's API => new assertion functions are only created by composing other assertion functions. This user would come up with something like:

   fun <T: Date> Expect<T>.isBetween(lowerBoundInclusive: T, upperBoundExclusive: T) =
       isGreaterOrEquals(lowerBoundInclusive).and.isLessThan(upperBoundExclusive)

2. Long-term User, a developer which uses Atrium but also invents new simple assertion functions. A user who uses Atrium already for a longer time. This user would come up with something like:

   fun Expect<Int>.isEven() = 
       createAndAddAssertion("is", RawString.create("an even number")) { it % 2 == 0 }

3. Library author, a developer which uses Atrium but also invents more complex assertion functions for own types. Could be a library author or someone which actually wants to understand Atrium fully to get most out of it. This user would come up with something like:

   fun <A, B> Expect<Either<A, B>>.isLeft(): Expect<A> = changeToLeft().getExpectOfFeature()
   fun <A, B> Expect<Either<A, B>>.isLeft(assertionCreator: Expect<A>.() -> Unit) =
       changeToLeft().addToInitial(assertionCreator)
   
   private fun <A, B> Expect<Either<A, B>>.changeToLeft(): ChangedSubjectPostStep<Either<A, B>, A> {
       return ExpectImpl.changeSubject.reportBuilder(this)
           .withDescriptionAndRepresentation("is a", RawString.create("Left"))
           .withCheck { it.isLeft() }
           .withTransformation { (it as Left).a }
           .build()
   }

Requirements

R1: Separation of infix and fluent API

Must/shall: must
For whom: all
Reasons:

• Mixing different styles lead to different code in the same codebase which we want to prevent in the first place (a user can depend on two APIs if desired).
• the learning curve is higher as there are multiple ways of achieving the same
• especially newcomers are left in uncertainty which version they should use (fluent or infix) and if there are differences between the two versions

R2: Global Implementation Replacement

Must/shall: must
For whom: all

Users should be able to replace certain parts of Atrium’s implementation. In particular, the Reporter, Translation and Assertions implementation should be replaceable. When the implementation is replaced globally, there is no “dangling” entry point that would use the un-replaced functionality. For example: If the user replaces the implementation of Expect<Any>.toBe, there is no version of Expect<Any>.toBe that could be used to access the old implementation.

Reasons:

• there may be implementation decisions that make sense for the Atrium but do not suit all users
• having multiple implementations of the same “thing” available can lead to subtle bugs

R3: Combinable, Shareable Implementation Changes

Must/shall: shall
For whom: Library author

It should be possible to implement and publish implementation changes (see R2) in such a way that several change modules can be combined; even if they target functionality that is implemented in the same class. This can, for example, be achieved if such modules only delegate to the currently loaded implementation instead of referencing one specific implementation.

Reasons:

• Multiple users might have the same need from atrium, while we do not want to fulfil it in the main project. Users should then be able to share alternative implementations.

R4: No Mutable State at Test Runtime

Must/shall: must
For whom: all

As soon as the library is being used, it should not be possible to change any state or implementations.

Reasons:

• avoid behaviour that is difficult to predict
• avoid race conditions that can, in particular, occur in parallel test execution

R5: Test Readability

Must/shall: must
For whom: Newcomer

All assertions should have predictable behaviour. By reading source code written with Atrium’s API, the average Kotlin developer who does not know Atrium can understand what is being tested on what.

Reasons:

• code reviews are crucial to detect errors in test logic (and thereby potentially in the tested logic)

R6: Failure Explanations

Must/shall: shall
For whom: all

When possible, and to the extent possible, users should be able to understand what they need to do in order to fix an assertion failure by just reading the assertion’s failure description.

Reasons:

• the more obvious the mistake is after reading an assertion’s failure description, the less time for manual debugging is needed and ergo the more useful Atrium becomes.

R7: Completeness

Must/shall: shall
For whom: all

Atrium’s users should expect that Atrium will offer a convenient way to specify assertions for most situations they will encounter. Atrium should hence offer an assertion function for anything one can reasonably expect to happen frequently when programming in Kotlin.

Reasons:

• maintainers need to weigh usefulness against maintenance effort. But an assertion function should never be dismissed if it is reasonably likely to be useful
• Having an assertion function at hand for almost every use case increases developers’ trust in Atrium.

R8: Minimalistic

Must/shall: must
For whom: all

Although Atrium shall offer

anything one can reasonably expect

as stated in R7: Completeness, it shall also be minimalistic in the sense of more is not better. This especially means, that the API should expose most frequently used functionality dominantly and less used functionality in a second step. For instance Expect<Iterable<Int>>.contains.inOrder.only.grouped.within.inAnyOrder is a valid use case but one which is most likely almost never used. Thus it is pushed to the contains API but not to the Expect API.

Reasons:

• having an overwhelming number of functions in an API makes it especially hard for newcomers to find the "tools" they need
• using a programming API is not much different than using any other API and thus should follow insights of Usability, UX, Interaction design etc. => this might be unfamiliar to developers but makes sense => flat learning curve, more intuitive etc.

R9: One way to the goal

Must/shall: must
For whom: all

Similar to R1 Separation of infix and fluent API. In an ideal world there would be just one way to write an assertion. Which means:

• no negation operator
• alias shouldn't be used in most cases
• shortcuts are only justified if they are used very regularly
• shortcuts and aliases should be described accordingly in KDOC and point to the other version
• incorporate runtime checks to catch misuses and point to the other implementaiotn

Reasons:

• the learning curve is higher as there are multiple ways of achieving the same
• especially for newcomers it is hard to know if there is a distinction between two things if they are named differently. For instance, if one could write Expect<Iterable<Int>>.contains.atLeast(1).butAtMost(1)... a newcomer might be unsure if this is the same as Expect<Iterable<Int>>.contains.exactly(1)...

R101: Little Custom Build Logic

Must/shall: shall
For whom: Library Authors

The project should follow conventional setups and require as little custom build logic as possible.

Reasons:

• build logic can be especially difficult to evolve and maintain
• the more non-standard a project setup is, the harder it is for new developers to get going