1.3.0

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2024-12-30 - 1.3.0 - feat(Assertion)
+Refactor Assertion class for better error handling and code clarity
+
+- Improved method runCheck to better handle async and sync execution
+- Enhanced getObjectToTestReference to handle undefined or null values gracefully
+- Refactored error message logic for clarity and added more descriptive fail messages
+- Added arrayItem method for better handling of array index access
+- Improved structure by integrating consistent error handling in assertion methods
+
 ## 2024-08-24 - 1.2.1 - fix(Assertion)
 Refactor methods for setting failure and success messages
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartexpect",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "private": false,
   "description": "A testing library to manage expectations in code, offering both synchronous and asynchronous assertion methods.",
   "main": "dist_ts/index.js",
@@ -18,8 +18,8 @@
     "@gitzone/tsbundle": "^2.0.8",
     "@gitzone/tsrun": "^1.2.44",
     "@gitzone/tstest": "^1.0.77",
-    "@push.rocks/tapbundle": "^5.0.23",
-    "@types/node": "^22.4.0"
+    "@push.rocks/tapbundle": "^5.5.0",
+    "@types/node": "^22.9.0"
   },
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.5",

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartexpect',
-  version: '1.2.1',
+  version: '1.3.0',
   description: 'A testing library to manage expectations in code, offering both synchronous and asynchronous assertion methods.'
 }

ts/smartexpect.classes.assertion.ts

