Add code comments for the recent assertions fix.

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;

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;