@robstoll robstoll released this Jul 20, 2018 · 240 commits to master since this release

Jar's can be found here: https://bintray.com/robstoll/tutteli-jars/atrium/0.7.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. Yet, I deprecated quite a lot of with this release; please replace deprecated functionality until v1.0.0 where I will remove it.
However, I do not provide yet a stable API for the core of Atrium -- it is almost stable, but there might be slight breaking changes which I want to introduce before v1.0.0. That is also the reason why I have not yet established backward compatibility tests for the core. This might affect you if you write your own assertion functions. It also affects you if you provide your own implementation for parts of Atrium.

New Features

API

  • isEmpty, isNotEmpty and hasSize for Map

  • messageContains as shortcut function for message { contains(...) }. You can still use message { ... } for more sophisticated assertions. For instance, if a certain string should only be contained once in the message then you can use message { contains.exactly(1).values(...) }. Or in case you want to be sure that something is not contained in the message message { contains(..); containsNot(...) }.

  • toBe(null) as replacement for isNull (isNull will be removed with 1.0.0)

  • notToBeNull as replacement for isNotNull (isNotNull will be removed with 1.0.0)

  • notToBeNullBut as shortuct function for notToBeNull { toBe(...) }

  • asIterable for Sequence and Array

  • added contains.inOrder.only.grouped.within.inAnyOrder to the sophisticated contains assertion builder for Iterable

  • added overloads to property and returnValueOf which allows to use a class reference rather than a bounded reference with the advantage that it is more robust when it comes to error reporting (since it does not need to access the reference to retrieve its name => see https://youtrack.jetbrains.com/issue/KT-23777 for more information)
    => personally I still use subject::... when I write assertions as such (in tests) but use Class::... inside assertion functions

  • added helper functions for people dealing with Java Code. Per default platform types are turned into a non-nullable version if possible. If you want to turn it into a nullable-version nonetheless, then you have to cast and restate the type. Depending on the type this might be cumbersome. Thus I introduced the following functions which give some extra hint to the compiler without actually adding code (they are all inline functions):

    • nullable turns a type into a nullable type or a function reference into a function reference with a nullable return type.
    • nullableContainer turns an Iterable into an iterable with nullable entry type, likewise it does the same for Array.
    • nullableValueMap turns a Map into a map with a nullable value type.

Domain / Core

Features for assertion-function-writers:

Other

  • further stabilised the API of atrium-core

  • introduced APIs cc-en_GB and cc-infix-en_GB in favour of cc-en_UK and cc-infix-en_UK => see below for migration guidelines

  • introduced atrium-domain modules in favour of atrium-assertion to provide a more stable API concerning impl-functions and sophisticated assertion builders

  • turned most modules into jdk9 modules (deprecated code was placed in separate modules ending with -deprecated)

    • new modules are using ServiceLoader now instead of api-late-binding (due to JDK9 split package problematic, ServiceLoader is a bit slower but on the other hand more commonly used)
  • introduced the module atrium-bc-test which ensures that, specs of 0.6.0:

    • are binary compatible with 0.7.0 (without re-compilation) and
    • can still be compiled against 0.7.0 and run successfully
      => This does not test every bits and pieces of Atrium, that is, it is only backward compatible to the extend of the tests.
      => 1.0.0 will contain major BC breaks, see below
      => Please contact me via slack if you would like to have your tests included in the bc-test (the more the merrier I suppose).

Fixed

  • #21 Charsequence contains empty string ends in endless loop

Improvements

  • #14 message of a thrown Exception as well as the beginning of the stack trace is now shown in case it is of a different type than the expected one (gives you some extra hint).
  • #15 Assert is now annotated with a DslMarker which assures that you do not call an assertion function of an outer subject inadvertently.
  • #16 PlantHasNoSubjectException popped up in some cases, is fixed.
  • #17 include actual size for hasSize
  • #20 Iterable<T: Any> contain assertion functions do no longer allow to pass null. Moreover, we added overloads for nullable where missing and renamed them to ...Nullable... (e.g. nullableValue or containsStrictlyNullableValues)
  • #22 Iterable contains in any order values create multiple assertions instead of sub-assertions
  • #23 CharSequence contains.regex should mention regex in reporting
  • predefined assertion verbs are now part of the bundle, newcomers will start off easier using Atrium (Readme was revised as well).
  • documented type assertions (isA) in Readme
  • documented handling of assertions for Sequence and Array in FAQ of Readme
  • the groupId of the artifacts was changed to ch.tutteli.atrium => adjust it next to the version

Breaking Changes

Planned (previously deprecated or announced)

  • Was planned but I did not do it: ReporterBuilder::withSameLineTextAssertionFormatter was announced to be removed with 0.7.0 but will remain in the deprecated ReporterBuilder in the deprecated module atrium-assertions and will remain there until 1.0.0. The new ReporterBuilder in module atrium-domain-builders does not include this method.

Unplaned

  • containsNot checks in addition that the Iterable returns at least one element (or in other words, it fails if Iterable returns nothing).
  • DefaultInvisibleAssertionGroupType was removed, use InvisibleAssertionGroupType instead, use AssertImpl.builder.invisibleGroup respectively.
  • the default implementation for subject was removed from interface BaseReportingAssertionPlant and ReportingAssertionPlantNullable
  • I renamed a few parameter names so that they better reflect what an assertion function expects -> only concerns you if you used named parameters. I assume that no one uses named parameters in this context but let me know if you did because I might introduce more such breaking changes in the future.

The following changes only bother you if you do not use a bundle module but specify the dependencies manually:

  • removed impl from the module names atrium-core-impl-robstoll and atrium-core-impl-robstoll-lib; => Adjust the names in such a case. E.g. depend on atrium-core-robstoll instead of atrium-core-impl-robstoll (or use one of the bundle modules).
  • some base classes for sophisticated builders where moved from atrium-assertions to atrium-domain-builders; => add a dependency to the domain modules in addition (or use one of the bundle modules).
  • moved deprecated code to seperate modules => add the corresponding dependencies in addition (atrium-translations-en_UK-deprecated, core-api-deprecated, core-robstoll-deprecated)

Deprecation

The following was deprecated and will be removed with 1.0.0:

  • the boolean assertion functions isTrue() and isFalse() => use toBe(true), toBe(false) respectively (or re-add as your own function if you want to keep it)
  • the nullable assertion function isNull in API cc-en_UK => use toBe(null) (or re-add as your own function if you want to keep it)
  • the nullable assertion function isNotNull in API cc-en_UK => use noToBeNull (or re-add as your own function if you want to keep it)
  • the shortcut function containsNot for nullable values => you can use containsNot.nullableValues(...)
  • the assertion function toThrow() => better there is only toThrow {} this way you do not need to chose and IntelliJ can compelete the function quicker.
  • the assertion function isSame and isNotSamein favour of isSameAs and isNotSameAs
  • the sequence inGiven order but only in API cc-infix-en_UK => use inGiven order and only
  • the functions object and objects of the sophisticated contains assertion builder for Iterable => use value, values respectively.
  • the assertion functions concerning Translatable => was most likely only used by Atrium internally. Is no longer used thus will be removed. But in any case, there is no need to pollute the API with functions most users do not use.
  • ReporterBuilder in package ch.tutteli.atrium.reporting => moved to package ch.tutteli.atrium.domain.builders (to be JDK9 ready where split package is not allowed), yet its inaccessible, use reporterBuilder instead
  • IndentAssertionGroup together with IndentAssertionGroupType and TextIndentAssertionGroupFormatter => please let me know (via slack or by opening an issue) if you used one of it. I happily show how you can achieve the same but differently.
  • InvisibleAssertionGroup -> use AssertImpl.builder.invisible instead.
  • AssertionGroup.Builder -> use AssertImpl.builder (one of the suggested replacements).
  • IAtriumFactory and AtriumFactory in favour of ICoreFactory, CoreFactory respectively -> use the suggested replacement.
  • DescriptiveAssertion::expected use DescriptiveAssertion::representation instead.
  • the whole module atrium-assertions -> use the atrium-domain modules instead
  • the whole package assertions.charsequence.builders as well as assertions.iterables.builders
  • the assertion verbs no longer reside in an own package but were moved to ch.tutteli.atrium.verbs because assert is a reserved keyword in Java and I would not have been able to define module-info.java where I export package assert

The following was deprecated and will be made internal with 1.0.0:

  • BasicDescriptiveAssertion -> use AssertImpl.builder.descriptive instead
  • BasicExplanatoryAssertion -> use AssertImpl.builder.explanatory instead
  • BasicAssertionGroup -> use AssertImpl.builder
  • ExplanatoryAssertionGroup -> use AssertImpl.builder.explanatoryGroup
  • EmptyNameAndSubjectAssertionGroup -> use AssertImpl.builder
  • ...CheckerOptionImpl (new classes - have to be public to retain backward compatibility - do not start to rely on them, rely on the interfaces instead)

Possible Breaking Changes with 0.8.0

  • I might rename parameters. I assume that no one is using named parameters in the context of postulating assertions. Please let me know if I am wrong.

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.

  • 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 the AssertionGroupType.
  • BulletPointIdentifier together with subtypes (AssertionGroupTypes) might be moved to another package: ch.tutteli.atrium.reporting.assertions

Migrating deprecated functionality

You have time to replace the deprecated functionality with the new solutions until 1.0.0 -- enough time I guess, I don't even know what 1.0.0 will contain exactly (surely html reporting and multi platform functionality, that might take a while).

I have placed corresponding ReplaceWith into most of the @Deprecated annotations. Unfortunately they do not all behave as I wish due to several bugs in this area (for instance: https://youtrack.jetbrains.com/issue/KT-24181, https://youtrack.jetbrains.com/issue/KT-10094)

Please file a bug if I have forgotten to place a replacement somewhere or if it does not work as expected (e.g., if I have forgotten to add an import). I gladly fix it and provide a patch version => better than you have to adjust things manually all over the place 😉.

The biggest deprecation is due to my silly mistake of using en_UK instead of en_GB (thanks to @robfletcher for pointing it out). Luckily though, it gave me the opportunity to provide an API which is deprecation free and JDK9 ready. That means, once you have transformed all your deprecated code, you can switch from the en_UK bundle to the en_GB bundle and if it still compiles then you can be sure, that you did not miss to migrate a deprecated entity and you are Atrium 1.0.0 compatible (in case you are using a de_CH bundle: müsst euch bis 1.0.0 gedulden, dann wird auch de_CH deprecation free und JDK9 ready sein).
Unfortunately, Intellij makes some replacements not terribly well, due to the following bug https://youtrack.jetbrains.com/issue/KT-10094.
As far as I have seen it only concerns consumers of the infix API (guidance is given by the following checklist).

Following a checklist which shall help you migrating things (I have done the same for migrating atrium-spec to use cc-en_GB instead of cc-en_UK).
You only need to consider the checklist for the bundle you use:

atrium-cc-en_UK-robstoll

Please make sure you have enabled the search options "Match case" and "Regex" in the following search & replace instructions.

  • update dependency to ch.tutteli.atrium:atrium-cc-en_UK-robstoll:0.7.0 (notice groupId has changed to ch.tutteli.atrium)

  • if you use a predefined verb:

    • verbs are no longer in an own package:
    1. search for: import ch.tutteli.atrium.verbs.(?:assert.(assert)|assertthat.(assertThat)|expect.(expect))
    2. replace with: import ch.tutteli.atrium.verbs.$1$2$3
  • search for: .(toThrow<[^>]+>)\(\)
    replace with: .$1\{\}

Either you replace the deprecated functions using IntelliJ's function "replace with suggestion", or you can use the following approach which might need some manual adjustment in the end but not much I guess. Yet, I think you are still better of using this approach over "replace with suggestion" due to the following bug: https://youtrack.jetbrains.com/issue/KT-24181 which makes replacements not ideal.

  • search for: ReporterBuilder

    => in case you have a match:

    • replace buildOnlyFailureReporter with the suggestion (ALT + Enter -> Replace with ...) => the code will not immediately compile, go on with the next step (at the end it will)
    • replace other deprecated functions starting from the bottom => at the end you will have replaced ReporterBuilder by reporterBuilder
    • remove the import ch.tutteli.atrium.reporting.ReporterBuilder
  • in case you have defined your own assertion verbs

    Configuration of the reporter can be done via verb directly but it is advisable to do it via ReporterFactory.
    In case you do not use another configuration than the DefaultReporterFactory already defines, then it is enough if you just exchange your Reporter with reporter (add import ch.tutteli.atrium.reporting.reporter)
    In case your configuration differs then you have to specify your own ReporterFactroy. See atriumVerbs.kt of API de_CH for an example how you define one. Furthermore, you need register your own ReporterFactory as service (ServiceLoader mechanism, see how it is done in API de_CH).

  • search for: (import ch.*)en_UK(.*)

    replace with: $1en_GB$2

  • search for: isTrue\(\)

    replace with: toBe(true)

  • search for: isFalse\(\)

    replace with: toBe(false)

  • search for: import ch.*en_GB.is(?:True|False)([\S\s]*)(import ch.*en_GB).is(?:True|False)

    replace with: $1$2.toBe

  • search for: isNull\(\)

    replace with: toBe(null)

  • remove duplicated toBe imports, you might have to replace multiple times:

    search for: (import ch.*en_GB.toBe)([\S\s]*)import ch.*en_GB.toBe

    replace with: $1$2

  • search for: isNotNull

    replace with: notToBeNull

  • search for: isSame

    replace with: isSameAs

  • search for: isNotSame

    replace with: isNotSameAs

  • search for: ((?:inAnyOrder\.(?:only\.)?)|(?:inOrder\.only\.))`object`

    replace with: $1value

  • search for: ((?:inAnyOrder\.(?:only\.)?)|(?:inOrder\.only\.))objects

    replace with: $1values

  • You might have some errors in conjunction with Iterable with nullable elements (Iterable<T?>) which you need to fix manually. There are replacements like nullableValue instead of value etc.

  • compile and see if you have deprecation warnings if so, fix them by using the suggested replacements

  • to test if you have removed all deprecated function you can adjust your gradle dependency and depend on atrium-cc-en_GB-robstoll instead of atrium-cc-en_UK-robstoll

  • remove the dependency to atrium-verbs in case you have defined it (is already defined in the bundle atrium-cc-en_GB-robstoll)

Ping me in the Atrium slack channel if you need help.

atrium-cc-infic-en_UK-robstoll

Please make sure you have enabled the search options "Match case" and "Regex" in the following search & replace instructions.

  • update dependency to Atrium as follows:

    buildscript {
        ext { atrium_version='0.7.0' }
    }
    repositories {
        jcenter()
        // either use jcenter or the repository on the next line
        // maven { url "http://dl.bintray.com/robstoll/tutteli-jars" }
    }
    dependencies {
        testCompile("ch.tutteli.atrium:atrium-cc-infix-en_GB-robstoll:$atrium_version") { 
            exclude group: 'ch.tutteli.atrium', module: 'atrium-api-cc-en_GB' 
        }
        testRuntimeOnly("ch.tutteli.atrium:atrium-api-cc-en_GB-robstoll:$atrium_version")
    }
    

    We have to define an exclude due to a missing feature (or you could call it a bug) so that maven dependencies defined with <scope>runtime</scope> are treated as compile nonetheless.
    If you are using gradle > 4.6, then you can put enableFeaturePreview("IMPROVED_POM_SUPPORT") in your settings.gradle and simplify the dependencies section to the following:

    dependencies {
        testCompile "ch.tutteli.atrium:atrium-cc-infix-en_GB-robstoll:$atrium_version" 
    }
    
  • if you use a predefined verb:

    • verbs are no longer in an own package:
    1. search for: import ch.tutteli.atrium.verbs.(?:assert.(assert)|assertthat.(assertThat)|expect.(expect))
    2. replace with: import ch.tutteli.atrium.verbs.$1$2$3
  • search for: .(toThrow<[^>]+>)\(\)
    replace with: .$1\{\}

  • Objects was deprecated in favour of Values -- I have not placed a ReplaceWith into the @Deprecated annotation due to mentioned bug.

    1. search for: Objects
    2. replace with: Values
    3. search for: Values(Values
    4. replace with: Values
  • search for: ch.tutteli.atrium.api.cc.infix.en_UK.(Empty|contain|case|only|order)

    replace with: ch.tutteli.atrium.api.cc.infix.en_GB.keywords.$1

    => this might not be as successful as I wish due to star import, you probably have to do some adjustments manually

Either you replace the deprecated functions using IntelliJ's function "replace with suggestion", or you can use the following approach which might need some manual adjustment in the end but not much I guess. Yet, I think you are still better of using this approach over "replace with suggestion" due to the following bug: https://youtrack.jetbrains.com/issue/KT-24181 which makes replacements not ideal.

  • search for: ReporterBuilder

    => in case you have a match:

    • see if you are using the deprecated fun withTranslationSupplier and replace it with the suggested replacement (ALT + Enter -> Replace with ...)
    • exchange buildOnlyFailureReporter() with .onlyFailureReporter().build()
    • remove the import ch.tutteli.atrium.reporting.ReporterBuilder
  • in case you have defined your own assertion verbs

    Configuration of the reporter can be done via verb directly but it is advisable to do it via ReporterFactory.
    In case you do not use another configuration than the DefaultReporterFactory already defines, then it is enough if you just exchange your Reporter with reporter (add import ch.tutteli.atrium.reporting.reporter)
    In case your configuration differs then you have to specify your own ReporterFactroy. See [atriumVerbs.kt of API de_CH)(https://github.com/robstoll/atrium/tree/v0.7.0/apis/atrium-api-cc-de_CH/src/test/kotlin/ch/tutteli/atrium/atriumVerbs.kt) for an example how you define one. Furthermore, you need register your own ReporterFactory as service (ServiceLoader mechanism, see how it is done in API de_CH).

  • search for: (import ch.*)en_UK(.*)
    replace with: $1en_GB$2

  • search for: isSame

    replace with: isSameAs

  • search for: isNotSame

    replace with: isNotSameAs

  • search for: ((?:inAny order (?:but only)?)|(?:inGiven order but only) )object

    replace with: $1value

  • search for: inGiven order but only
    replace with: inGiven order and only

  • You might have some errors in conjunction with Iterable with nullable elements (Iterable<T?>) which you need to fix manually. There are replacements like nullableValue instead of value etc.

  • to test if you have removed all deprecated function you can adjust your gradle dependency and depend on atrium-cc-infic-en_GB-robstoll instead of atrium-cc-infic-en_UK-robstoll

  • remove the dependency to atrium-verbs in case you have defined it (is already defined in the bundle atrium-cc-infic-en_GB-robstoll)

Ping me in the Atrium slack channel if you need help.

atrium-cc-de_CH-robstoll

  • update dependency to Atrium as follows:

    buildscript {
        ext { atrium_version='0.7.0' }
    }
    repositories {
        jcenter()
        // either use jcenter or the repository on the next line
        // maven { url "http://dl.bintray.com/robstoll/tutteli-jars" }
    }
    dependencies {
        testCompile("ch.tutteli.atrium:atrium-cc-de_CH-robstoll:$atrium_version") { 
            exclude group: 'ch.tutteli.atrium', module: 'atrium-api-cc-en_GB' 
        }
        testRuntimeOnly("ch.tutteli.atrium:atrium-api-cc-en_GB-robstoll:$atrium_version")
    }
    

    We have to define an exclude due to a missing feature (or you could call it a bug) so that maven dependencies defined with <scope>runtime</scope> are treated as compile nonetheless.
    If you are using gradle > 4.6, then you can put enableFeaturePreview("IMPROVED_POM_SUPPORT") in your settings.gradle and simplify the dependencies section to the following:

    dependencies {
        testCompile "ch.tutteli.atrium:atrium-cc-de_CH-robstoll:$atrium_version" 
    }
    
  • if you use a predefined verb:

    • verbs are no longer in an own package:
    1. search for: import ch.tutteli.atrium.verbs.(?:assert.(assert)|assertthat.(assertThat)|expect.(expect))
    2. replace with: import ch.tutteli.atrium.verbs.$1$2$3
  • search for: .(toThrow<[^>]+>)\(\)
    replace with: .$1\{\}

  • search for: ReporterBuilder

    => in case you have a match:

    • replace buildOnlyFailureReporter with the suggestion (ALT + Enter -> Replace with ...) => the code will not immediately compile, go on with the next step (at the end it will)
    • replace other deprecated functions starting from the bottom => at the end you will have replaced ReporterBuilder by reporterBuilder
    • remove the import ch.tutteli.atrium.reporting.ReporterBuilder
  • use the suggested replacements for deprecated functions.

  • remove the dependency to atrium-verbs in case you have defined it (is already defined in the bundle atrium-cc-de_CH-robstoll)

Ping me in the Atrium slack channel if you need help.

Not included in this release yet

  • sophisticated assertion builder for toBe with error tolerance for floating point numbers
  • failure hint for toBe in conjuction with Float or Double
Assets 2