summaryrefslogtreecommitdiffstats
path: root/testing/modules/Assert.sys.mjs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
commit6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch)
treea68f146d7fa01f0134297619fbe7e33db084e0aa /testing/modules/Assert.sys.mjs
parentInitial commit. (diff)
downloadthunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.tar.xz
thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.zip
Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'testing/modules/Assert.sys.mjs')
-rw-r--r--testing/modules/Assert.sys.mjs695
1 files changed, 695 insertions, 0 deletions
diff --git a/testing/modules/Assert.sys.mjs b/testing/modules/Assert.sys.mjs
new file mode 100644
index 0000000000..bd1393e674
--- /dev/null
+++ b/testing/modules/Assert.sys.mjs
@@ -0,0 +1,695 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// Originally from narwhal.js (http://narwhaljs.org)
+// Copyright (c) 2009 Thomas Robinson <280north.com>
+// MIT license: http://opensource.org/licenses/MIT
+
+const { ObjectUtils } = ChromeUtils.import(
+ "resource://gre/modules/ObjectUtils.jsm"
+);
+
+/**
+ * This module is based on the
+ * `CommonJS spec <https://wiki.commonjs.org/wiki/Unit_Testing/1.0>`_
+ *
+ * When you see a jsdoc comment that contains a number, it's a reference to a
+ * specific section of the CommonJS spec.
+ *
+ * 1. The assert module provides functions that throw AssertionError's when
+ * particular conditions are not met.
+ *
+ * To use the module you may instantiate it first.
+ *
+ * @param {reporterFunc} reporterFunc
+ * Allows consumers to override reporting for this instance.
+ * @param {boolean} isDefault
+ * Used by test suites to set ``reporterFunc`` as the default
+ * used by the global instance, which is called for example
+ * by other test-only modules. This is false when the
+ * reporter is set by content scripts, because they may still
+ * run in the parent process.
+ *
+ * @class
+ */
+export function Assert(reporterFunc, isDefault) {
+ if (reporterFunc) {
+ this.setReporter(reporterFunc);
+ }
+ if (isDefault) {
+ Assert.setReporter(reporterFunc);
+ }
+}
+
+// This allows using the Assert object as an additional global instance.
+Object.setPrototypeOf(Assert, Assert.prototype);
+
+function instanceOf(object, type) {
+ return Object.prototype.toString.call(object) == "[object " + type + "]";
+}
+
+function replacer(key, value) {
+ if (value === undefined) {
+ return "" + value;
+ }
+ if (typeof value === "number" && (isNaN(value) || !isFinite(value))) {
+ return value.toString();
+ }
+ if (typeof value === "function" || instanceOf(value, "RegExp")) {
+ return value.toString();
+ }
+ return value;
+}
+
+const kTruncateLength = 128;
+
+function truncate(text, newLength = kTruncateLength) {
+ if (typeof text == "string") {
+ return text.length < newLength ? text : text.slice(0, newLength);
+ }
+ return text;
+}
+
+function getMessage(error, prefix = "") {
+ let actual, expected;
+ // Wrap calls to JSON.stringify in try...catch blocks, as they may throw. If
+ // so, fall back to toString().
+ try {
+ actual = JSON.stringify(error.actual, replacer);
+ } catch (ex) {
+ actual = Object.prototype.toString.call(error.actual);
+ }
+ try {
+ expected = JSON.stringify(error.expected, replacer);
+ } catch (ex) {
+ expected = Object.prototype.toString.call(error.expected);
+ }
+ let message = prefix;
+ if (error.operator) {
+ let truncateLength = error.truncate ? kTruncateLength : Infinity;
+ message +=
+ (prefix ? " - " : "") +
+ truncate(actual, truncateLength) +
+ " " +
+ error.operator +
+ " " +
+ truncate(expected, truncateLength);
+ }
+ return message;
+}
+
+/**
+ * 2. The AssertionError is defined in assert.
+ *
+ * At present only the four keys mentioned below are used and
+ * understood by the spec. Implementations or sub modules can pass
+ * other keys to the AssertionError's constructor - they will be
+ * ignored.
+ *
+ * @example
+ *
+ * new assert.AssertionError({
+ * message: message,
+ * actual: actual,
+ * expected: expected,
+ * operator: operator,
+ * truncate: truncate
+ * });
+ *
+ */
+Assert.AssertionError = function (options) {
+ this.name = "AssertionError";
+ this.actual = options.actual;
+ this.expected = options.expected;
+ this.operator = options.operator;
+ this.message = getMessage(this, options.message, options.truncate);
+ // The part of the stack that comes from this module is not interesting.
+ let stack = Components.stack;
+ do {
+ stack = stack.asyncCaller || stack.caller;
+ } while (
+ stack &&
+ stack.filename &&
+ stack.filename.includes("Assert.sys.mjs")
+ );
+ this.stack = stack;
+};
+
+// assert.AssertionError instanceof Error
+Assert.AssertionError.prototype = Object.create(Error.prototype, {
+ constructor: {
+ value: Assert.AssertionError,
+ enumerable: false,
+ writable: true,
+ configurable: true,
+ },
+});
+
+Assert.prototype._reporter = null;
+
+/**
+ * This callback type is used for custom assertion report handling.
+ *
+ * @callback reporterFunc
+ * @param {AssertionError|null} err
+ * An error object when the assertion failed, or null when it passed.
+ * @param {String} message
+ * Message describing the assertion.
+ * @param {Stack} stack
+ * Stack trace of the assertion function.
+ */
+
+/**
+ * Set a custom assertion report handler function.
+ *
+ * @example
+ *
+ * Assert.setReporter(function customReporter(err, message, stack) {
+ * if (err) {
+ * do_report_result(false, err.message, err.stack);
+ * } else {
+ * do_report_result(true, message, stack);
+ * }
+ * });
+ *
+ * @param {reporterFunc} reporterFunc
+ * Report handler function.
+ */
+Assert.prototype.setReporter = function (reporterFunc) {
+ this._reporter = reporterFunc;
+};
+
+/**
+ * 3. All of the following functions must throw an AssertionError when a
+ * corresponding condition is not met, with a message that may be undefined if
+ * not provided. All assertion methods provide both the actual and expected
+ * values to the assertion error for display purposes.
+ *
+ * This report method only throws errors on assertion failures, as per spec,
+ * but consumers of this module (think: xpcshell-test, mochitest) may want to
+ * override this default implementation.
+ *
+ * @example
+ *
+ * // The following will report an assertion failure.
+ * this.report(1 != 2, 1, 2, "testing JS number math!", "==");
+ *
+ * @param {boolean} failed
+ * Indicates if the assertion failed or not.
+ * @param {*} actual
+ * The result of evaluating the assertion.
+ * @param {*} [expected]
+ * Expected result from the test author.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ * @param {String} [operator]
+ * Operation qualifier used by the assertion method (ex: '==').
+ * @param {boolean} [truncate=true]
+ * Whether or not ``actual`` and ``expected`` should be truncated when printing.
+ */
+Assert.prototype.report = function (
+ failed,
+ actual,
+ expected,
+ message,
+ operator,
+ truncate = true
+) {
+ // Although not ideal, we allow a "null" message due to the way some of the extension tests
+ // work.
+ if (message !== undefined && message !== null && typeof message != "string") {
+ this.ok(
+ false,
+ `Expected a string or undefined for the error message to Assert.*, got ${typeof message}`
+ );
+ }
+ let err = new Assert.AssertionError({
+ message,
+ actual,
+ expected,
+ operator,
+ truncate,
+ });
+ if (!this._reporter) {
+ // If no custom reporter is set, throw the error.
+ if (failed) {
+ throw err;
+ }
+ } else {
+ this._reporter(failed ? err : null, err.message, err.stack);
+ }
+};
+
+/**
+ * 4. Pure assertion tests whether a value is truthy, as determined by !!guard.
+ * ``assert.ok(guard, message_opt);``
+ * This statement is equivalent to ``assert.equal(true, !!guard, message_opt);``.
+ * To test strictly for the value true, use ``assert.strictEqual(true, guard,
+ * message_opt);``.
+ *
+ * @param {*} value
+ * Test subject to be evaluated as truthy.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.ok = function (value, message) {
+ if (arguments.length > 2) {
+ this.report(
+ true,
+ false,
+ true,
+ "Too many arguments passed to `Assert.ok()`",
+ "=="
+ );
+ } else {
+ this.report(!value, value, true, message, "==");
+ }
+};
+
+/**
+ * 5. The equality assertion tests shallow, coercive equality with ==.
+ * ``assert.equal(actual, expected, message_opt);``
+ *
+ * @param {*} actual
+ * Test subject to be evaluated as equivalent to ``expected``.
+ * @param {*} expected
+ * Test reference to evaluate against ``actual``.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.equal = function equal(actual, expected, message) {
+ this.report(actual != expected, actual, expected, message, "==");
+};
+
+/**
+ * 6. The non-equality assertion tests for whether two objects are not equal
+ * with ``!=``
+ *
+ * @example
+ * assert.notEqual(actual, expected, message_opt);
+ *
+ * @param {*} actual
+ * Test subject to be evaluated as NOT equivalent to ``expected``.
+ * @param {*} expected
+ * Test reference to evaluate against ``actual``.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.notEqual = function notEqual(actual, expected, message) {
+ this.report(actual == expected, actual, expected, message, "!=");
+};
+
+/**
+ * 7. The equivalence assertion tests a deep equality relation.
+ * assert.deepEqual(actual, expected, message_opt);
+ *
+ * We check using the most exact approximation of equality between two objects
+ * to keep the chance of false positives to a minimum.
+ * `JSON.stringify` is not designed to be used for this purpose; objects may
+ * have ambiguous `toJSON()` implementations that would influence the test.
+ *
+ * @param {*} actual
+ * Test subject to be evaluated as equivalent to ``expected``, including nested properties.
+ * @param {*} expected
+ * Test reference to evaluate against ``actual``.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.deepEqual = function deepEqual(actual, expected, message) {
+ this.report(
+ !ObjectUtils.deepEqual(actual, expected),
+ actual,
+ expected,
+ message,
+ "deepEqual",
+ false
+ );
+};
+
+/**
+ * 8. The non-equivalence assertion tests for any deep inequality.
+ * assert.notDeepEqual(actual, expected, message_opt);
+ *
+ * @param {*} actual
+ * Test subject to be evaluated as NOT equivalent to ``expected``, including nested
+ * properties.
+ * @param {*} expected
+ * Test reference to evaluate against ``actual``.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.notDeepEqual = function notDeepEqual(
+ actual,
+ expected,
+ message
+) {
+ this.report(
+ ObjectUtils.deepEqual(actual, expected),
+ actual,
+ expected,
+ message,
+ "notDeepEqual",
+ false
+ );
+};
+
+/**
+ * 9. The strict equality assertion tests strict equality, as determined by ===.
+ * ``assert.strictEqual(actual, expected, message_opt);``
+ *
+ * @param {*} actual
+ * Test subject to be evaluated as strictly equivalent to ``expected``.
+ * @param {*} expected
+ * Test reference to evaluate against ``actual``.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.strictEqual = function strictEqual(actual, expected, message) {
+ this.report(actual !== expected, actual, expected, message, "===");
+};
+
+/**
+ * 10. The strict non-equality assertion tests for strict inequality, as
+ * determined by !==. ``assert.notStrictEqual(actual, expected, message_opt);``
+ *
+ * @param {*} actual
+ * Test subject to be evaluated as NOT strictly equivalent to ``expected``.
+ * @param {*} expected
+ * Test reference to evaluate against ``actual``.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.notStrictEqual = function notStrictEqual(
+ actual,
+ expected,
+ message
+) {
+ this.report(actual === expected, actual, expected, message, "!==");
+};
+
+function checkExpectedArgument(instance, funcName, expected) {
+ if (!expected) {
+ instance.ok(
+ false,
+ `Error: The 'expected' argument was not supplied to Assert.${funcName}()`
+ );
+ }
+
+ if (
+ !instanceOf(expected, "RegExp") &&
+ typeof expected !== "function" &&
+ typeof expected !== "object"
+ ) {
+ instance.ok(
+ false,
+ `Error: The 'expected' argument to Assert.${funcName}() must be a RegExp, function or an object`
+ );
+ }
+}
+
+function expectedException(actual, expected) {
+ if (!actual || !expected) {
+ return false;
+ }
+
+ if (instanceOf(expected, "RegExp")) {
+ return expected.test(actual);
+ // We need to guard against the right hand parameter of "instanceof" lacking
+ // the "prototype" property, which is true of arrow functions in particular.
+ } else if (
+ !(typeof expected === "function" && !expected.prototype) &&
+ actual instanceof expected
+ ) {
+ return true;
+ } else if (expected.call({}, actual) === true) {
+ return true;
+ }
+
+ return false;
+}
+
+/**
+ * 11. Expected to throw an error:
+ * assert.throws(block, Error_opt, message_opt);
+ *
+ * Example:
+ * ```js
+ * // The following will verify that an error of type TypeError was thrown:
+ * Assert.throws(() => testBody(), TypeError);
+ * // The following will verify that an error was thrown with an error message matching "hello":
+ * Assert.throws(() => testBody(), /hello/);
+ * ```
+ *
+ * @param {Function} block
+ * Function to evaluate and catch eventual thrown errors.
+ * @param {RegExp|Function} expected
+ * This parameter can be either a RegExp or a function. The function is
+ * either the error type's constructor, or it's a method that returns
+ * a boolean that describes the test outcome.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.throws = function (block, expected, message) {
+ checkExpectedArgument(this, "throws", expected);
+
+ // `true` if we realize that we have added an
+ // error to `ChromeUtils.recentJSDevError` and
+ // that we probably need to clean it up.
+ let cleanupRecentJSDevError = false;
+ if ("recentJSDevError" in ChromeUtils) {
+ // Check that we're in a build of Firefox that supports
+ // the `recentJSDevError` mechanism (i.e. Nightly build).
+ if (ChromeUtils.recentJSDevError === undefined) {
+ // There was no previous error, so if we throw
+ // an error here, we may need to clean it up.
+ cleanupRecentJSDevError = true;
+ }
+ }
+
+ let actual;
+
+ try {
+ block();
+ } catch (e) {
+ actual = e;
+ }
+
+ message =
+ (expected.name ? " (" + expected.name + ")." : ".") +
+ (message ? " " + message : ".");
+
+ if (!actual) {
+ this.report(true, actual, expected, "Missing expected exception" + message);
+ }
+
+ if (actual && !expectedException(actual, expected)) {
+ throw actual;
+ }
+
+ this.report(false, expected, expected, message);
+
+ // Make sure that we don't cause failures for JS Dev Errors that
+ // were expected, typically for tests that attempt to check
+ // that we react properly to TypeError, ReferenceError, SyntaxError.
+ if (cleanupRecentJSDevError) {
+ let recentJSDevError = ChromeUtils.recentJSDevError;
+ if (recentJSDevError) {
+ if (expectedException(recentJSDevError)) {
+ ChromeUtils.clearRecentJSDevError();
+ }
+ }
+ }
+};
+
+/**
+ * A promise that is expected to reject:
+ * assert.rejects(promise, expected, message);
+ *
+ * @param {Promise} promise
+ * A promise that is expected to reject.
+ * @param {?} [expected]
+ * Test reference to evaluate against the rejection result.
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.rejects = function (promise, expected, message) {
+ checkExpectedArgument(this, "rejects", expected);
+ return new Promise((resolve, reject) => {
+ return promise
+ .then(
+ () =>
+ this.report(
+ true,
+ null,
+ expected,
+ "Missing expected exception " + message
+ ),
+ err => {
+ if (!expectedException(err, expected)) {
+ reject(err);
+ return;
+ }
+ this.report(false, err, expected, message);
+ resolve();
+ }
+ )
+ .catch(reject);
+ });
+};
+
+function compareNumbers(expression, lhs, rhs, message, operator) {
+ let lhsIsNumber = typeof lhs == "number" && !Number.isNaN(lhs);
+ let rhsIsNumber = typeof rhs == "number" && !Number.isNaN(rhs);
+
+ if (lhsIsNumber && rhsIsNumber) {
+ this.report(expression, lhs, rhs, message, operator);
+ return;
+ }
+
+ let errorMessage;
+ if (!lhsIsNumber && !rhsIsNumber) {
+ errorMessage = "Neither '" + lhs + "' nor '" + rhs + "' are numbers";
+ } else {
+ errorMessage = "'" + (lhsIsNumber ? rhs : lhs) + "' is not a number";
+ }
+ this.report(true, lhs, rhs, errorMessage);
+}
+
+/**
+ * The lhs must be greater than the rhs.
+ * assert.greater(lhs, rhs, message_opt);
+ *
+ * @param {Number} lhs
+ * The left-hand side value.
+ * @param {Number} rhs
+ * The right-hand side value.
+ * @param {String} [message]
+ * Short explanation of the comparison result.
+ */
+Assert.prototype.greater = function greater(lhs, rhs, message) {
+ compareNumbers.call(this, lhs <= rhs, lhs, rhs, message, ">");
+};
+
+/**
+ * The lhs must be greater than or equal to the rhs.
+ * assert.greaterOrEqual(lhs, rhs, message_opt);
+ *
+ * @param {Number} [lhs]
+ * The left-hand side value.
+ * @param {Number} [rhs]
+ * The right-hand side value.
+ * @param {String} [message]
+ * Short explanation of the comparison result.
+ */
+Assert.prototype.greaterOrEqual = function greaterOrEqual(lhs, rhs, message) {
+ compareNumbers.call(this, lhs < rhs, lhs, rhs, message, ">=");
+};
+
+/**
+ * The lhs must be less than the rhs.
+ * assert.less(lhs, rhs, message_opt);
+ *
+ * @param {Number} [lhs]
+ * The left-hand side value.
+ * @param {Number} [rhs]
+ * The right-hand side value.
+ * @param {String} [message]
+ * Short explanation of the comparison result.
+ */
+Assert.prototype.less = function less(lhs, rhs, message) {
+ compareNumbers.call(this, lhs >= rhs, lhs, rhs, message, "<");
+};
+
+/**
+ * The lhs must be less than or equal to the rhs.
+ * assert.lessOrEqual(lhs, rhs, message_opt);
+ *
+ * @param {Number} [lhs]
+ * The left-hand side value.
+ * @param {Number} [rhs]
+ * The right-hand side value.
+ * @param {String} [message]
+ * Short explanation of the comparison result.
+ */
+Assert.prototype.lessOrEqual = function lessOrEqual(lhs, rhs, message) {
+ compareNumbers.call(this, lhs > rhs, lhs, rhs, message, "<=");
+};
+
+/**
+ * The lhs must be a string that matches the rhs regular expression.
+ * rhs can be specified either as a string or a RegExp object. If specified as a
+ * string it will be interpreted as a regular expression so take care to escape
+ * special characters such as "?" or "(" if you need the actual characters.
+ *
+ * @param {String} lhs
+ * The string to be tested.
+ * @param {String|RegExp} rhs
+ * The regular expression that the string will be tested with.
+ * Note that if passed as a string, this will be interpreted.
+ * as a regular expression.
+ * @param {String} [message]
+ * Short explanation of the comparison result.
+ */
+Assert.prototype.stringMatches = function stringMatches(lhs, rhs, message) {
+ if (typeof rhs != "string" && !instanceOf(rhs, "RegExp")) {
+ this.report(
+ true,
+ lhs,
+ String(rhs),
+ `Expected a string or a RegExp for rhs, but "${rhs}" isn't a string or a RegExp object.`
+ );
+ return;
+ }
+
+ if (typeof lhs != "string") {
+ this.report(
+ true,
+ lhs,
+ String(rhs),
+ `Expected a string for lhs, but "${lhs}" isn't a string.`
+ );
+ return;
+ }
+
+ if (typeof rhs == "string") {
+ try {
+ rhs = new RegExp(rhs);
+ } catch {
+ this.report(
+ true,
+ lhs,
+ rhs,
+ `Expected a valid regular expression for rhs, but "${rhs}" isn't one.`
+ );
+ return;
+ }
+ }
+
+ const isCorrect = rhs.test(lhs);
+ this.report(!isCorrect, lhs, rhs.toString(), message, "matches");
+};
+
+/**
+ * The lhs must be a string that contains the rhs string.
+ *
+ * @param {String} lhs
+ * The string to be tested (haystack).
+ * @param {String} rhs
+ * The string to be found (needle).
+ * @param {String} [message]
+ * Short explanation of the expected result.
+ */
+Assert.prototype.stringContains = function stringContains(lhs, rhs, message) {
+ if (typeof lhs != "string" || typeof rhs != "string") {
+ this.report(
+ true,
+ lhs,
+ rhs,
+ `Expected a string for both lhs and rhs, but either "${lhs}" or "${rhs}" is not a string.`
+ );
+ }
+
+ const isCorrect = lhs.includes(rhs);
+ this.report(!isCorrect, lhs, rhs, message, "includes");
+};