Add `assertThat` alias for `check`

[passsy]

Choosing a catchy keyword for an assertion library is hard. I thought long about this, because I was about to publish a similar library. I will not publish it in favor of checks but I want to share my findings.

Keyword analysis

assert

The best keyword for assertions would be assert. Like many other libs in many languages do:

assert.strictEqual(z, 6); // mochajs
assert.typeOf(foo, 'string'); // chaijs
assert.equals(requests.length, 1); // sinonjs
assertEquals(2, calculator.add(1, 1)); // junit5
assert Example.hello() == :world // elixir
assert_eq!(2 + 2, 4); // rust
XCTAssert(viewModel.users.count == 0) // switft
assertEquals(2+ 2, 4) // kotlin.test 

But we can't because assert is a language keyword that can't be used.

assertThat

An abbreviation of assert is assertThat, which became very popular in the java world, still heavily used with AssertJ.

assertThat(frodo.getAge()).isEqualTo(33); // AssertJ
assertThat(actual, equalTo(expected)) // hamcreset
assertThat(person.name).isEqualTo("Alice") // assertk
assertThat(actual).isEqualTo(expected) // truth

expect

expect is commonly used in the js world.

expect(sum(1, 2)).toBe(3); // jest
expect(a).toBe(true); // jasmine
expect(foo).to.be.a('string'); // chaijs
expect(actual).notToBe(unexpected) // artrium

expectThat(actual).isEqualTo(expected) // strikt

It would be great, but expect is already widely used by package:test and would be confusing.

check

I could not find any other assertion library using it

Conculsion

I really wanted assert in the name, the second best option is assertThat.

From my experience, it has a significant advantage over check or expect. It is characteristic and easy to spot in code. When I scan tests for assertions, assertThat stands out in java code. expect in dart code not so much, neither does check.

Wish

check will not be replaced with assertThat, especially since it was just changed from checkThat to check.

I wish package:checks would allow for more freedom of keywords, creating an alias and allow assertThat officially. Like chaijs does, it allows expect, should and assert equally.

[natebosch]

Your evaluation closely matches some internal discussion we had.

There is a background in other languages beyond Java for assertThat too, it's fairly common in other testing frameworks in other languages. This was a really strong contender for the chosen name (and we would have probably named the package package:asserts) based mainly on consistency with other ecosystems. There is nothing fundamentally blocking us from going this route if we decide the name is worth it as the default for everyone.

Another benefit for assertThat is the clear association with throwing an exception on failure.

The main reason I avoided assertThat was worry that people would confuse it against assert, which has very different tradeoffs in terms of when it should be used, and very different behavior. I'm worried that people might thing that --no-enable-asserts might somehow interact with assertThat.

Another reason that surfaced later is that check is shorter, and doesn't have a capital letter. One of the reasons to rename from checkThat to check was to make that part of the expression as visually unintrusive as possible, and check does a much better job there than assertThat.

One thing I noticed about the assertThat choice in at least one Java testing library, is that the authors chose it almost exclusively because of it's legacy in the Java ecosystem, and it isn't necessarily the name they would have chosen without that pressure. I don't know how much I want to let the legacy of other languages carry through here, and the within ecosystem pressure would push toward expect which we explicitly want to avoid.

creating an alias and allow assertThat officially

I think it's unlikely we'll add an alias - this package is will focus on delivering one solution, and my hope is that an ecosystem need for alternative styles can be built on top of it (or entirely independent of it - one of the goals in replacing matcher is to make it more possible to alternatives to thrive in the ecosystem).

it allows expect, should and assert equally.

There is a chance we'll add an assume and expectThat (or some other name - trying to avoid conflict with the legacy expect to make migrations as easy as possible) with different behaviors to check. https://github.com/dart-lang/test/pull/1898

If we go that route I think it adds another argument to not ship an alias in this package - the different names would focus on different behavior, not different style.