From a9ab3511a46bb138a9ec10385f0c073bc335625b Mon Sep 17 00:00:00 2001
From: Priyansh Garg <priyanshgarg30@gmail.com>
Date: Tue, 22 Oct 2024 16:29:38 +0530
Subject: [PATCH] Add code comments for the recent assertions fix.

---
 lib/api/web-element/assert/element-assertions.js | 6 +++++-
 lib/api/web-element/assert/value-assertions.js   | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/lib/api/web-element/assert/element-assertions.js b/lib/api/web-element/assert/element-assertions.js
index 3fe999212..170e8b3fb 100644
--- a/lib/api/web-element/assert/element-assertions.js
+++ b/lib/api/web-element/assert/element-assertions.js
@@ -8,6 +8,10 @@ class ScopedElementAssertions {
   }
 
   assert(callback) {
+    // The below promise is returned to the test case by the assertion, so
+    // it should fail in case the actual assertion (callback) fails. In case
+    // of a sync test, the actual assertion would never fail, so we always
+    // resolve the promise.
     const assertPromise = new Promise((resolve, reject) => {
       const assert = this.nightwatchInstance.api.assert;
 
@@ -26,7 +30,7 @@ class ScopedElementAssertions {
     });
 
     // prevent unhandledRejection errors, while also making sure
-    // that the exception passes to the actual test case.
+    // that the exception/failure passes to the actual test case.
     assertPromise.catch(() => {});
 
     return assertPromise;
diff --git a/lib/api/web-element/assert/value-assertions.js b/lib/api/web-element/assert/value-assertions.js
index d243bb441..e21088f18 100644
--- a/lib/api/web-element/assert/value-assertions.js
+++ b/lib/api/web-element/assert/value-assertions.js
@@ -9,6 +9,10 @@ module.exports.create = function createAssertions(scopedValue, {negated, nightwa
     }
 
     _assert(callback) {
+      // The below promise is returned to the test case by the assertion, so
+      // it should fail in case the actual assertion (callback) fails. In case
+      // of a sync test, the actual assertion would never fail, so we always
+      // resolve the promise.
       const assertPromise = new Promise((resolve, reject) => {
         const assert = nightwatchInstance.api.assert;
         const callbackResult = callback(this.negated ? assert.not : assert, this.scopedValue.value);
@@ -26,7 +30,7 @@ module.exports.create = function createAssertions(scopedValue, {negated, nightwa
       });
 
       // prevent unhandledRejection errors, while also making sure
-      // that the exception passes to the actual test case.
+      // that the exception/failure passes to the actual test case.
       assertPromise.catch((err) => {});
 
       return assertPromise;