xunit.ts 0.12.0 → 1.0.1

package/src/Assertions/Defined.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function Defined(value: any, message?: string) {
-    if(value !== undefined) {
+/**
+ * Asserts that a value is defined (any value other than `undefined`)
+ * 
+ * @remarks
+ * Passes if `expression` does not evaluate to `undefined`
+ * 
+ * Fails if `expression` evaluates to `undefined`
+ *
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.defined(expression);
+ */
+export default function Defined(expression: any, message?: string) {
+    if(expression !== undefined) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be defined, but expression is undefined',
         expected: '(not undefined expression)',
-        actual: value
+        actual: expression
     });
 }

package/src/Assertions/DoesNotContain.ts

@@ -0,0 +1,28 @@
+import { AssertionError } from "assert";
+
+/**
+ * Asserts that an array does not contain a given element
+ * 
+ * @remarks
+ * Passes if array `haystack` does not contain an element with a value of `needle`
+ * 
+ * Fails if array `haystack` contains an element with a value of `needle`
+ *
+ * @param needle the element to find
+ * @param haystack the array to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.doesNotContain(needle, haystack);
+ */
+export default function DoesNotContain<T>(needle: T, haystack: ReadonlyArray<T>, message?: string) {
+    if(!haystack.includes(needle)) {
+        return;
+    }
+
+    throw new AssertionError({
+        message: message || 'Expected array not containing expression, but array contained expression',
+        expected: needle,
+        actual: haystack
+    });
+}

package/src/Assertions/DoesNotThrow.ts

@@ -1,8 +1,23 @@
 import { AssertionError } from "assert";
 
