atrium v0.8.0 Release Notes
Release Date: 2019-04-28 // almost 5 years ago-
Jar's can be found here: https://bintray.com/robstoll/tutteli-jars/atrium/0.8.0
API Maturity : Stable
Implementation Maturity : Almost Stable๐ There won't be any breaking changes in the API (assertion functions/builders) until v1.0.0 besides parameter name renaming. But we want to progress as well and deprecate functionality in each version (e.g quite a lot with 0.7.0; please replace deprecated functionality until v1.0.0 where we will remove it.
โ However, we do not provide yet a stable API for the domain and core modules of Atrium -- it is almost stable, but there might be slight breaking changes which we want to introduce before v1.0.0. That is also the reason why we do not have yet established backward compatibility tests for domain/core. This might affect you if you write your own assertion functions. And it also affects you if you provide your own implementation for parts of Atrium.Table of Content
- ๐ New Features
- API
- Domain/Core aka write own assertion functions
- Others
- ๐ Fixes
- Improvments
- ๐ฅ Breaking Changes
- ๐ Deprecation
- ๐ Migrating deprecated functionality
๐ New Features
API
- #27 containsExactly as replacement for containsStrictly, thanks to @msmoljan for the implementation and thanks to @christophsturm for the idea
- #33 isNotBlank for CharSequence, thanks to @pt2121 for the implementation
- #39 make atLeast optional for CharSequence.contains, thanks to @christophsturm for the idea
- #51 keys and values for Map to postulate assertions about the keys or values of a Map
- #37 asEntries for Map, thanks to @arjank for the implementation
- #29/#75 getExisting for Map to postulate assertions about the value of a corresponding key
- #28 containskey, #59 containsNotKey for Map, thanks to @uaArsen for the implementation
- #61/#62 contains for Map
- #30/#76 get for List
- #53 notToThrow as counterpart of toThrow - thanks to @charleskorn for the idea
- #65 shortcut property/fun for Pair.first and Pair.second
- #25 isKeyValue as well as shortcut property/fun key/value for Map.Entry
- #69 toBe was opened up for nullable subjects (accepts now
Any?
), thanks to @dave08 for the discussion - #70 toBeNullIfNullElse for nullable subjects, thanks to @dave08 for the idea
- #71 shortcut property/fun Collection.size
- #78 containsExactly with single assertion creator
- #48 asIterable with assertionCreator block
- #46
o
as alternative tothis
in sub-assertions for the infix API
Domain / Core
๐ Features for assertion-function-writers:
- #67 AssertImpl.mapArguments -> to map a variable length argument lists of the form
first: T, vararg rest: T
(inside a functionT, Array<out T>
) toR, Array<out R>
- #72 changeSubject to a nullable type
- AssertImpl.feature.extractor -> in case you want to make an assertion about a feature which is not always safe to extract (e.g. List.get expects a suitable index)
- โจ AssertImpl.collector.collectOrExplain => collects assertions for later usage but only if it is safe to collect them, otherwise it wraps them into an explanatory assertion so that it can be used to enhance reporting
- AssertImpl.collector.collectNullable which allows to collect assertions for a nullable subject (for AssertionPlantNullable instead of AssertionPlant)
Others
- turned Atrium into an multi-platform project; all dependencies are also available for:
- ๐ #41 deprecated notToBeNullBut for BigDecimal
- ๐ #55 infix API - deprecated calls to
toBe
if a keyword is passed inadvertently - โ stacktraces in error reporting should no longer contain stack frames of Atrium or test runners
๐ Fixes
- none this time
๐ Improvements
- DetailedObjectFormatter shows now Kotlin types instead of Java types (e.g.
kotlin.Int
instead ofjava.lang.Integer
). - an AtriumError is now thrown instead of an AssertionError (AtriumError is a subtype of AssertionError)
๐ฅ Breaking Changes
Planned (previously deprecated or announced)
- none this time
Unplaned
- Made
Group
,GroupWithoutNullableEntries
andGroupWithNullableEntries
invariant. I doubt this will be a problem for someone, otherwise let me know - Made
Value
,Values
,Entry
,Entries
invariant; in case you get problems, try to use user-site variance and specifyout
there
The following breaking changes only bother you if you implemented an own core. Most have been necessary to turn Atrium into a multi-platform project: - core uses now an own implementation of
Locale
and no longer java.util.Locale - core uses now
KClass
instead ofClass
- TranslatableWithArgs takes a List instead of an Array as parameter
- Reporter needs to provide an AtriumErrorAdjuster in addition
- โ removed duplicate anyAssertions in package ch.tutteli.atrium.domain.creating.any.typetransformation.creators (use the one from package ch.tutteli.atrium.domain.creating)
tl;dr the following is only of interest if you rely on binary compatibility
I changed the JvmName ofcontains?
incc-en_UK
andcc-infix-en_UK
tocontainsDeprecated
andenthaelt?
incc-de_CH
toenthaeltDeprecated
due to the DEX compiler for android which cannot handle?
in identifiers. This is a binary backward compatibility break for a method which I introduced in 0.7.0 to retain source backward compatibility. In case you use still use cc-en_UK or cc-infix-en_UK and rely on binary compatibility you will have to recompile when updating to 0.8.0.๐ Deprecation
๐ The following was deprecated and will be removed with 1.0.0:
Assert<Iterable>.containsStrictly
usecontainsExactly
instead.- ๐ ReporterBuilder::withoutTranslations using java.util.Locale => use Atrium's Locale
- 0๏ธโฃ TranslatorOption::withDefaultTranslator using java.util.Locale => use Atrium's Locale
- 0๏ธโฃ TextAssertionFormatterOption::withDefaultTextCapabilities => use withTextCapabilities which uses KClass instead of Class
- ๐ง AtriumErrorAdjusterOption::withOnlyFailureReporter and withCustomReporter => new step in configuration, use either withDefaultAtriumErrorAdjusters or choose one of the other options
- ๐ all functions containing
nullable
in their name => their counterpart withoutnullable
in their name where opened up to accept also nullable types (see #60 for details)
Possible Breaking Changes with 0.9.0
- I will prepare the transition to
Assert<T>
instead ofAssert<out T>
. I will turnAssert
into an own type (currently only a type alias) - you should not notice something but it means that the binary code will change when you compile against 0.9.0 - โ I might reuse opentest4j exceptions to improve error reporting in IDEs. For this to work I might have to make modifications to Assertion/AssertionGroup (would only affect core implementors).
- ๐ป An exception will be thrown where one has to define an assertionCreator -- shall prevent kind of dead code/incomplete assertions; for instance
assert(mapOf("a" to 1)).keys {}
- same for
addAssertionsCreatedBy
/and {}
; they will throw an exception if no sub-assertion is defined
- same for
- toBe, contains etc. which expect
T
where<T: Any>
might be restricted to input types, so that comparing apple with oranges is no longer possible without explicitly stating the type. E.g.assert(1).toBe("hello")
would be a compile error
Possible Breaking Changes with 1.0.0
Please open an issue if you are not happy with one of the changes and state why or contact me via the Atrium slack channel.
Assert<Throwable>.message{}
will returnAssert<Throwable>
instead ofUnit
Assert<T>.isA{}
will returnAssert<T>
instead ofUnit
All property and returnValueOf taking an assertionCreator will return the same type as the current subject.
๐ I will remove
out
ofAssert<out T>
in order that things likeasssert(1).toBe("hello")
is no longer possible, overloads can be simplified etc.returnValueOf functions might be renamed to returnValueOfX where X denotes the number of arguments. Too often it occurs that Kotlin is not able to infer the correct overload, the user does not get the appropriate help in code completion or the error message is too big. This should help.
๐ feature assertion functions might require a lambda in the future. This way error reporting does not blow up in the middle of the way because
subject
is not available. However, there is a bug concerning nullable-features in Kotlin which prevents me from doing it at the moment: https://youtrack.jetbrains.com/issue/KT-23768, please up-vote it.A type parameter might be added to
AssertionGroup
to restrict theAssertionGroupType
.๐ฆ
BulletPointIdentifier
together with subtypes (AssertionGroupType
s) might be moved to another package:ch.tutteli.atrium.reporting.assertions
๐ AssertionPlant/Assert will switch roles => AssertionPlant will be the typealias of Assert, see #26; should only break binary compatibility
๐ I will introduce interface groups for RepoterBuilder as I did in other cases (e.g. see Descriptive); should only break binary compatibility
๐ Migrating deprecated functionality
๐ In case you migrate from a version < 0.7.0 then please have a look at the migration guide given in the Release Notes of 0.7.0.
Otherwise you can use the suggested replacements (ALT + Enter -> Replace with ...)Ping me in the Atrium slack channel if you need help.
- ๐ New Features