@@ -5,9 +5,13 @@ export type TExecutionType = 'sync' | 'async';
 export class Assertion {
   executionMode: TExecutionType;
   baseReference: any;
-  propertyDrillDown: string[] = [];
+  propertyDrillDown: Array<string | number> = [];
+
   private notSetting = false;
   private timeoutSetting = 0;
+  private failMessage: string;
+  private successMessage: string;
+
   constructor(baseReferenceArg: any, executionModeArg: TExecutionType) {
     this.baseReference = baseReferenceArg;
     this.executionMode = executionModeArg;
@@ -16,6 +20,14 @@ export class Assertion {
   private getObjectToTestReference() {
     let returnObjectToTestReference = this.baseReference;
     for (const property of this.propertyDrillDown) {
+      if (returnObjectToTestReference == null) {
+        // if it's null or undefined, stop
+        break;
+      }
+
+      // We just directly access with bracket notation.
+      // If property is a string, it's like obj["someProp"];
+      // If property is a number, it's like obj[0].
       returnObjectToTestReference = returnObjectToTestReference[property];
     }
     return returnObjectToTestReference;
@@ -31,13 +43,11 @@ export class Assertion {
     return this;
   }
 
-  private failMessage: string;
   public setFailMessage(failMessageArg: string) {
     this.failMessage = failMessageArg;
     return this;
   }
 
-  private successMessage: string;
   public setSuccessMessage(successMessageArg: string) {
     this.successMessage = successMessageArg;
     return this;
@@ -72,7 +82,7 @@ export class Assertion {
             }
           });
         }
-        this.baseReference.then((promiseResultArg) => {
+        this.baseReference.then((promiseResultArg: any) => {
           this.baseReference = promiseResultArg;
           done.resolve(runDirectOrNegated(checkFunction));
         });
@@ -83,27 +93,23 @@ export class Assertion {
     }
   }
 
-  /**
-   * checks if the given object is defined
-   */
   public toBeDefined() {
     return this.runCheck(() => {
       if (this.getObjectToTestReference() === undefined) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not defined`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not defined`
         );
       }
     });
   }
 
-  /**
-   * checks if the given object is not defined
-   */
   public toBeTypeofString() {
     return this.runCheck(() => {
       if (typeof this.getObjectToTestReference() !== 'string') {
         throw new Error(
-          this.failMessage || `Assertion failed: ${this.baseReference} with drill down ${
+          this.failMessage ||
+            `Assertion failed: ${this.baseReference} with drill down ${
               this.propertyDrillDown
             } is not of type string, but typeof ${typeof this.baseReference}`
         );
@@ -115,7 +121,8 @@ export class Assertion {
     return this.runCheck(() => {
       if (typeof this.getObjectToTestReference() !== 'number') {
         throw new Error(
-          this.failMessage || `Assertion failed: ${this.baseReference} with drill down ${
+          this.failMessage ||
+            `Assertion failed: ${this.baseReference} with drill down ${
               this.propertyDrillDown
             } is not of type string, but typeof ${typeof this.baseReference}`
         );
@@ -127,7 +134,8 @@ export class Assertion {
     return this.runCheck(() => {
       if (typeof this.getObjectToTestReference() !== 'boolean') {
         throw new Error(
-          this.failMessage || `Assertion failed: ${this.baseReference} with drill down ${
+          this.failMessage ||
+            `Assertion failed: ${this.baseReference} with drill down ${
               this.propertyDrillDown
             } is not of type string, but typeof ${typeof this.baseReference}`
         );
@@ -140,7 +148,8 @@ export class Assertion {
       const result = plugins.fastDeepEqual(this.getObjectToTestReference(), comparisonObject);
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not equal ${comparisonObject}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} does not equal ${comparisonObject}`
         );
       }
     });
@@ -151,7 +160,10 @@ export class Assertion {
       const result = comparisonObject.test(this.getObjectToTestReference());
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not equal ${comparisonObject}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not match regex ${comparisonObject}`
         );
       }
     });
@@ -164,7 +176,8 @@ export class Assertion {
         this.getObjectToTestReference() === true;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not true or not of type boolean`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not true or not of type boolean`
         );
       }
     });
@@ -177,7 +190,8 @@ export class Assertion {
         this.getObjectToTestReference() === false;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not false or not of type boolean`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not false or not of type boolean`
         );
       }
     });
@@ -188,7 +202,8 @@ export class Assertion {
       const result = this.getObjectToTestReference() instanceof classArg;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not an instance of ${classArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not an instance of ${classArg}`
         );
       }
     });
@@ -196,16 +211,22 @@ export class Assertion {
 
   public toHaveProperty(propertyArg: string, equalsArg?: any) {
     return this.runCheck(() => {
-      const result = !!this.getObjectToTestReference()[propertyArg];
-      if (!result) {
+      const obj = this.getObjectToTestReference();
+      if (!obj || !(propertyArg in obj)) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not have property ${propertyArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not have property ${propertyArg}`
         );
       }
-      if (equalsArg) {
-        if (result !== equalsArg) {
+      if (equalsArg !== undefined) {
+        if (obj[propertyArg] !== equalsArg) {
           throw new Error(
-            this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does have property ${propertyArg}, but it does not equal ${equalsArg}`
+            this.failMessage ||
+              `${this.baseReference} with drill down ${
+                this.propertyDrillDown
+              } does have property ${propertyArg}, but it does not equal ${equalsArg}`
           );
         }
       }
@@ -225,7 +246,10 @@ export class Assertion {
         }
 
         if (!obj || !(property in obj)) {
-          throw new Error(this.failMessage || `Missing property at path "${currentPath}" in ${this.baseReference}`);
+          throw new Error(
+            this.failMessage ||
+              `Missing property at path "${currentPath}" in ${this.baseReference}`
+          );
         }
         obj = obj[property];
       }
@@ -237,7 +261,8 @@ export class Assertion {
       const result = this.getObjectToTestReference() > numberArg;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not greater than ${numberArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not greater than ${numberArg}`
         );
       }
     });
@@ -248,7 +273,8 @@ export class Assertion {
       const result = this.getObjectToTestReference() < numberArg;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not less than ${numberArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not less than ${numberArg}`
         );
       }
     });
@@ -259,7 +285,8 @@ export class Assertion {
       const result = this.getObjectToTestReference() === null;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not null`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not null`
         );
       }
     });
@@ -270,7 +297,8 @@ export class Assertion {
       const result = this.getObjectToTestReference() === undefined;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not undefined`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not undefined`
         );
       }
     });
@@ -278,26 +306,27 @@ export class Assertion {
 
   public toBeNullOrUndefined() {
     return this.runCheck(() => {
-      const result =
-        this.getObjectToTestReference() === null || this.getObjectToTestReference() === undefined;
+      const testRef = this.getObjectToTestReference();
+      const result = testRef === null || testRef === undefined;
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not null or undefined`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not null or undefined`
         );
       }
     });
   }
 
