From e269bb6006b9cc283b74bee31e37a43491fae319 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinkle@fastmail.com>
Date: Tue, 28 Jun 2022 11:46:23 -0700
Subject: [PATCH] Docs: Avoid "bad example" when "failing example" is intended

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.
---
 docs/assert/deepEqual.md  |  6 +++---
 docs/assert/notEqual.md   | 12 ++++++------
 docs/assert/pushResult.md | 38 +++++++++++++++++++++++---------------
 3 files changed, 32 insertions(+), 24 deletions(-)

diff --git a/docs/assert/deepEqual.md b/docs/assert/deepEqual.md
index 33188e6ba..33946c7dd 100644
--- a/docs/assert/deepEqual.md
+++ b/docs/assert/deepEqual.md
@@ -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',
diff --git a/docs/assert/notEqual.md b/docs/assert/notEqual.md
index 01c393064..b16bb4bab 100644
--- a/docs/assert/notEqual.md
+++ b/docs/assert/notEqual.md
@@ -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);
 });
 ```
diff --git a/docs/assert/pushResult.md b/docs/assert/pushResult.md
index 270561cba..53cbb14aa 100644
--- a/docs/assert/pushResult.md
+++ b/docs/assert/pushResult.md
@@ -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()
 });
 ```