Skip to content

Commit

Permalink
Docs: Avoid "bad example" when "failing example" is intended
Browse files Browse the repository at this point in the history
There are some pages where we use good/bad to indicate whether
the way a test is written is recommended or not.

But on deepEqual and notEqual, what we meant was actually whether
the test is passing or failing. Refer to it as such instead, this
is also consistent with what we write on other pages already.
  • Loading branch information
Krinkle committed Sep 14, 2022
1 parent fec7c1a commit e269bb6
Show file tree
Hide file tree
Showing 3 changed files with 32 additions and 24 deletions.
6 changes: 3 additions & 3 deletions docs/assert/deepEqual.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,15 @@ To assert strict equality on own properties only, refer to [`assert.propEqual()`
Validate the properties and values of a given object.

```js
QUnit.test('good example', assert => {
QUnit.test('passing example', assert => {
const result = { foo: 'bar' };

assert.deepEqual(result, { foo: 'bar' }, 'result object');
assert.deepEqual(result, { foo: 'bar' });
});
```

```js
QUnit.test('bad example', assert => {
QUnit.test('failing example', assert => {
const result = {
a: 'Albert',
b: 'Berta',
Expand Down
12 changes: 6 additions & 6 deletions docs/assert/notEqual.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,18 +30,18 @@ The `notEqual` assertion uses the simple inverted comparison operator (`!=`) to
The simplest assertion example:

```js
QUnit.test('good example', assert => {
QUnit.test('passing example', assert => {
const result = '2';

// succeeds, 1 and 2 are different.
assert.notEqual(result, 1, 'string and number');
assert.notEqual(result, 1);
});

QUnit.test('bad example', assert => {
QUnit.test('failing example', assert => {
const result = '2';

// fails, the number 2 and the string "2" are actually considered equal
// when loosely compared. Use notStrictEqual instead to consider them different
assert.notEqual(result, 2, 'string and number');
// fails, the number 2 and the string "2" are considered equal when
// compared loosely. Use `assert.notStrictEqual` to consider them different.
assert.notEqual(result, 2);
});
```
38 changes: 23 additions & 15 deletions docs/assert/pushResult.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,29 +23,37 @@ Report the result of a custom assertion.
If you need to express an expectation that is not abstracted by a built-in QUnit assertion, you can perform your own logic ad-hoc in an expression, and then pass two directly comparable values to [`assert.strictEqual()`](./strictEqual.md), or pass your own representative boolean result to [`assert.true()`](./true.md).

```js
QUnit.test('bad example with remainder', assert => {
const result = 3;
const actual = (result % 2) === 1;
assert.true(actual, 'remainder of mod 2 is 1');
// In case of failure, there is no information about the
// actually observed remainder or the expected value
QUnit.test('bad example of remainder', assert => {
const result = 4;
const actual = (result % 3) === 2;
assert.true(actual, 'remainder');
// In case of failure:
// > Actual: false
// > Expected: true
//
// No mention of the actual remainder.
// No mention of the expected value.
});

QUnit.test('good example with remainder', assert => {
const result = 3;
assert.strictEqual(result % 2, 1, 'remainder of mod 2');
QUnit.test('good example of remainder', assert => {
const result = 4;
assert.strictEqual(result % 3, 2, 'remainder');
// In case of failure:
// > Actual: 1
// > Expected: 2
});

QUnit.test('example with value in range', assert => {
QUnit.test('bad example of between', assert => {
const actual = 3;
const isBetween = (actual >= 1 && actual <= 10);
assert.true(isBetween, 'result between 1 and 10');
// No information in case of failure.
// Cannot be expressed in a useful way using strictEqual()
// In case of failure:
// > Actual: false
// > Expected: true
//
// Example of failure if result is out of range:
// > actual: false
// > expected: true
// No mention of the actual remainder.
// No mention of the expected value.
// Cannot be expressed in a useful way with strictEqual()
});
```

Expand Down

0 comments on commit e269bb6

Please sign in to comment.