-  // Array
+  // Array checks
 
   public toContain(itemArg: any) {
     return this.runCheck(() => {
-      const result =
-        this.getObjectToTestReference() instanceof Array &&
-        this.getObjectToTestReference().includes(itemArg);
+      const testRef = this.getObjectToTestReference();
+      const result = Array.isArray(testRef) && testRef.includes(itemArg);
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not contain ${itemArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} does not contain ${itemArg}`
         );
       }
     });
@@ -307,7 +336,10 @@ export class Assertion {
     return this.runCheck(() => {
       const arrayRef = this.getObjectToTestReference();
       if (!Array.isArray(arrayRef) || arrayRef.length !== 0) {
-        throw new Error(this.failMessage || `Expected ${this.baseReference} to be an empty array, but it was not.`);
+        throw new Error(
+          this.failMessage ||
+            `Expected ${this.baseReference} to be an empty array, but it was not.`
+        );
       }
     });
   }
@@ -316,13 +348,18 @@ export class Assertion {
     return this.runCheck(() => {
       const arrayRef = this.getObjectToTestReference();
       if (!Array.isArray(arrayRef)) {
-        throw new Error(this.failMessage || `Expected ${this.baseReference} to be an array.`);
+        throw new Error(
+          this.failMessage ||
+            `Expected ${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } to be an array.`
+        );
       }
-
       for (const value of values) {
         if (!arrayRef.includes(value)) {
           throw new Error(
-            this.failMessage || `Expected ${this.baseReference} to include value "${value}", but it did not.`
+            this.failMessage ||
+              `Expected ${this.baseReference} to include value "${value}", but it did not.`
           );
         }
       }
@@ -333,12 +370,17 @@ export class Assertion {
     return this.runCheck(() => {
       const arrayRef = this.getObjectToTestReference();
       if (!Array.isArray(arrayRef)) {
-        throw new Error(this.failMessage || `Expected ${this.baseReference} to be an array.`);
+        throw new Error(
+          this.failMessage ||
+            `Expected ${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } to be an array.`
+        );
       }
-
       if (arrayRef.includes(value)) {
         throw new Error(
-          this.failMessage || `Expected ${this.baseReference} to exclude value "${value}", but it included it.`
+          this.failMessage ||
+            `Expected ${this.baseReference} to exclude value "${value}", but it included it.`
         );
       }
     });
@@ -350,7 +392,10 @@ export class Assertion {
       const result = typeof testObject === 'string' && testObject.startsWith(itemArg);
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not contain ${itemArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not start with ${itemArg}`
         );
       }
     });
@@ -362,20 +407,22 @@ export class Assertion {
       const result = typeof testObject === 'string' && testObject.endsWith(itemArg);
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not contain ${itemArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not end with ${itemArg}`
         );
       }
     });
   }
 
-  // ... previous code ...
-
   public toBeOneOf(values: any[]) {
     return this.runCheck(() => {
       const result = values.includes(this.getObjectToTestReference());
       if (!result) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not one of ${values}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not one of ${values}`
         );
       }
     });
@@ -386,7 +433,10 @@ export class Assertion {
       const obj = this.getObjectToTestReference();
       if (typeof obj.length !== 'number' || obj.length !== length) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not have a length of ${length}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not have a length of ${length}`
         );
       }
     });
@@ -397,7 +447,10 @@ export class Assertion {
       const difference = Math.abs(this.getObjectToTestReference() - value);
       if (difference > Math.pow(10, -precision) / 2) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not close to ${value} up to ${precision} decimal places`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } is not close to ${value} up to ${precision} decimal places`
         );
       }
     });
@@ -412,7 +465,8 @@ export class Assertion {
         thrown = true;
         if (expectedError && !(e instanceof expectedError)) {
           throw new Error(
-            this.failMessage || `Expected function to throw ${expectedError.name}, but it threw ${e.name}`
+            this.failMessage ||
+              `Expected function to throw ${expectedError.name}, but it threw ${e.name}`
           );
         }
       }
@@ -426,7 +480,8 @@ export class Assertion {
     return this.runCheck(() => {
       if (!this.getObjectToTestReference()) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not truthy`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not truthy`
         );
       }
     });
@@ -436,7 +491,8 @@ export class Assertion {
     return this.runCheck(() => {
       if (this.getObjectToTestReference()) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not falsy`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not falsy`
         );
       }
     });
@@ -444,9 +500,12 @@ export class Assertion {
 
   public toBeGreaterThanOrEqual(numberArg: number) {
     return this.runCheck(() => {
-      if (this.getObjectToTestReference() <= numberArg) {
+      if (this.getObjectToTestReference() < numberArg) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not greater than or equal to ${numberArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } is not greater than or equal to ${numberArg}`
         );
       }
     });
