Assertion Verbs

[CfGit12]

Disclaimer: I'm aware I can customise the assertion verbs, but generally speaking I'd not expect to have to do this without exceptional circumstances.

I find the out of the box assertion verbs to be a little bit muddled. I'm going to give a few examples of both expect and assertThat to illustrate my point. Firstly expect:

expect(x).toBe(y) makes sense and reads well.

expect(x).isLessThan(y) does not read well. I would expect expect(x).toBeLessThan(y).

expect(x).containsOnly(y) isn't as bad but is still a bit iffy. Would prefer expect(x).toContainOnly(y).

expect {}.toThrow reads well.

Using the assertThat notation we have:

assertThat(x).toBe(y) which doesn't read well at all. I would expect isEqualTo to be included for this case.

assertThat(x).isLessThan(y) on the other hand does read well in this case.

assertThat(x).containsOny(y) reads well.

assertThat {}.toThrow does not read well.

Essentially out of the box both expect and assertThat have problems. The assertions themselves feel like they're not written consistently for the assertion prefix they're expecting.

I don't have any particular preference over expect and assertThat but as it stands each of them have issues. When I come to demo this library to my team this will be the first thing they see and for me it sticks out a bit.

[robstoll]

@CfGit12 thanks for your feedback, very much appreciated.

expect(x).isLessThan(y) does not read well. I would expect expect(x).toBeLessThan(y).

We are going to rewrite the API with the up-coming version to a consistent to + infinitive form, i.e. isLessThan well be renamed to toBeLessThan as you suggest. You can read more about it and give further feedback/ideas here robstoll/atrium-roadmap#93. For instance, one open point. shall we provide only toBeA as replacement of isA or should we have toBeAn additionally or use a totally different name?

That said, maybe we should remove assertThat as predefined assertion-verb as it will not read nice as you pointed out. I think assert(x).toBeLessThan(y) still reads fine but maybe it makes more sense to have only one assertion verb?

Last but not least, let me know in case you have free capacities and could help to rename stuff, we could use your help.

[CfGit12]

Excellent :)

Posted a couple of thoughts in the other issue.

I don't really have any availability to directly contribute I'm afraid but happy to provide feedback when required.