+/**
+ * Asserts that an expression does not throw an error/exception
+ * 
+ * @remarks
+ * Passes if calling `expression` does not throw an error/exception
+ * 
+ * Fails if calling `expression` throws an error/exception
+ *
+ * @param expression the expression to run
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.doesNotThrow(() => expression);
+ */
 export default function DoesNotThrow(expression: () => any, message?: string) {
     try {
         expression();
+        return;
     } catch (exception) {
         throw new AssertionError({
             message: message || 'Expected expression to not throw exception, but expression did throw exception',

package/src/Assertions/Empty.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function Empty(value: any, message?: string) {
-    if(value.length === 0) {
+/**
+ * Asserts that an array is empty
+ * 
+ * @remarks
+ * Passes if `array` contains zero elements
+ * 
+ * Fails if `array` contains any elements
+ *
+ * @param array the array to check
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.empty(array);
+ */
+export default function Empty(array: ReadonlyArray<any>, message?: string) {
+    if(array.length === 0) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be empty, but expression was not empty',
         expected: [],
-        actual: value
+        actual: array
     })
 }

package/src/Assertions/Equal.ts

@@ -1,6 +1,21 @@
 import { AssertionError } from "assert";
 import equal from 'lodash.isequal';
 
+/**
+ * Asserts that two values are equal
+ * 
+ * @remarks
+ * Passes if `actual` and `expected` evaluate to equal values
+ * 
+ * Fails if `actual` and `expected` do not evaluate to equal values
+ * 
+ * @param expected the expected value
+ * @param actual the actual value
+ * @param message (optional) message to display on failure
+ *
+ * @example
+ * this.assert.equal(expected, actual);
+ */
 export default function Equal(expected: any, actual: any, message?: string) {
     if(equal(actual, expected)) {
         return;

package/src/Assertions/False.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function False(value: any, message?: string) {
-    if(value === false) {
+/**
+ * Asserts that a given value is equal to `false`
+ * 
+ * @remarks
+ * Passes if `expression` evaluates to `false`
+ * 
+ * Fails if `expression` does not evaluate to `false`
+ * 
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ *
+ * @example
+ * this.assert.false(expression);
+ */
+export default function False(expression: any, message?: string) {
+    if(expression === false) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be false, but expression is not false',
         expected: false,
-        actual: value
+        actual: expression
     });
 }

package/src/Assertions/InstanceOf.ts

@@ -1,13 +1,28 @@
 import { AssertionError } from "assert";
 
-export default function InstanceOf<T>(type: any, value: any, message?: string) {
-    if (value instanceof type) {
+/**
+ * Asserts that a value is an instance of a certain type
+ * 
+ * @remarks
+ * Passes if `object`'s type matches `type`
+ * 
+ * Fails if `object`'s type does not match `type` 
+ *
+ * @param type the expected type of the value
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.instanceOf(type, object);
+ */
+export default function InstanceOf<T>(type: any, expression: any, message?: string) {
+    if (expression instanceof type) {
         return;
     }
 
     throw new AssertionError({
-        message: message || `Expected expression of type, but was ${typeof value}`,
+        message: message || `Expected expression of type, but was ${typeof expression}`,
         expected: type,
-        actual: typeof value
+        actual: typeof expression
     })
 }

package/src/Assertions/NotEmpty.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function NotEmpty(value: any, message?: string) {
-    if(value.length > 0) {
+/**
+ * Asserts that an array is not empty
+ * 
+ * @remarks
+ * Passes if `array` contains any elements
+ * 
+ * Fails if `array` contains zero elements
+ *
+ * @param array the array to check
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.notEmpty(array);
+ */
+export default function NotEmpty(array: ReadonlyArray<any>, message?: string) {
+    if(array.length > 0) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be not empty, but expression was empty',
         expected: '(non-empty expression)',
-        actual: value
+        actual: array
     })
 }

package/src/Assertions/NotEqual.ts

@@ -1,7 +1,23 @@
 import { AssertionError } from "assert";
+import equal from 'lodash.isequal';
 
+/**
+ * Asserts that two values are not equal
+ * 
+ * @remarks
+ * Passes if `actual` and `expected` do not evaluate to equal values
+ * 
+ * Fails if `actual` and `expected` evaluate to equal values
+ * 
+ * @param expected the expected value
+ * @param actual the actual value
+ * @param message (optional) message to display on failure
+ *
+ * @example
+ * this.assert.notEqual(expected, actual);
+ */
 export default function NotEqual(expected: any, actual: any, message?: string) {
-    if(actual !== expected) {
+    if(!equal(actual, expected)) {
         return;
     }
 

package/src/Assertions/NotNull.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function NotNull(value: any, message?: string) {
-    if(value !== null) {
+/**
+ * Asserts that a value is not `null`
+ * 
+ * @remarks
+ * Passes if `expression` does not evaluate to `null`
+ * 
+ * Fails if `expression` evaluates to `null`
+ * 
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ *
+ * @example
+ * this.assert.notNull(expression);
+ */
+export default function NotNull(expression: any, message?: string) {
+    if(expression !== null) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be not null, but expression is null',
         expected: '(non-null expression)',
-        actual: value
+        actual: expression
     });
 }

package/src/Assertions/Null.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function Null(value: any, message?: string) {
-    if(value === null) {
+/**
+ * Asserts that a value is `null`
+ * 
+ * @remarks
+ * Passes if `expression` evaluates to `null`
+ * 
+ * Fails if `expression` does not evaluate to `null`
+ * 
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ *
+ * @example
+ * this.assert.null(expression);
+ */
+export default function Null(expression: any, message?: string) {
+    if(expression === null) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be null, but expression is not null',
         expected: null,
-        actual: value
+        actual: expression
     });
 }

package/src/Assertions/StringContains.ts

@@ -1,7 +1,22 @@
 import { AssertionError } from "assert";
 
-export default function StringContains(needle: string, haystack: string|null, message?: string) {
-    if(haystack !== undefined && haystack !== null && haystack.indexOf(needle) !== -1) {
+/**
+ * Asserts that a string contains a given substring
+ * 
+ * @remarks
+ * Passes if `needle` is a substring of `haystack`
+ * 
+ * Fails if `needle` is not a substring of `haystack`
+ *
+ * @param needle the substring to find
+ * @param haystack the string to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.stringContains(needle, haystack);
+ */
+export default function StringContains(needle: string, haystack: string | null, message?: string) {
+    if (haystack !== undefined && haystack !== null && haystack.indexOf(needle) > -1) {
         return;
     }
 

package/src/Assertions/StringDoesNotContain.ts

@@ -0,0 +1,28 @@
+import { AssertionError } from "assert";
+
+/**
+ * Asserts that a string does not contain a given substring
+ * 
+ * @remarks
+ * Passes if `needle` is not a substring of `haystack`
+ * 
+ * Fails if `needle` is a substring of `haystack`
+ *
+ * @param needle the substring to find
+ * @param haystack the string to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.stringDoesNotContain(needle, haystack);
+ */
+export default function StringDoesNotContain(needle: string, haystack: string|null, message?: string) {
+    if(haystack === undefined || haystack === null || haystack.indexOf(needle) === -1) {
+        return;
+    }
+
+    throw new AssertionError({
+        message: message || 'Expected string not containing expression, but string did contain expression',
+        expected: needle,
+        actual: haystack
+    });
+}

package/src/Assertions/StringDoesNotEndWith.ts

@@ -0,0 +1,30 @@
+import { AssertionError } from "assert";
+
+/**
+ * Asserts that a string does not end with a given substring
+ * 
+ * @remarks
+ * Passes if the final characters of `haystack` do not match `needle`
+ * 
+ * Fails if the final characters of `haystack` match `needle`
+ *
+ * @param needle the substring to find
+ * @param haystack the string to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.stringDoesNotEndWith(needle, haystack);
+ */
+export default function StringDoesNotEndWith(needle: string, haystack: string | null, message?: string) {
+    if (haystack === undefined || haystack === null
+        || haystack.indexOf(needle) === -1
+        || haystack.indexOf(needle) !== haystack.length - needle.length) {
+        return;
+    }
+
+    throw new AssertionError({
+        message: message || 'Expected string containing expression, but string did not contain expression',
+        expected: needle,
+        actual: haystack
+    });
+}

package/src/Assertions/StringDoesNotStartWith.ts

@@ -0,0 +1,28 @@
+import { AssertionError } from "assert";
+
+/**
+ * Asserts that a string does not begin with a given substring
+ * 
+ * @remarks
+ * Passes if the first characters of `haystack` do not match `needle`
+ * 
+ * Fails if the first characters of `haystack` match `needle`
+ *
+ * @param needle the substring to find
+ * @param haystack the string to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.stringDoesNotStartWith(needle, haystack);
+ */
+export default function StringDoesNotStartWith(needle: string, haystack: string|null, message?: string) {
+    if(haystack === undefined || haystack === null || haystack.indexOf(needle) !== 0) {
+        return;
+    }
+
+    throw new AssertionError({
+        message: message || 'Expected string containing expression, but string did not contain expression',
+        expected: needle,
+        actual: haystack
+    });
+}

package/src/Assertions/StringEndsWith.ts

@@ -1,7 +1,24 @@
 import { AssertionError } from "assert";
 
-export default function StringEndsWith(needle: string, haystack: string|null, message?: string) {
-    if(haystack !== undefined && haystack !== null && haystack.indexOf(needle) === haystack.length - needle.length) {
+/**
+ * Asserts that a string ends with a given substring
+ * 
+ * @remarks
+ * Passes if the final characters of `haystack` match `needle`
+ * 
+ * Fails if the final characters of `haystack` do not match `needle`
+ *
+ * @param needle the substring to find
+ * @param haystack the string to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.stringEndsWith(needle, haystack);
+ */
+export default function StringEndsWith(needle: string, haystack: string | null, message?: string) {
+    if (haystack !== undefined && haystack !== null
+        && haystack.indexOf(needle) > -1
+        && haystack.indexOf(needle) === haystack.length - needle.length) {
         return;
     }
 

package/src/Assertions/StringStartsWith.ts

@@ -1,5 +1,20 @@
 import { AssertionError } from "assert";
 
+/**
+ * Asserts that a string begins with a given substring
+ * 
+ * @remarks
+ * Passes if the first characters of `haystack` match `needle`
+ * 
+ * Fails if the first characters of `haystack` do not match `needle`
+ *
+ * @param needle the substring to find
+ * @param haystack the string to search
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.stringStartsWith(needle, haystack);
+ */
 export default function StringStartsWith(needle: string, haystack: string|null, message?: string) {
     if(haystack !== undefined && haystack !== null && haystack.indexOf(needle) === 0) {
         return;

package/src/Assertions/Throws.ts

@@ -1,5 +1,19 @@
 import { AssertionError } from "assert";
 
+/**
+ * Asserts that an expression throws an error/exception
+ * 
+ * @remarks
+ * Passes if calling `expression` throws an error/exception
+ * 
+ * Fails if calling `expression` does not throw an error/exception
+ *
+ * @param expression the expression to run
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.throws(() => expression);
+ */
 export default function Throws(expression: () => any, message?: string) {
     try {
         expression();

package/src/Assertions/True.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function True(value: any, message?: string) {
-    if(value === true) {
+/**
+ * Asserts that a given expression evaluates to `true`
+ * 
+ * @remarks
+ * Passes if `expression` evaluates to `true`
+ * 
+ * Fails if `expression` does not evaluate to `true`
+ * 
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ *
+ * @example
+ * this.assert.true(expression);
+ */
+export default function True(expression: any, message?: string) {
+    if(expression === true) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be true, but expression is not true',
         expected: true,
-        actual: value
+        actual: expression
     });
 }

package/src/Assertions/Undefined.ts

@@ -1,13 +1,27 @@
 import { AssertionError } from "assert";
 
-export default function Undefined(value: any, message?: string) {
-    if(value === undefined) {
+/**
+ * Asserts that a given value is equal to `undefined`
+ * 
+ * @remarks
+ * Passes if `expression` evaluates to `undefined`
+ * 
+ * Fails if `expression` does not evaluate to `undefined`
+ * 
+ * @param expression the value to check
+ * @param message (optional) message to display on failure
+ * 
+ * @example
+ * this.assert.undefined(expression);
+ */
+export default function Undefined(expression: any, message?: string) {
+    if(expression === undefined) {
         return;
     }
 
     throw new AssertionError({
         message: message || 'Expected expression to be undefined, but expression is not undefined',
         expected: undefined,
-        actual: value
+        actual: expression
     });
 }

package/src/Assertions/index.ts

@@ -16,16 +16,16 @@ import not_empty from './NotEmpty';
 import count from './Count';
 
 import contains from './Contains';
-import not_contains from './NotContains';
+import not_contains from './DoesNotContain';
 
 import string_contains from './StringContains';
-import string_not_contains from './StringNotContains';
+import string_not_contains from './StringDoesNotContain';
 
 import string_starts from './StringStartsWith';
-import string_not_starts from './StringNotStartsWith';
+import string_not_starts from './StringDoesNotStartWith';
 
 import string_ends from './StringEndsWith';
-import string_not_ends from './StringNotEndsWith';
+import string_not_ends from './StringDoesNotEndWith';
 
 import instance_of from './InstanceOf';
 

package/src/CLI.ts

@@ -2,7 +2,6 @@ import Usage from 'command-line-usage';
 import JUnitReporter from './Reporters/JUnitReporter';
 import Process from "process";
 import Args from "command-line-args";
-import Factory from "./Factory";
 import Runner from "./Runners/Runner";
 import SonarReporter from "./Reporters/SonarReporter";
 
@@ -72,7 +71,7 @@ export default class CLI {
 
     private static readonly usage = Usage(CLI.sections);
 
-    constructor(private readonly process: typeof Process) {
+    constructor(private readonly runnerFactory: (args: Args.CommandLineOptions) => Runner, private readonly process: typeof Process) {
     }
 
     async run(): Promise<boolean> {
@@ -84,14 +83,16 @@ export default class CLI {
             return true;
         }
 
-        const runner = Factory.Runner(args);
+        const runner = this.runnerFactory(args);
 
         try {
             const results = await runner.runAll(args.dir);
             return Runner.allTestsPassed(results);
         } catch (error) {
-            this.process.stderr.write(`An unhandled ${error.name} occurred: ${error.message}\n`);
-            this.process.stderr.write(error.stack?.toString() || '(no call stack)\n');
+            if (error instanceof Error) {
+                this.process.stderr.write(`An unhandled ${error.name} occurred: ${error.message}\n`);
+                this.process.stderr.write(error.stack?.toString() || '(no call stack)\n');
+            }
             return false;
         }
     }

package/src/Factory.ts

@@ -12,22 +12,22 @@ import fs from "fs/promises";
 import SonarReporter from "./Reporters/SonarReporter";
 
 export default class Factory {
-    private static readonly file_system = new FileSystem(fs);
+    static readonly file_system = new FileSystem(fs);
 
     static Runner(args: Args.CommandLineOptions) {
-        const loader = new TestSuiteLoader(this.file_system);
-        const reporters = this.Reporters(args);
+        const loader = new TestSuiteLoader(Factory.file_system);
+        const reporters = Factory.Reporters(args);
         const test_runner = new TestRunner(reporters);
         const test_suite_runner = new TestSuiteRunner(test_runner, reporters);
 
         return new Runner(loader, test_suite_runner, reporters);
     }
 
-    static Reporters(args: Args.CommandLineOptions): ResultReporter[] {
+    static Reporters(args: Args.CommandLineOptions): ReadonlyArray<ResultReporter> {
         return [
             !args.quiet ? new ConsoleReporter(new Output(process.stdout)) : null,
-            args.junit !== undefined ? new JUnitReporter(this.file_system, args.junit ?? JUnitReporter.defaultFileName) : null,
-            args.sonar !== undefined ? new SonarReporter(this.file_system, args.sonar ?? SonarReporter.defaultFileName) : null
+            args.junit !== undefined ? new JUnitReporter(Factory.file_system, args.junit ?? JUnitReporter.defaultFileName) : null,
+            args.sonar !== undefined ? new SonarReporter(Factory.file_system, args.sonar ?? SonarReporter.defaultFileName) : null
         ].filter(r => r !== null) as ResultReporter[];
     }
 }