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 in that make sense for the project 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, and the less time for manual debugging is needed, the more useful atrium becomes.

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:

• test 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