Improving assertion consistency, fluency and conventions in v5

[mindplay-dk]

Since v5 will be a major release, how about nixing some of the assertion aliases?

export const Assert = {
  equal,
  //equals: equal,
  //eq: equal,
  //deepEqual: equal,
  //same: equal,
  notEqual,
  //notEquals: notEqual,
  //notEq: notEqual,
  //notDeepEqual: notEqual,
  //notSame: notEqual,
  is,
  isNot,
  ok,
  //truthy: ok,
  notOk,
  //falsy: notOk,
  fail,
  throws,
};

It's an opinion, of course - but I don't find the aliases do anything to help with comprehension, they just muddy things and raise questions... "what's the difference between equal, deepEqual and same?" - in some frameworks, these mean different things. In my opinion, it would be better not to waste time deciphering ambiguous terminology, debating which ones to use, refactoring in codebases with multiple contributors, and so on. (same is particularly confusing here, because, in some frameworks, that word is used for identity comparison, which is what is does in zora.)

I also would love it if the assertion object could have a better name (solely by convention, of course) than t - something that made sense for all the standard assertion names. Personally, I use is, which works for almost all assertions:

test("something", is => {
  is.equal(...);
  is.notEqual(...);
  is.is(...); // ?
  is.isNot(...) // is.not(...) ?
  is.ok(...);
  is.notOk(...);
  is.fail(...); // is.failure(...) ?
  is.throws, // is.thrown(...) ?
};

It doesn't work well for all cases - I wish we could have used test, but, obviously not. check or assert is clumsy to type, which is probably why you went with t in the first place.

If we can't think of a meaningful, keyboard friendly name for this, maybe consider getting rid of the name altogether, and make it conventional to destructure instead, since that's an option now?

test("something", ({ isEqual, isNotEqual, isSame, isNotSame, isOk, isNotOk, isFailure, isException }) => {
  // ...
};

Of course, the assertions are a little less close at hand if the convention is to unpack them declaratively in this way.

I currently use a mix of these styles in my own tests - I'll unpack throws for example, and leave the rest as is:

test("something", ({ throws, ...is }) => {
  is.equal(...);
  is.ok(...);
  throws(...);
};

This reads more like "language", but makes it less obvious where the assertions are - you don't immediately spot things like throws when you're probably skimming for is.

I'm not proposing a solution here - I'm inviting to think about an API and conventions that read more fluently in v5. 😏

[lorenzofox3]

how about nixing some of the assertion aliases?

I would keep the aliases because everyone has its own preferences (I personally only use eq and ok), however we can put the emphasis on the "main" methods so aliases are details for the most curious users.

ex:

doc.md

### equal(actual, expected, [description])

performs a deep equal check 

(aliases: ``eq``, ``deepEqual``, etc)

Regarding same I had the same expectations than yours and it was implemented that way in the first place but people coming from node-tap were confused apparently (#39, #64) and I changed it.

If we can't think of a meaningful, keyboard friendly name for this, maybe consider getting rid of the name altogether, and make it conventional to destructure instead, since that's an option now?

I like this idea (naming is hard)

[mindplay-dk]

The problem with the aliases isn't so much a documentation problem - the issue is, all of these show up in autocomplete suggestions, forcing you to consider all of the aliases when picking from the available assertions.

Having a smaller number of assertions you have to choose from is a good thing. Having consistent test suites is a good thing.

If people have strong opinions about the function names, in v5, it would be easy enough to create any alias you want.

You could even add an optional package with the legacy aliases, and folks can optional import that.

I just would prefer if we could start out clean? Give people the choice to make a whole mess of aliases or not 😉

[lorenzofox3]

Hey, I do not manage to mention you in the following discussion, can you please have a look and let me know your first impressions. thanks.

LR