assert: support inequalities

[RedYetiDev]

This PR introduces four new assertion methods

Motivation

These methods align with the capabilities provided by other popular testing libraries, such as:

• Jest: toBeGreaterThan
• Chai: above
• Vitest: isAbove

While it’s possible to use standard assertions like assert(x > y), dedicated methods offer more informative error messages by including displaying the values of x and y in the failure output. This saves time and effort, particularly when working with large test suites, as there’s no need to manually format output with assert(x > y, `${x} > ${y}`).

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.41%. Comparing base (58a8eb4) to head (1eb4315).
Report is 8 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #55796   +/-   ##
=======================================
  Coverage   88.40%   88.41%           
=======================================
  Files         654      654           
  Lines      187815   187891   +76     
  Branches    36136    36145    +9     
=======================================
+ Hits       166045   166130   +85     
- Misses      15001    15003    +2     
+ Partials     6769     6758   -11     

Files with missing lines	Coverage Δ
lib/assert.js	99.88% <100.00%> (+0.01%)	⬆️
lib/internal/test_runner/test.js	96.98% <100.00%> (+<0.01%)	⬆️

... and 29 files with indirect coverage changes

[aduh95]

This PR goes against Node.js core principles, we're all idealist people who strive for a better world, we do not and never will want to support inequalities!

[MoLow]

besides naming, LGTM

[RedYetiDev]

Would you rather lessThanOrEqual or lessThanOrEqualTo?

[marco-ippolito]

shouldnt we validate that inputs are numbers?

[LiviaMedeiros]

I feel +1 for having this whenever I see assert(actual < expectedMax) without message just to see the actual value; but the implementation raises questions, especially if we want it to be a part of public API.

node:assert has Legacy and Strict modes. The current implementation feels like a part of Legacy mode, because inequality operators work similar to == rather than ===.
Do we want to add new methods to Legacy mode?
Do we want to have both versions?
What value types do we want to support? Do we allow lessThan(false, 2)? lessThan(1, 2n)? lessThan('a', 'b')? lessThan([], [1])?
Do we want type validation to be configurable?
Will it match the expectations for everyone?

An important thing to consider is that message is the key here.

// `false == true` not informative, have to look at the code
assert(retryCount < RETRY_MAX);

// `Expected 5 to be less than 5` tells the compared values but still not informative
assert.lessThan(retryCount, RETRY_MAX);

// Informative, both lines yield same message
assert(retryCount < RETRY_MAX, `retryCount has value of ${retryCount} which is greater than RETRY_MAX`);
assert.lessThan(retryCount, RETRY_MAX, `retryCount has value of ${retryCount} which is greater than RETRY_MAX`);

// Even better when message tells the context of error
assert(retryCount < RETRY_MAX, 'function myFunc retried too many times when delay is set to 0 and data is recursive')

The current implementation uses message as is if it's present, so it becomes just a slower and more verbose version of assert.ok.

If we make strict version with type validation, how do we handle the case when types are not matched? E.g.:

// Old code without explicit `assert.equal(typeof retryCount, 'number')`
assert.ok(retryCount <= RETRY_MAX, `retry count greater than ${RETRY_MAX}`);

// New code?
assert.strictNotGreaterThan(retryCount, RETRY_MAX, `retry count greater than ${RETRY_MAX} OR retry count's type ${typeof retryCount} is not number`);

[RedYetiDev]

Sounds good to me. Currently, as you said, I do use the message property, but then difference that the error contains the "actual" and "expected" failures as properties.

I could also do what the other assertion methods do, that is, have their own message that displays along with the user provided message.