Support for testable errors codes for all user facing errors

The `error.name` property can be used to determine what caused the error. Some error messagers have also been improved and some missing tests were added

Author: Joris-van-der-Wel

core/lib/background/RunnerScriptParent.js

@@ -3,6 +3,7 @@
 const EventEmitter = require('events').EventEmitter;
 const JSONBird = require('jsonbird');
 
+const {SCRIPT_EXECUTION_TIMEOUT_ERROR} = require('../../../lib/scriptErrors');
 const log = require('../../../lib/logger')({hostname: 'background', MODULE: 'core/background/RunnerScriptParent'});
 const coreMethods = require('./coreMethods');
 const loadModule = require('./loadModule');
@@ -47,7 +48,7 @@ class RunnerScriptParent {
         return this[PRIVATE].run();
     }
 
-    async stop(reason = 'unknown') {
+    async stop(reason) {
         return this[PRIVATE].stop(reason);
     }
 
@@ -172,7 +173,10 @@ class RunnerScriptParentPrivate {
             const {runTimeoutMs, stackFileName} = this;
             this.scriptTimeoutTimer = setTimeout(() => {
                 this.scriptTimeoutTimer = 0;
-                this.stop(`Script execution timed out after ${runTimeoutMs / 1000} seconds`)
+                this.stop({
+                    name: SCRIPT_EXECUTION_TIMEOUT_ERROR,
+                    message: `Script execution timed out after ${runTimeoutMs / 1000} seconds`,
+                })
                 .catch(err => log.error({err}, 'Stopping script (after script timeout) failed'));
             }, runTimeoutMs);
 
@@ -197,7 +201,7 @@ class RunnerScriptParentPrivate {
                 await this.emitRunScriptResult(runScriptResult);
                 scriptResult.timing.endNow();
                 log.info({err: runScriptResult.scriptError}, 'Worker completed runScript command');
-                await this.stop('Normal script completion');
+                await this.stop({message: 'Normal script completion'});
             }
             finally { // only emit runEnd if runStart was emitted
                 // eslint-disable-next-line camelcase, no-undef
@@ -239,15 +243,15 @@ class RunnerScriptParentPrivate {
         }
     }
 
-    async stop(reason) {
+    async stop({name, message} = {}) {
         if (this.sentStopCommand) {
             return false;
         }
 
         this.sentStopCommand = true;
 
         await this.rpcCall('core.stopScript', {
-            reason: reason,
+            reason: {name, message},
         });
         return true;
     }

core/lib/background/scratchpadMethods.js

@@ -30,7 +30,7 @@ module.exports = ({browserTabId, browserTabs, browserDownloads, rpc, scratchpadR
             setRunState({state: 'stopping'});
 
             try {
-                await script.stop(reason);
+                await script.stop({message: reason});
             }
             finally {
                 setRunState({state: 'stopped'});

core/lib/script-env/RunnerScript.js

@@ -158,9 +158,12 @@ class RunnerScriptPrivate {
         log.info('Emitted core.runEnd...');
     }
 
-    async stop(reason) {
-        log.info({reason}, 'Stopping...');
-        this.stopPromiseReject(Error(`Script stopped: ${reason}`));
+    async stop({name = 'Error', message = ''}) {
+        log.info({name, message}, 'Stopping...');
+        const err = new Error(`Script stopped: ${message}`);
+        err.name = name;
+        this.stopReason = err;
+        this.stopPromiseReject(err);
     }
 
     compileScript(scriptContent, stackFileName) {

lib/RequestModificationPatterns.js

@@ -1,4 +1,5 @@
 'use strict';
+const {illegalArgumentError} = require('./scriptErrors');
 const log = require('./logger')({
     hostname: 'background',
     MODULE: 'RequestModificationPatterns',
@@ -18,12 +19,12 @@ class RequestModificationPatterns {
 
     add(patterns, data = null) {
         if (!Array.isArray(patterns) || !patterns.length) {
-            throw new TypeError('add(): Argument `patterns` must be an non empty array of strings');
+            throw illegalArgumentError('RequestModificationPatterns.add(): Argument `patterns` must be an non empty array of strings');
         }
 
         for (const pattern of patterns) {
             if (typeof pattern !== 'string') {
-                throw new TypeError('add(): Argument `patterns` must be an non empty array of strings');
+                throw illegalArgumentError('RequestModificationPatterns.add(): Argument `patterns` must be an non empty array of strings');
             }
         }
 

lib/domUtilities.js

@@ -1,4 +1,5 @@
 'use strict';
+const {illegalArgumentError} = require('./scriptErrors');
 const findPropertyInChain = require('./findPropertyInChain');
 
 // These constants are repeated here so that we can access them even if there is no DOM (yet)
@@ -68,7 +69,7 @@ const isNode = object => {
  */
 const assertIsNode = (object, message = '') => {
     if (!isNode(object)) {
-        throw new TypeError(`${message}Expected value to be a DOM Node`);
+        throw illegalArgumentError(`${message}Expected value to be a DOM Node`);
     }
 };
 
@@ -86,7 +87,7 @@ const assertIsNodeType = (object, nodeType, message = '') => {
     if (object.nodeType !== nodeType) {
         const names = NODE_TYPE_CONSTRUCTOR_NAME;
         const fullMessage = `${message}Expected value to be a ${names[nodeType]} Node instead of a ${names[object.nodeType]} Node`;
-        throw new TypeError(fullMessage);
+        throw illegalArgumentError(fullMessage);
     }
 };
 

lib/scriptErrors.js

@@ -0,0 +1,90 @@
+'use strict';
+
+// (all errors which are visible to the runner script made by the user under normal conditions)
+
+/**
+ * An argument passed to one of the api functions or setters is incompatible with the type expected by that function
+ */
+const ILLEGAL_ARGUMENT_ERROR = 'Openrunner:IllegalArgumentError';
+
+/**
+ * An api function has been called at an inappropriate time
+ */
+const ILLEGAL_STATE_ERROR = 'Openrunner:IllegalStateError';
+
+/**
+ * Unable to navigate to the specified URL using tab.navigate()
+ */
+const NAVIGATE_ERROR = 'Openrunner:NavigateError';
+
+/**
+ * And assertion made by the script has failed.
+ */
+const ASSERTION_ERROR = 'Openrunner:AssertionError';
+
+/**
+ * The script is waiting for a condition in the DOM (e.g. a specific DOM Element to be present) which has been
+ * aborted because it took too long.
+ */
+const DOM_WAIT_TIMEOUT_ERROR = 'BluefoxTimeoutError';
+
+/**
+ * The script is waiting for a new page to be navigated too, which has been aborted because it took too long.
+ */
+const NEW_PAGE_WAIT_TIMEOUT_ERROR = 'Openrunner:NewPageWaitTimeoutError';
+
+
+/**
+ * An active transaction has been aborted because the script is stopping.
+ */
+const TRANSACTION_ABORTED_ERROR = 'Openrunner:TransactionAbortedError';
+
+/**
+ * An active content script (e.g. `tab.run()`)has been aborted because the page is navigating away,
+ * the tab is closing, or the script is stopping.
+ */
+
+const CONTENT_SCRIPT_ABORTED_ERROR = 'Openrunner:ContentScriptAbortedError';
+
+/**
+ * The Openrunner script has been running longer than its configured timeout limit and has been aborted.
+ * For example:
+ * 'Openrunner-Script-Timeout: 10s'
+ */
+const SCRIPT_EXECUTION_TIMEOUT_ERROR = 'Openrunner:ScriptExecutionTimeoutError';
+
+const createErrorShorthand = name => (message, cause = null) => {
+    const err = new Error(message);
+    err.name = name;
+    err.cause = cause;
+    return err;
+};
+
+const translateRpcErrorName = err => {
+    const match = /RPCRequestError<(Openrunner:.*?)>/.exec(err && err.name);
+    if (match) {
+        err.name = match[1];
+    }
+    throw err;
+};
+
+module.exports = {
+    ILLEGAL_ARGUMENT_ERROR,
+    ILLEGAL_STATE_ERROR,
+    NAVIGATE_ERROR,
+    ASSERTION_ERROR,
+    DOM_WAIT_TIMEOUT_ERROR,
+    NEW_PAGE_WAIT_TIMEOUT_ERROR,
+    TRANSACTION_ABORTED_ERROR,
+    CONTENT_SCRIPT_ABORTED_ERROR,
+    SCRIPT_EXECUTION_TIMEOUT_ERROR,
+    illegalArgumentError: createErrorShorthand(ILLEGAL_ARGUMENT_ERROR),
+    illegalStateError: createErrorShorthand(ILLEGAL_STATE_ERROR),
+    navigateError: createErrorShorthand(NAVIGATE_ERROR),
+    assertionError: createErrorShorthand(ASSERTION_ERROR),
+    newPageWaitTimeoutError: createErrorShorthand(NEW_PAGE_WAIT_TIMEOUT_ERROR),
+    transactionAbortedError: createErrorShorthand(TRANSACTION_ABORTED_ERROR),
+    contentScriptAbortedError: createErrorShorthand(CONTENT_SCRIPT_ABORTED_ERROR),
+    scriptExecutionTimeoutError: createErrorShorthand(SCRIPT_EXECUTION_TIMEOUT_ERROR),
+    translateRpcErrorName,
+};

runner-modules/eventSimulation/lib/content/keyboard.js

@@ -1,4 +1,5 @@
 'use strict';
+const {illegalArgumentError} = require('../../../../lib/scriptErrors');
 const findPropertyInChain = require('../../../../lib/findPropertyInChain');
 const {getOwnerDocument, getDocumentWindow, assertIsNodeType, ELEMENT_NODE} = require('../../../../lib/domUtilities');
 const {parseKeyIdentifiers, SHIFT_KEY} = require('./keys');
@@ -115,7 +116,7 @@ const keyboardTextInput = async (element, keyIdentifiers, options = {}) => {
     const isElementContentEditable = element.isContentEditable;
 
     if (!isElementTextValueControl && !isElementContentEditable) {
-        throw new TypeError(
+        throw illegalArgumentError(
             `keyboardTextInput(): (${element.nodeName} ${element.type || ''}) is not a valid element for text input`
         );
     }

runner-modules/eventSimulation/lib/content/keys.js

@@ -1,4 +1,5 @@
 'use strict';
+const {illegalArgumentError} = require('../../../../lib/scriptErrors');
 
 const DOM_KEY_LOCATION_STANDARD = 0;
 const DOM_KEY_LOCATION_LEFT = 1;
@@ -240,7 +241,7 @@ const parseKeyIdentifiers = identifiers => {
     });
 
     if (invalidKeys.length) {
-        throw new TypeError(`Invalid Argument: The following keys are not supported: "${invalidKeys.join('", "')}"`);
+        throw illegalArgumentError(`The following keys are not supported: "${invalidKeys.join('", "')}"`);
     }
 
     return keyEntries;

runner-modules/requestBlocking/lib/script-env/index.js

@@ -1,4 +1,5 @@
 'use strict';
+const {illegalArgumentError} = require('../../../../lib/scriptErrors');
 
 const parsePatternArg = patternsArg => {
     const patterns = Array.isArray(patternsArg)
@@ -7,7 +8,7 @@ const parsePatternArg = patternsArg => {
 
     for (const value of patterns) {
         if (typeof value !== 'string') {
-            throw Error('Invalid patterns argument');
+            throw illegalArgumentError('requestBlocking: Invalid patterns argument');
         }
     }
     return patterns;

runner-modules/requestModification/lib/script-env/index.js

@@ -1,4 +1,5 @@
 'use strict';
+const {illegalArgumentError} = require('../../../../lib/scriptErrors');
 
 const parsePatternArg = patternsArg => {
     const patterns = Array.isArray(patternsArg)
@@ -7,7 +8,7 @@ const parsePatternArg = patternsArg => {
 
     for (const value of patterns) {
         if (typeof value !== 'string') {
-            throw Error('Invalid patterns argument');
+            throw illegalArgumentError('requestModification: Invalid patterns argument');
         }
     }
     return patterns;
@@ -17,7 +18,7 @@ const parseHeadersArg = headersArg => {
     const headers = [];
     for (const [name, value] of Object.entries(headersArg)) {
         if (value !== null && typeof value !== 'string') {
-            throw Error(`Invalid header value for ${name}`);
+            throw illegalArgumentError(`requestModification: Invalid header value for ${name}`);
         }
 
         headers.push([name, value]);