Change Wording from ‘Assertion’ to ‘Expectation’

[jGleitz]

In #714, we found that it makes sense to talk about ‘expectations’ instead of ‘assertions’. Hence, we want to refactor the whole code base to reflect that naming.

[jGleitz]

@robstoll: I’d also like to change the wording from ‘feature assertion’ to ‘feature extractor’ because they don’t really assert (or expect) anything, they only change the subject.

This would also mean that it might make sense to separate feature extractors from expectations. If I remember correctly, we had that in the past but removed the split. From a naming standpoint, it would make sense though. What do you think?

[robstoll]

I am not sure where you want to change the wording. In the readme? the file name in the API?

We actually have already a FeatureExtractor on the logic level, it's the implementation behind feature assertions in the end.

So far I made the following distinction between the two (KDoc of FeatureExtractor)

/**
 * Defines the contract for sophisticated `safe feature extractions` including assertion creation for the feature.
 *
 * It is similar to [FeatureAssertions] but differs in the intended usage.
 * [FeatureAssertions] are intended to make assertions about a return value of a method call or a property,
 * assuming that the call as such always succeeds (no exception is thrown).
 * The [FeatureExtractor] on the other hand should be used if it is already known,
 * that the call/access fails depending on given arguments.
 * For instance, [List.get] is a good example where it fails if the given index is out of bounds.
 */

[jGleitz]

I am not sure where you want to change the wording. In the readme? the file name in the API?

I am mainly concerned about how we communicate, so I’d mainly change the readme. However, I thought it might make sense to reflect that distinction also in the API and the logic files. That could also make it easier to find certain functions, since so files are quite big.

We actually have already a FeatureExtractor on the logic level

I know :). However, I hadn’t read that piece of KDoc yet.

I don’t find the distinction you make in the KDoc all too convincing. I think the distinction should be about intend. Let’s take List.get: True, using it is also some kind of expectation, however, that should not be the intend. If I want to make sure that there are three elements, I should write something like expect(list).size.toBeGreaterThan(2). I’d, personally, consider it bad style to only use get(2) if there being three elements is an important expectation for my test.

From my point of view, there are no ‘feature expectations’, but only ‘feature extractors’ and ‘expectations’. Something like Throwable.messageToContain is only a shortcut for a feature extractor plus an expectation. This also ties in nicely with the naming convention we found in robstoll/atrium-roadmap#93. Expectations have the form ‘to+infinitive’, feature extractors do not and are most of the time called like their corresponding method/value on the subject type.

As I said, I am mainly concerned about the wording we use in the documentation. Consistent wording that builds a clear mental model always helps me a lot when reading docs and getting to know projects.

Whether we split the files is another question. I am in favour of it, but much less concerned about it than I am about the docs.

[robstoll]

Those are good points and make sense. So I am in favour of renaming featureAssertions.kt in the APIs to featureExtractors.kt and we can also name it that way in the README.

Also I agree that the distinction is no longer really up-to-date as we now also catch exceptions caused in feature { } since 0.15.0 and report it. So I am in favour of merging the FeatureAssertions and FeatureExtractor on the logic level. I would still name it FeatureExtractor and not FeatureExtractors in contrast to featureExtractors.kt on the API level.

However, I think you take an end-user perspective on the logic level where the logic level targets expectation function writers. Thus, I would still include in the KDoc of property, f0 and co. + manualFeature that they should not be used if the extraction is not safe and instead use extract

[jGleitz]

So I am in favour of renaming featureAssertions.kt in the APIs to featureExtractors.kt and we can also name it that way in the README.

So I am in favour of merging the FeatureAssertions and FeatureExtractor on the logic level. I would still name it FeatureExtractor and not FeatureExtractors in contrast to featureExtractors.kt on the API level.

Great 👍

However, I think you take an end-user perspective on the logic level where the logic level targets expectation function writers. Thus, I would still include in the KDoc of property, f0 and co. + manualFeature that they should not be used if the extraction is not safe and instead use extract

I am not sure what you are hinting at with this paragraph. I did not want to imply changing any KDoc. I absolutely see that distinguishing safe from unsafe extractions on the logic level makes sense. As you say, I was only concerned about the user’s perspective.