@@ -454,9 +513,12 @@ export class Assertion {
 
   public toBeLessThanOrEqual(numberArg: number) {
     return this.runCheck(() => {
-      if (this.getObjectToTestReference() >= numberArg) {
+      if (this.getObjectToTestReference() > numberArg) {
         throw new Error(
-          `${this.baseReference} with drill down ${this.propertyDrillDown} is not less than or equal to ${numberArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } is not less than or equal to ${numberArg}`
         );
       }
     });
@@ -464,10 +526,14 @@ export class Assertion {
 
   public toMatchObject(objectArg: object) {
     return this.runCheck(() => {
-      const partialMatch = plugins.fastDeepEqual(this.getObjectToTestReference(), objectArg); // Note: Implement a deep comparison function or use one from a library
-      if (!partialMatch) {
+      // Implement a partial object match if needed.
+      const matchResult = plugins.fastDeepEqual(this.getObjectToTestReference(), objectArg);
+      if (!matchResult) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not match the object ${objectArg}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not match the object ${JSON.stringify(objectArg)}`
         );
       }
     });
@@ -476,10 +542,18 @@ export class Assertion {
   public toContainEqual(value: any) {
     return this.runCheck(() => {
       const arr = this.getObjectToTestReference();
-      const found = arr.some((item: any) => plugins.fastDeepEqual(item, value)); // Assuming fastDeepEqual checks deep equality
+      if (!Array.isArray(arr)) {
+        throw new Error(
+          this.failMessage || `Expected ${this.baseReference} to be an array but it is not.`
+        );
+      }
+      const found = arr.some((item: any) => plugins.fastDeepEqual(item, value));
       if (!found) {
         throw new Error(
-          `${this.baseReference} with drill down ${this.propertyDrillDown} does not contain the value ${value}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not contain the value ${JSON.stringify(value)}`
         );
       }
     });
@@ -489,7 +563,8 @@ export class Assertion {
     return this.runCheck(() => {
       if (!Array.isArray(this.getObjectToTestReference())) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not an array`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not an array`
         );
       }
     });
@@ -497,9 +572,13 @@ export class Assertion {
 
   public toInclude(substring: string) {
     return this.runCheck(() => {
-      if (!this.getObjectToTestReference().includes(substring)) {
+      const testRef = this.getObjectToTestReference();
+      if (typeof testRef !== 'string' || !testRef.includes(substring)) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not include the substring ${substring}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not include the substring ${substring}`
         );
       }
     });
@@ -510,7 +589,10 @@ export class Assertion {
       const obj = this.getObjectToTestReference();
       if (typeof obj.length !== 'number' || obj.length <= length) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not have a length greater than ${length}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not have a length greater than ${length}`
         );
       }
     });
@@ -521,7 +603,10 @@ export class Assertion {
       const obj = this.getObjectToTestReference();
       if (typeof obj.length !== 'number' || obj.length >= length) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} does not have a length less than ${length}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${
+              this.propertyDrillDown
+            } does not have a length less than ${length}`
         );
       }
     });
@@ -529,9 +614,11 @@ export class Assertion {
 
   public toBeDate() {
     return this.runCheck(() => {
-      if (!(this.getObjectToTestReference() instanceof Date)) {
+      const testRef = this.getObjectToTestReference();
+      if (!(testRef instanceof Date)) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not a date`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not a date`
         );
       }
     });
@@ -539,9 +626,11 @@ export class Assertion {
 
   public toBeBeforeDate(date: Date) {
     return this.runCheck(() => {
-      if (!(this.getObjectToTestReference() < date)) {
+      const testRef = this.getObjectToTestReference();
+      if (!(testRef instanceof Date) || testRef >= date) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not before ${date}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not before ${date}`
         );
       }
     });
@@ -549,15 +638,20 @@ export class Assertion {
 
   public toBeAfterDate(date: Date) {
     return this.runCheck(() => {
-      if (!(this.getObjectToTestReference() > date)) {
+      const testRef = this.getObjectToTestReference();
+      if (!(testRef instanceof Date) || testRef <= date) {
         throw new Error(
-          this.failMessage || `${this.baseReference} with drill down ${this.propertyDrillDown} is not after ${date}`
+          this.failMessage ||
+            `${this.baseReference} with drill down ${this.propertyDrillDown} is not after ${date}`
         );
       }
     });
   }
 
-  public customAssertion(assertionFunction: (value: any) => boolean, errorMessage: string) {
+  public customAssertion(
+    assertionFunction: (value: any) => boolean,
+    errorMessage: string
+  ) {
     return this.runCheck(() => {
       if (!assertionFunction(this.getObjectToTestReference())) {
         throw new Error(this.failMessage || errorMessage);
@@ -565,8 +659,20 @@ export class Assertion {
     });
   }
 
+  /**
+   * Drill into a property
+   */
   public property(propertyNameArg: string) {
     this.propertyDrillDown.push(propertyNameArg);
     return this;
   }
+
+  /**
+   * Drill into an array index
+   */
+  public arrayItem(indexArg: number) {
+    // Save the number (instead of "[index]")
+    this.propertyDrillDown.push(indexArg);
+    return this;
+  }
 }