Discussion on Should, Must and the RFC-2119

[macrogreg]

Apologies for the duplication. I submitted an issue on this (#1922) and then resized that discussions are active for this project, so re-posting here. Not sure what the maintainers consider the more appropriate place, so sorry for the dup.

---

Background

This is not a bug, but rather a question / suggestion for the future. :)
Fluent Assertions is a brilliant framework. I am glad that it exists and I am grateful to the authors.

There is one thing about it that bugs me a lot. It is likely just due to my being overly compulsive about naming things in a deliberate and correct manner, yet I would be very interested and grateful to to learn whether there are others who feel similar. :)

My question is about a central concept of Fluent Assertions: the Should(..) method.

Fluent Assertions does an amazing job making assertions read easily. Yet, a test case is also a "specification" of how the tested code is expected to behave. And, there exists a de-factor standard that describes guidelines for the English words to use in requirements specifications: the infamous RFC 2119.

Based on that, what Fluent Assertions expresses using Should(..), MUST really me expressed using the verb "must".

For those who are not familiar, the aforementioned RFC is extremely short, check it out. The relevant part is:

• MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
• SHOULD: This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

Question 1: History

I am curious to learn the authors' thoughts on this topic. Did the choice Should(..) vs. Must(..) come up explicitly in the early days of Fluent Assertions? If yes, what were the reasons for the choice taken? Or was it the case that by the time this came up, there was already so much code in the wild based on Should(..) that a change could not be realistically considered for compatibility reasons? Or, perhaps, I am the only one worried about it? :)

Question 2: Future / Adjustments

Assume that after learning some of the background in question 1 I wanted to use RFC-2119-style working in my own assertions, i.e. I wanted to replace Should(..) with Must(..). Assume also that I wanted to share the solution for doing that with the community in case other people like that idea and want to apply it in a way that does not disrupt Fluent Assertions at its core.
In the context of the fact that I am in no way an exert on the internals of Fluent Assertions, would the authors (or any of the experts) have some guidance on the implementation strategy?

Based on a first looks, it seems that it may be possible to duplicate the AssertionExtensions class and to define a Must(..) equivalent for every of the Should(..) overloads found there.

If I did so,

• would it be preferable to just call through to the corresponding Should(..) version,
• or to use the same implementation body as the respective Should(..) without actually calling into it?

Would such an approach break anything around the stack walks done by the framework?
Are there any other gotchas I should expect?
Would there be any interest in including such an optional extension in some way into Fluent Assertions directly? Perhaps tucked away into a sub-namespace or in some other non-disruptive manner?
If this whole topic a crazy idea? :)

Conclusion

I realize that people are busy. I respect your time and because of that I am ever more grateful for any feedback I might get from
Fluent Assertions experts on this topic.

Thank you.

[dennisdoomen]

Thank you for raising this discussion. I actually remembered that I regretted my choice to go for should many years ago. I'm quite open to the idea of switching to must in the next major release, depending on the feedback from the community.

[dagilleland]

Reminds me of the regret Tony Hoare had over creating the Null Reference concept.

[IT-VBFK]

Same here :)

If a test only should be true, why are we testing ;)

A test IMHO have to be a particular scenario which have to pass... otherwise this test is useless

[dennisdoomen]

https://twitter.com/ddoomen/status/1522295222478249984

[jnyrup]

Q1:
I can't comment much on the early history since the project was already ~6 years old when I joined.
Had we created the library today Must might well have been the better choice, it's also two characters shorter than Should.

I'm often conservative about changes (my comments across issues and PRs will confirm), but renaming Should to Must is probably the most breaking change I can think of.
To list some things it would break:

• ABI
• API
• Several nuget packages extending Fluent Assertions
• Documentation
• StackOverflow questions and answers
• Tutorials and examples all over the internet
• Every assertion written in all code bases consuming FA
• (My muscle memory)

I don't think the change outweights what it breaks.

Q2:
I haven't tried out making a clone of Should named Must that calls the constructors directly, but our code expects .Should( to be present in the call stack and I think it might also have some expectation that the subject comes right before .Should(.

fluentassertions/Src/FluentAssertions/CallerIdentification/ShouldCallParsingStrategy.cs

Line 7 in c33006c

private const string ShouldCall = ".Should(";

If you intend to proceed with making extension methods, I'm much open to see if we can adjust/extend the caller identification code to support using Must (or possibly any other word) in addition to Should.

[macrogreg]

Thanks, folks, for the discussion.
I agree on the heavy impact of such a change, and that if it would be considered at all, it would need to be offered to the public in a way that carefully manages the breaking changes.

My wild guess is that during the vote on twitter, the breaking changes were a driving factor.
Although, personally, I'd go with var.Please().BeTrue(); 😄

I have a very full schedule for May, but I suggest that in June I spend some time on trying to make the .Must(..) extension methods work. Once I am working on it, I'll ask for some pointers for what needs to be tweaked except for the extension methods themselves. If the required changes are reasonable and can be made to the system without too much churn, then we can make them and offer the "Must" package in any way you prefer: completely separately (independent extension), as a separate, optional package of FluentAssertions, or as an optional feature within FluentAssertions.

Does that sound reasonable from your perspective?

[jnyrup]

Take your time to experiment as it's not blocking anyone.
Share your findings and let's then discuss what the best path forward might be.

[DanStevens]

I find this topic interesting as I am often writing characterization tests for legacy code, in which case the term 'Should' is somewhat unfitting because I'm writing to tests to describe what the code does as-is without respect to correctness. The more fitting term here would be 'Is', but unfortunately that doesn't fit well with FluentAssertions since LegacyMethod().Is.Be(true) is no longer proper English. LegacyMethod().Is(true) would be nice but I imagine that would be a bigger change than 'Should' to 'Must'. I suppose 'Appears To' (e.g. AppearsTo.Be(true)) would fit the syntax better while still being fluent, although it does sound a bit contrived.

[dennisdoomen]

It should be relatively easy to support Must next to Should