Last question: Should we separate expectations from feature extractions in the logic and API files? Should we, for example, have pathExpectations.kt (containing stuff like toExist) and pathFeatureExtractors.kt (containing stuff like `fileName)? On first look, it seems that this would no even lead to a lot more files, since most files contain only expectations or only feature extractors.

[robstoll]

I am not sure what you are hinting at with this paragraph, I did not want to imply changing any KDoc

That on this level we should first serve the expectation function writers and then end-users.
I actually understood that you would want to remove the distinction, i.e. remove the extract or at least the text in the KDoc. So, a misunderstanding on my part. Thanks for your clarification 👍

Should we separate expectations from feature extractions in the logic and API files?

I would not, we had and many times still have the split in the specs and so far it was more confusing than helpful.

[jGleitz]

Fair enough.

[jGleitz]

@robstoll how will we proceed here? My current understanding is that you approve the change in principle, but don’t want it to affect the code too much, which leaves us in a weird half-baked situation, from my point of view.

1. Why don’t we rename the API files? My understanding is that this will be a source compatible change, which should be fine, right?
2. In 🚧 Rename ‘Assertions’ to ‘Expectations’ #748 you mentioned that you want to leave the ‘Assertion’ class, and all related classes, named ‘Assertion’. Why is that?

Regarding 2, I don’t think that it would be wise to talk about both ‘Assertions’ and ‘Expectations’ in Atrium. Because:

• I think ‘Assertion’ is not a fitting name at all. I am not sure why it is so common in the Java world when talking about tests. Maybe it is because of the assert keyword and the corresponding AssertionError. In production code, it makes sense to use assert and the term assertion, because you use it to assert a certain property of the code. In test code, I don’t think it makes much sense. Test code checks or makes expectations, it does not assert.
• I think in 🚧 Rename ‘Assertions’ to ‘Expectations’ #748 you imagined ‘assertion’ to be the domain & logic term, and ‘expectation’ to be the API term. However, I think can not be separated clearly. It starts with assertionCreator lambdas: They create Assertions, so calling them anything else, would not make sense. But then again, the user would provide an assertionCreator lambda to make expectations – that’s also odd.

All in all, I proposed this change because I think it would make it easier to talk about Atrium’s concept and to write clear documentation. I still think that pulling it through would improve the understandability of this project. I also think that now is a good point in time, once Atrium hits 1.0.0, such a change is much worse to pull off.

However, if we are going to mix terms throughout the code base and documentation, I think we are worse off than if we went just with ‘Assertion’. So I think we should do the change, but do it all the way.

What are your thoughts @robstoll ?

[robstoll]

1. We will. I first figured that renaming the files now makes sense and we can later on move the deprecated stuff out of the files into a file called xyExpectationsDeprecated. But that's work which is unnecessary as it is also perfectly fine to have the old deprecated functions in xyAssertions.kt and the new in xyExpectations.kt

2. because we will talk about expectation functions in the README and on the API level. To me, they sound like they are creating expectations. Which they do but not in a technical term in the sense of, if we rename Assertion to Expectation, then they don't create Expectations only, they have much more side effects (also depending on the context) -- a bit further outlined below when I talk about assertionCreator-lambda

But... I agree that Assertion can be quickly mixed up with assert from production and that this is not an ideal term. Maybe we can come up with something else which also has less overlapping with expectation? I am open for a new term and I agree that now would be the perfect timing.

It starts with assertionCreator lambdas: They create Assertions, so calling them anything else, would not make sense.

They create Assertions but also add them to the Expect. And this can cause that an exception is thrown depending on the Expect to which they add the Assertion. A lot of side effects. I would like to distinguish this from the mere creation of Assertions.

Which also means, I would still rename it to expectationCreator-lambda

---

• I still think talking about expectations on the API level (and hence in README and most of the docs) makes a bit more sense than about assertions, especially because we use now the verb expect and the interface is named Expect.
• I am also happy to rename Assertions (assertionBuilder etc.) to something else. Right now I don't have a better fitting name in my head but I will think about it

[robstoll]

Maybe it makes sense to look at it from a reporting perspective. We wanted to introduce Reportable with subtypes: Text, Translatable, something which replaces ExplanatoryAssertionGroup and Assertion/AssertionGroup.

[jGleitz]

Okay, I understand from what you write that you don’t insist on the term ‘Assertion’, but rather want to differentiate between the logic object and the general term ‘expectation’. I’ll write my interpretation of the terms, maybe that convinces you.

First, the functions we offer through the API are currently called ‘assertion functions’. Going forward, I’d just call them ‘expectation’, not ‘expectation function’. It makes perfect sense to say that toBe(4) is an expectation. In this context ‘expectation’ is used in its broad meaning that it has in the everyday English language.

If I understood you correctly, you hesitate to call Assertion Expectation because an expectation (lowercase ‘e’) on the API level includes more (side effects, etc.) than an Expectation on the logic level. This is correct. However, I don’t think that this is an issue at all, because this is also a very common case in programming: There is the use case on the API level, and there is an object representing that use case on the logic level. And of course, the object encompasses much less than the use case.

In my experience, naming the logic object according to the use case is helpful, not irritating. The use case and logic object can be clearly separated: the former is an ‘expectation’, the latter an Expectation. On the other hand, it is helpful, especially for newcomers, to use a name that resembles the use case, because you can just go ‘ah, this is called Expectation, this will most likely be the thing that contains the actual check’.

---

We wanted to introduce Reportable with subtypes: Text, Translatable, something which replaces ExplanatoryAssertionGroup and Assertion/AssertionGroup.

Yes, I am aware. And I still think we should do it, it will improve the API! But I am not sure how this is related to this discussion.

[robstoll]

I understand from what you write that you don’t insist on the term ‘Assertion’,

Exactly, I don't insist on the term. I am basically with you that Assertion can be mixed-up with assert and I am happy to change this. IMO Assertion is better if we talk only about language because for me, an Assertion is stronger than an Expectation but maybe that's a personal preferences. In the context of Atrium, I still think Expectation fits better because we have expect as verb.

Going forward, I’d just call them ‘expectation’, not ‘expectation function’.

I don't see yet how this will work out. In the README we will have sections like Your first expectation and then Write your own expectations. I think we need expectation function for the distinction. But I don't see a problem with using expectation function when we only talk about the function as such. I am with you that we can use the term expectation for an expectation function call, e.g. for toEqual(4).

However, I don’t think that this is an issue at all, because this is also a very common case in programming

I don't think that it is a real problem, we had assertion function and Assertion before and no one complained. It's more a subtlety which I would like to improve because it does not really ad up in the end to my mind and now is the perfect time to change something like that. As already outlined, if we have an expectation function, it should create expectations. If we call Assertion, Expectation, then why does the expecationBuilder create a different kind of expectation than the expectation function. It's not terrible but it can be improved IMO.

But I am not sure how this is related to this discussion.

Was just meant as input, maybe you had a good idea looking at Assertion from the reporting perspective to come up with something different. I thought about it a bit and I think my gut feeling was not wrong. Looking at it from a reporting perspective might make more sense. I try to outline two possibilities.

An AssertionGroup is currently: a description + representation, a list of Assertions + the information how they should be displayed in reporting. We can see from this that an AssertionGroup is more than just a grouping and it is related to reporting. A better fitting name could be ReportGroup and an Assertion would be a Report instead. The AssertionBuilder would become the ReportBuilder. We have different kind of reports, like a RepresentationOnlyReport, a DescriptiveReport (I don't like the name as it is too general so maybe we can come up with a better name as well, maybe simply DescriptionRepresentationReport). A ReportGroup will in the end be reported by a Reporter to the user.
AnyAssertions on the logic level would become AnyReports (or maybe better AnyReportFactory?).

Although I find report quite fitting because we are using it for reporting, the term might be too loaded by devs with the idea that a Report already needs to be everything and not a single unit. And we would again overload the term once we produce a HTML report next to the terminal report. Therefore, I am considering to use the term Record instead. At first glance I like it because it emphasises that we take a snapshot in time and create a record from it. The user has an expectation, we record the actual state and a Reporter in the end reports the aggregated records to the user to let him know about the outcome.

Following the three possibilities (with status quo) next to each other (I also made a few further adjustments)

Current	Expectation	Report	Record
toEqual(4) = assertion	expectation	expectation	expectation
toEqual = assertion function	expectation function	expectation function	expectation function
contains.atLeast(…) = sophisticated assertion builder	sophisticated expectation builder	sophisticated expectation builder	sophisticated expectation builder
assertion verb	verb	verb	verb
anyAssertions.kt (on API level)	anyExpectations.kt	anyExpectations.kt	anyExpectations.kt
AnyAssertions (on logic level)	AnyExpectations	AnyReportFactory	AnyRecordFactory
Assertion	Expectation	Report	Record
AssertionGroup	ExpectationGroup	ReportGroup	RecordGroup
AssertionGroupType	ExpectationGroupType	ReportGroupType	RecordGroupType
AssertionBuilder	ExpectationBuilder	ReportBuilder	RecordBuilder
AssertionCollector	ExpectationCollector	ReportCollector	RecordCollector
AssertionContainer	ExpectationContainer	ReportContainer	RecordContainer
AssertionContainer.addAssertion	ExpectationContainer.appendExpectation	ReportContainer.appendReport	RecordContainer.appendRecord
AssertionContainer.createAndAddAssertion	ExpectationContainer.createAndAppendExpectation	ReportContainer.createAndAppendReport	RecordContainer.createAndAppendRecord
AssertionContainer.addAssertionsCreatedBy	ExpectationContainer.appendExpectationsCreatedBy	ReportContainer.appendExpectationsCreatedBy	RecordContainer.appendExpectationsCreatedBy
AssertionFormatter	ExpectationFormatter	ReportFormatter	RecordFormatter
AssertionFormatterFacade	can most likely be removed	can most likely be removed	can most likely be removed
TextListAssertionGroupFormatter	TextListExpectationGroupFormatter	TextListReportGroupFormatter	TextListRecordGroupFormatter
HtmlListAssertionGroupFormatter (does not yet exist)	HtmlListExpectationGroupFormatter	HtmlListExpectationGroupFormatter	HtmlListRecordGroupFormatter
DescriptionAnyAssertion	DescriptionOfAnyExpectations	DescriptionOfAnyReports	DescriptionOfAnyRecords

[robstoll]

Oho... I figured I am going to start rewording assertion to expectation in the readme. The following would be bad I think:
Atrium is an open-source multiplatform expectation library for Kotlin with support for JVM, JS and Android. The term assertion library is so common whereas expectation library is not known at all 🤔
I guess I will keep assertion library but replace assertion with exception in other places