@suffolklitlab/alkiln 5.13.4 → 5.15.0

package/lib/utils/Log.js

@@ -4,15 +4,59 @@ const session_vars = require( `./session_vars` );
 const time = require(`./time`);
 const files = require(`./files`);
 
-// ? 🌈 💡 🔎 🤕 🐛
-// Alternatives: 🩹 ❤️‍🩹 🚑 🖊️
+// ? 🌈 💡 🔎 🤕 🐛 🖊️
+// Alternatives: 🩹 ❤️‍🩹 🚑
 
 /**
  * Future issues:
- * - [ ] Save logs from GitHub actions as well? Users can download them themselves, but this
- *    might not be clear to them
- * - [ ] Capture cucumber ProgressFormatter logs instead of making them ourselves?
+ * - [ ] Save logs from GitHub actions as well? Users can download them
+ *   themselves, but this might not be clear to them.
+ * - [ ] Capture cucumber ProgressFormatter logs instead of making them
+ *   ourselves?
  * - [ ] keeping report separate for now (can just be an issue to integrate)
+ * - [ ] Discuss: instead of logging above an error, manipulate the error
+ *   message to prepend the accompanying log code, etc (all except the `before`
+ *   prop). Before this, do UX research to see if the current format is as
+ *   confusing to authors as it seems from this end.
+ * - [ ] Discuss: Should `.error()` return an Error? See discussion:
+ *   https://github.com/SuffolkLITLab/ALKiln/discussions/988
+ * */
+
+/**
+ * Quick examples:
+ * 
+log.debug({ code: `ALK0%%%`, context: `unspecified context`,},
+  `The message`,
+  some_val
+);
+
+log.success({ code: `ALK0%%%`, context: `unspecified context`,},
+  `The message`,
+  some_val
+);
+log.info({ code: `ALK0%%%`, context: `unspecified context`,},
+  `The message`,
+  some_val
+);
+log.warn({ code: `ALK0%%%`, context: `unspecified context`,},
+  `The message`,
+  some_val
+);
+log.error({ code: `ALK0%%%`, context: `unspecified context`,},
+  `The message`,
+  some_val
+);
+log.throw({ code: `ALK0%%%`, context: `unspecified context`,
+  error: new Error(
+    `Error message`
+  ),}
+);
+log.throw({ code: `ALK0%%%`, context: `unspecified context`,
+  error: new Error(
+    `Error message`
+  ),},
+  `Additional message`
+);
  * */
 
 class Log {
@@ -103,23 +147,96 @@ class Log {
      * const log = new Log({ path: "_alkiln-123", context: "setup" });
      * */
 
-    // GitHub actions will pass in a path that may already exist
-    if ( path ) { files.make_artifacts_folder( path ); }
-    // Other processes, like ALKilnInThePlayground, don't have a path
-    else { path = files.make_artifacts_folder(); }
+    // These records help internal tests check for correct behavior
+    this.internal_log_records = [];
 
-    this.path = path;
+    let dir = path;  // eventually, convert to this.dir instead of this.path
+
+    let is_new_folder = this._is_new_folder({ dir }).is_new;
+    this.path = this._make_or_get_folder({ dir }).dir;
+    // Discuss: Should making/saving the artifacts folder be hidden in here? If
+    //    not, where should it be? `make_artifacts_folder` maybe...
     session_vars.save_artifacts_path_name( this.path );
 
+    // Make sure `log` is in the logged context
+    if ( context ) { context = context + ` log`; }
+    else { context = `log`; }
+    let files_msg = `ALKiln will save test results files at "${ this.path }"`;
+    if ( is_new_folder ) {
+      this.info({ code: `ALK0214`, context, }, files_msg );
+    }  else {
+      this.debug({ code: `ALK0277`, context, }, files_msg );
+    }
+
     // Has this `Log` ever failed to append to the debug file?
     this.fs_append_to_debug_file_failed = false;
 
-    // Add `log` to the context and tell the author what the path is
-    if ( context ) { context = context + ` log`; }
-    else { context = `log`; }
-    this.info({ code: `ALK0214`, context, },
-      `Saving files to "${ this.path }"`
-    );
+  }
+
+  clear_internal_log_records() {
+    this.internal_log_records = [];
+  }
+
+  _is_new_folder({ dir }) {
+    /** Check if the artifacts folder is a new folder.
+     * 
+     * @param {object} obj - Named arguments
+     * @param {undefined | str} obj.dir - A folder path or undefined
+     * 
+     * @returns {{ is_new: bool, errors: [] | [Error] }} - Whether the folder
+     *     previously existed (if yes, true) and a list of any Errors that
+     *     happened
+     * */
+    let is_new = true;
+    try {
+
+      if ( dir ) {
+        if ( fs.existsSync( dir )) { is_new = false; }
+      } else if ( session_vars.get_artifacts_path_name() ) {
+        is_new = false;
+      }
+      return { is_new, errors: [] };
+
+    } catch ( folder_check_error ) {
+      return { is_new, errors: [ folder_check_error ]}
+    }
+  }
+
+  _make_or_get_folder({ dir }) {
+    /** Make a new folder for artifacts or get one that already exists.
+     * 
+     * The chosen directory will be, in order of precedence, the `dir` value,
+     *     an existing folder, or a completely new folder.
+     * 
+     * @param {object} obj - Named arguments
+     * @param {undefined | str} obj.dir - Optional. Desired path to the
+     *     artifacts folder.
+     * 
+     * @returns { {dir: str, errors: [Error]} } Object with the given directory
+     *     name and a list of 0 or more Error instances.
+     * */
+    try {
+
+      // GitHub actions pass in a dir, but other processes, like
+      //    ALKilnInThePlayground, don't have a path
+      if ( !dir ) {
+        if ( session_vars.get_artifacts_path_name() ) {
+          dir = session_vars.get_artifacts_path_name();
+        } else {
+          dir = files.make_artifacts_folder();
+        }
+      }
+
+      if ( !fs.existsSync( dir )) {
+        files.make_artifacts_folder( dir );
+      }
+
+      return { dir, errors: [] };
+
+    } catch ( error_making_dir ) {
+      return { dir, errors: [ error_making_dir ]};
+    }
+    
   }
 
   _console( console_opts = {}, ...logs ) {
@@ -128,7 +245,8 @@ class Log {
    *  takedown, run_cucumber (before and after running the tests), and API calls
    *  that interact with the server at those times. It writes to the console at
    *  different levels and throws errors. If it's not throwing a given error, it
-   *  returns the combined metadata and the logs as a formatted string.
+   *  returns the combined metadata and the logs as a formatted string. Only
+   *  internal code should call this method.
    *
    * The `_console` method will:
    *  1. Save the data to files with `log.debug()`
@@ -143,9 +261,12 @@ class Log {
    *                  ┌───────────────────────────────────────┐
    *                  │             ._console()               │
    *                  ├───────────────────────────────────────┤
-   * .throw()   ──┐   │  .debug() (all) (formatted logs str)  │
-   *              │   │  get metadata string (all)            │
-   *              │   │                                       │
+   * all below ─┐     │                                       │
+   *            ├────► .debug() (formatted logs str)          │
+   *            └────► get metadata string (all)              │
+   * then...          │                                       │
+   *                  │                                       │
+   * .throw()   ──┐   │                                       │
    *              ├────► get safe Error                       │
    *              ├────► console.error() with extra info      │
    *              └────► throw Error                          │
@@ -153,15 +274,17 @@ class Log {
    *              │   │                                       │
    * .info()    ──╘════► console.info() logs ════════════╗    │
    *                  │                                  ║    │
-   * .warn()    ───────► console.warn() logs─────┐       ║    │
-   *                  │                          ▼       ║    │
+   * .warn()    ───────► console.warn() logs───────┐     ║    │
+   *                  │                            │     ║    │
+   * .error()   ───────► console.error() logs───┐  │     ║    │
+   *                  │                         ▼  ▼     ║    │
    *                  │  return formatted logs string ◄══╝    │
    *                  └───────────────────────────────────────┘
    *
    * @param { Object } console_opts - Required. Metadata and functional flags
-   *     and data
-   * @param { success|info|warn|error } console_opts.level - Required. The log
-   *     level. Functional and metadata. Defined by the internal caller.
+   *     and data.
+   * @param { "success"|"info"|"warn"|"error" } console_opts.level - Required.
+   *     The log level. Functional and metadata. Defined by the internal caller.
    * @param { string } console_opts.before - Optional. Text to add before the
    *     metadata of the log. Metadata. Default "".
    * @param { string } console_opts.icon - Required. Unicode char put at the
@@ -172,18 +295,14 @@ class Log {
    * @param { string } console_opts.context - Optional. Info about the context
    *     where the log was called. Metadata. Examples: "setup", "run",
    *     "takedown". Default "". Defined by the original caller.
-   * @param { Error|any } console_opts.error - Optional. Only include if
-   *     `do_throw`  is true. Otherwise, `error` must be `undefined`. The error
-   *     or data to throw if `do_throw` is `true`. Before that throw, `_console`
-   *     will write the before, metadata, and logs. Try to use an actual
-   *     instance of  Error. Otherwise, the stack trace will include this
-   *     function, which is confusing. Avoid that. Default `undefined`. Defined
-   *     by the original caller.
+   * @param { Error|any } console_opts.error - Optional. The error or data to
+   *     eventually throw if `do_throw` is `true`, like with `.throw()`.
+   *     Otherwise, just another log. It will keep its original stack trace.
+   *     Default is `undefined`. Defined by the original caller.
    * @param { boolean } console_opts.do_throw - Optional. If `true` caller wants
-   *     to throw an error error. Default `false`. Defined by the original
-   *     caller.
+   *     to throw an error. Default `false`. Defined by the internal caller.
    * @param { ...any } logs - Optional. The logs to write to the console. Joined
-   *     by " " or "\n" depending on the type of the log. Default `undefined`.
+   *     by " " or "\n" depending on the type of the log. Default becomes `[]`.
    *     Defined by the original caller.
    *
    * @returns { string } Formatted metadata, logs, and, if given, the error.
@@ -243,44 +362,46 @@ class Log {
       error,  // Sometimes undefined
       do_throw = false,  // Sometimes undefined
     } = console_opts;
+    logs = logs || [];
+
+    if ( do_throw || error !== undefined ) {
+      error = this._get_Error_safely({ maybe_error: error });
+    }
 
-    let formatted_str_to_return = this.debug({ level, before, icon, code, context, error, do_throw }, ...logs );
+    let formatted_str_to_return = this.debug({
+      level, before, icon, code, context, error, do_throw,
+    }, ...logs );
 
     let metadata_str = this._format_metadata({ level, icon, code, context });
 
     // Throw whatever we can throw
     if ( do_throw ) {
-      error = this._get_Error_safely({ maybe_error: error });
-      // WARNING: If someone catches the error we throw, the console logs that
-      // get logged here before catching will be confusing.
+      // WARNING: If someone catches the error we throw, these strings will get
+      // logged. The final resulting logs may become confusing.
       try {
-        logs = logs || [];
-        console.error( `${before}${metadata_str}:`, ...logs );
+        console.error( `\n\n\n${before}${metadata_str}:`, ...logs );
       } catch ( pre_throw_error ) {
         this.debug({
           icon: `🖊️`, code: `ALK0215`, context: `internal log`, level: `note`,
         }, `Skipped logging metadata before throwing the error`, pre_throw_error );
       }
 
-      if ( error instanceof Error ) {
-        throw error;
-      } else {
-        // non-error messages will get in here if do_throw is `true` Ensure the
-        // call stack gets created at this point.
-        // Discuss: Should we include the metadata in this error since we don't
-        // need to preserve a stack trace? That's inconsistent, though.
-        throw new Error( error );
-      }
+      // Readers will see this text in the console, so give a clarifying name
+      let error_from_alkiln = error;
+      // ALKiln threw an error when preparing, cleaning up, or running the tests
+      throw error_from_alkiln;
     }
 
     // Avoid using custom-formatted logs and error here.
     // Let the console show them as it wants.
     try {
-      // log at the given level if console has that method (`log` by default).
-      // If a non-standard level was passed in, like `success`, use `info` by
-      // default.
+
+      let combined = this._combined_logs_and_error({ logs, error, do_throw });
+      // log at the given level if console has that method (`log` by default
+      // from ._console). If a non-standard level, like `success`, was passed in
+      // use `info` by default.
       if ( !console[ level ]) { level = `info`; }
-      console[ level ]( `${before}${metadata_str}:`, ...logs );
+      console[ level ]( `${before}${metadata_str}:`, ...combined );
 
     } catch ( console_log_error ) {
       // Fail silently
@@ -298,15 +419,28 @@ class Log {
      *  Returns a formatted string version of the log with its metadata. Avoids
      *  throwing internal errors while giving the max info possible. Avoids
      *  writing to the visible console. Every log should come through here.
+     *  External code can call this method.
      *
      * Tries to make saved logs look as similar as possible to console logs.
      *
-     * `.debug()` has the same signature as `._console()`, but saves to files
-     *  instead of writing to the console.
-     *
-     * @params - Similar to `._console()`, except we expect to use `.debug()`
-     *     directly as well as internally, while we expect to only use
-     *     `._console()` internally.
+     * @param { Object } console_opts - Required. Metadata and functional flags
+     *     and data.
+     * @param { "success"|"info"|"warn"|"error" } console_opts.level - Required.
+     *     The log level. Functional and metadata. Defined by the internal
+     *     caller.
+     * @param { string } console_opts.before - Optional. Text to add before the
+     *     metadata of the log. Metadata. Default "".
+     * @param { string } console_opts.icon - Required. Unicode char put at the
+     *     start of metadata. Makes the level more easy to see quickly. Defined
+     *     by the internal caller.
+     * @param { string } console_opts.code - Required. Unique consecutive log id
+     *     with the format ALK####. Defined by the original caller.
+     * @param { string } console_opts.context - Optional. Info about the context
+     *     where the log was called. Metadata. Examples: "setup", "run",
+     *     "takedown". Default "". Defined by the original caller.
+     * @param { ...any } logs - Optional. The logs to write to the console.
+     *     Joined by " " or "\n" depending on the type of the log. Default
+     *     becomes `[]`. Defined by the original caller.
      *
      * @returns { string } Same as `._console()`
      *
@@ -333,9 +467,12 @@ class Log {
       icon = `🐛`,
       code = `ALK000d`,
       context = ``,
-      error,  // Sometimes undefined
+      error,
       do_throw = false,
     } = debug_opts;
+    logs = logs || [];
+
+    this.internal_log_records.push({ opts: debug_opts, logs });
 
     // "warning" level and icon for for internal devs we use to avoid disrupting
     // the info authors are looking for
@@ -351,17 +488,13 @@ class Log {
       let logging_errors_msgs = [];
       try {
 
-        // Use `with_error` to include the error in the debug and unexpected
-        // results logs
-        let with_error = this._combine_logs_and_possible_error({
-          logs, maybe_error: error, do_throw,
-        });
-
-        let stringified = this._stringify_logs( ...with_error );
+        let combined = this._combined_logs_and_error({ logs, error, do_throw });
 
+        let stringified = this._stringify_logs( ...combined );
         // Question: Does `formatted` double log the error in the console?
         // Answer: `._console` doesn't use `formatted`, just returns it.
         formatted = `${ before }${ metadata_str }: ${ stringified }`;
+
       } catch ( formatted_log_error ) {
         formatted = `🖊️ ALK0212 internal debug NOTE [${ Date.now() }]: Skipped formatting debug logs.`;
         this._save_to_debug_safely({ unexpected: true, text: formatted });
@@ -491,31 +624,28 @@ class Log {
   }  // Ends Log._stringify_logs()
 
   _stringify_inline({ prev_line_type, inline_log }) {
-    /** Formats the start of an inline log based on the previous log and returns
-     *  that combined string.
+    /** Formats the log to add a space or a new line separator. May end up with
+     *     a leading space for now.
      *
      * @param { "inline"|"block"|null } prev_line_type - Required. The type of
      *     the previous log.
      * @param { null|non-obj } inline_log - Required. The log.
      *
-     * @returns { string } The formatted log.
+     * @returns { string } The formatted line.
      *
      * @example
      * // Backticks are to make the surrounding white space more clear
      * log._stringify_inline({ prev_line_type: null, inline_log: "apple" });
-     * // `apple`
+     * // "apple "
      * log._stringify_inline({ prev_line_type: 'inline', inline_log: "apple" });
-     * // ` apple`
+     * // "apple "
      * log._stringify_inline({ prev_line_type: 'block', inline_log: "apple" });
-     * // `
-     * // apple`
+     * // "
+     * // apple"
      * */
-    // An inline log's string starts with nothing if it's the first string...
     let start = ``;
-    // ...starts after a space if its next to an inline string...
-    if ( prev_line_type === `inline` ) { start = ` `; }
-    // ...or starts on a new line if it's after a block of text, like an error
-    // or object.
+    if ( prev_line_type === `inline` && !inline_log.startsWith(`\n`) ) { start = ` `; }
+    // This is actually the end of the block-type log
     else if ( prev_line_type === `block` ) { start = `\n`; }
     return `${ start }${ inline_log }`;
   }
@@ -525,6 +655,8 @@ class Log {
      *  a "block"-type separator at the start. Can handle circular references.
      *  Catch ANY error.
      *
+     * @param { "inline"|"block"|null } prev_line_type - Required. The type of
+     *     the previous log.
      * @param { Object } obj_log - Required. The object to format.
      *
      * @returns { string } The obj as a string plus a separator
@@ -536,15 +668,15 @@ class Log {
      * // { fruit: 'bananas' }
      * */
     let start = ``;
-    if ( prev_line_type === `inline` || prev_line_type === `block` ) {
-      start = `\n`;
-    }
+    // Avoid adding a new line to the start of the first line
+    let is_first_line = prev_line_type === null;
+    if ( !is_first_line ) { start = `\n`; }
 
     try {
       // Try to stringify the object.
       return `${ start }${ this._inspect({ value: obj_log }) }`;
 
-    // Discuss: record these errors?
+    // Discuss: record the outer error?
     } catch ( outer_error ) {
       // If that fails, see if it has its own way of stringifying
       try {
@@ -556,48 +688,29 @@ class Log {
     }  // ends outer try
   }
 
-  _combine_logs_and_possible_error({ logs=[], do_throw=false, maybe_error }) {
-    /** Returns a list of combined values to be logged. If we need to include
-     *  an error, ensure it's an error. Catch ANY internal errors.
-     *
-     * @param { array } logs - Required. List of logs.
-     * @param { boolean } do_throw - Optional. Default is `false`. If `true`
-     *     caller wants to throw an error.
-     * @param { Error|undefined } maybe_error - Optional. Default is
-     *     `undefined`. A value that might be. turned into an Error and is
-     *     definitely _safe_ to turn into an Error. For example, no circular
-     *     references.
-     *
-     * @returns { array } List of all values that should be logged.
-     *
-     * @example
-     * let with_error = log._combine_logs_and_possible_error({
-     *   [ "a", "b" ], do_throw: true, maybe_error: "A string."
-     * });
-     * // [ "a", "b", <An error with its stack and the message "A string."> ]
-     * @example
-     * let with_error = log._combine_logs_and_possible_error({
-     *   [ "a", "b" ], do_throw: false, maybe_error: new Error("An error.")
-     * });
-     * // [ "a", "b" ]
+  _combined_logs_and_error({ logs=[], error, do_throw=false }) {
+    /** Return a list of the given logs combined with the given error, if it
+     *     exists, ensuring the error is an Error.
+     * 
+     * @param { ...any } logs - Optional. The logs to write to the console.
+     *     Joined by " " or "\n" depending on the type of the log. Default
+     *     becomes `[]`. Defined by the original caller.
+     * @param { Error|any } console_opts.error - Optional. Any. Default is
+     *     `undefined`. Defined by the original caller.
+     * @param { boolean } console_opts.do_throw - Optional. If `true` caller wants
+     *     to throw an error. Default `false`. Defined by the internal caller.
+     * 
+     * @return [ any ] - List of logs, potentially with an added error
+     * 
      * */
-    let combined = [ ...logs ];
-    try {
-      // If we're supposed to throw, make sure the error gets an Error value.
-      if ( do_throw ) {
-        combined.push( this._get_Error_safely({ maybe_error }) );
-
-      // Otherwise error should be `undefined`. If not, we get a warning.
-      } else if ( maybe_error !== undefined ) {
-        this._save_to_debug_safely({ unexpected: true, text: `🖊️ ALK0223 internal debug NOTE [${ Date.now() }]: Only logs that throw should give a value to \`error\`. Skipping the value.` });
-      }
-    } catch ( combining_error_error ) {
-      this._save_to_debug_safely({ unexpected: true, text: `🖊️ ALK0226 internal debug NOTE [${ Date.now() }]: Skipped combining the logs.` });
-      this._save_to_debug_safely({ unexpected: true, text: combining_error_error.stack });
+    if ( do_throw || error !== undefined ) {
+      error = this._get_Error_safely({ maybe_error: error });
     }
+    let logs_maybe_with_error = [ ...logs ];
+    if ( error !== undefined ) { logs_maybe_with_error.push( error ); }
 
-    return combined;
-  } // Ends _combine_logs_and_possible_error()
+    return logs_maybe_with_error;
+  }
 
   _get_Error_safely({ maybe_error }) {
     /** Given anything, return an Error. Avoid throwing any errors.
@@ -605,17 +718,28 @@ class Log {
      * @param { Object } opts
      * @param { * } opts.maybe_error - Optional. Can be anything.
      *
-     * @returns { Error }
+     * @returns { Error|undefined }
      * */
-    if ( maybe_error instanceof Error ) {
-      return maybe_error;
-    } else {
-      if ( this._json_does_error( maybe_error )) {
-        maybe_error = this._get_inspected_val_safely( maybe_error );
+    try {
+
+      if ( maybe_error instanceof Error ) {
+        return maybe_error;
+      } else if ( maybe_error ) {
+
+        if ( this._json_does_error( maybe_error )) {
+          maybe_error = this._get_inspected_val_safely( maybe_error );
+        }
+
+        let error_from_alkiln = maybe_error;  // clearer name
+
+        // The stack trace `new Error()` creates here will be less helpful, but
+        // it's all we can do if the caller hasn't already created the error.
+        return new Error( error_from_alkiln );
+
       }
-      // The stack trace will be less helpful, but it's all we can do if the
-      // caller hasn't already created the error.
-      return new Error( maybe_error );
+    } catch ( get_safe_error_error ) {
+      this._save_to_debug_safely({ unexpected: true, text: `🖊️ ALK0226 internal debug NOTE [${ Date.now() }]: Skipped combining the logs.` });
+      this._save_to_debug_safely({ unexpected: true, text: get_safe_error_error.stack });
     }
   }
 
@@ -681,7 +805,7 @@ class Log {
      * @param logs { ...string } - Optional. Default is `undefined`. Explanation
      *     of what happened.
      *
-     * @returns { string } Formatted metadata, logs, and, if given, the error.
+     * @returns { string } Formatted metadata and logs.
      *
      * @example
      * log.warn({
@@ -693,13 +817,11 @@ class Log {
      * */
     // Discuss: do we want to log some successes as "💡 ... SUCCESS: " for
     // smaller successful operations along the way?
-    let {
-      code = `ALK000s`, before = ``, context = ``
-    } = success_opts;
     return this._console({
-      level: `success`, icon: `🌈`,
-      before, code, context,
-    }, ...logs);
+      code: `ALK000s`,
+      ...success_opts,
+      level: `success`, icon: `🌈`, do_throw: false,
+    }, ...logs );
   }
 
   info( info_opts = {}, ...logs ) {
@@ -717,7 +839,7 @@ class Log {
      * @param logs { ...string } - Optional. Default is `undefined`. Explanation
      *     of what happened.
      *
-     * @returns { string } Formatted metadata, logs, and, if given, the error.
+     * @returns { string } Formatted metadata and logs.
      *
      * @example
      * log.warn({
@@ -727,13 +849,11 @@ class Log {
      * }, "demo log");
      * // ~~~💡 ALK00d4 demo INFO [2024-08-16 00:30:39UTC]: demo log
      * */
-    let {
-      code = `ALK000i`, before = ``, context = ``,
-    } = info_opts;
     return this._console({
-      level: `info`, icon: `💡`,
-      before, code, context,
-    }, ...logs);
+      code: `ALK000i`,
+      ...info_opts,
+      level: `info`, icon: `💡`, do_throw: false,
+    }, ...logs );
   }
 
   warn( warning_opts = {}, ...logs ) {
@@ -751,7 +871,7 @@ class Log {
      * @param logs { ...string } - Optional. Default is `undefined`. Explanation
      *     of what happened.
      *
-     * @returns { string } Formatted metadata, logs, and, if given, the error.
+     * @returns { string } Formatted metadata and logs.
      *
      * @example
      * log.warn({
@@ -761,13 +881,47 @@ class Log {
      * }, "demo log");
      * // ~~~🔎 ALK00d5 demo WARNING [2024-08-16 00:30:39UTC]: demo log
      * */
-    let {
-      code = `ALK000w`, before = ``, context = ``
-    } = warning_opts;
     return this._console({
-      level: `warn`, icon: `🔎`,
-      before, code, context,
-    }, ...logs);
+      code: `ALK000w`,
+      ...warning_opts,
+      level: `warn`, icon: `🔎`, do_throw: false,
+    }, ...logs );
+  }
+
+  error( error_opts = {}, ...logs ) {
+    /** Log errors (messages with the error icon) to the console using
+     *      additional metadata and the given logs. Use it in ALKlin test suite
+     *      wrapper functionality, like setup and takedown.
+     *
+     * @param { Object } error_opts
+     * @param { string } error_opts.code - Required. Unique log id of the
+     *     format "ALK####", where "#" is a digit.
+     * @param { string } error_opts.before - Optional. Default is `""`.
+     *     Decoration to log before the metadata.
+     * @param { string } error_opts.context - Optional. Default is `""`. Info
+     *     about the origin of the logs.
+     * @param { ...string } logs - Optional. Default is `undefined`. Explanation
+     *     of what happened.
+     * @param { Error|any } error_opts.error - Default is `undefined`.
+     *     `.error()` treats this like an item in `logs` since `.error()`
+     *     doesn't throw.
+     *
+     * @returns { string } Formatted metadata, logs, and, if given, the error.
+     *
+     * @example
+     * log.warn({
+     *   before: "~~~",
+     *   code: "ALK00d5",
+     *   context: "demo",
+     *   error: 
+     * }, "demo log");
+     * // ~~~🤕 ALK00d5 demo WARNING [2024-08-16 00:30:39UTC]: demo log
+     * */
+    return this._console({
+      code: `ALK000e`,
+      ...error_opts,
+      level: `error`, icon: `🤕`, do_throw: false,
+    }, ...logs );
   }
 
   throw( throw_opts = {}, ...logs ){
@@ -807,14 +961,11 @@ class Log {
      * // Uncaught ReferenceError: undefined_value is not defined
      * // <the stack trace>
      * */
-    let {
-      code = `ALK000t`, before = ``, context = ``, error = `ALKiln default error`,
-    } = throw_opts;
-
     this._console({
-      level: `error`, icon: `🤕`, do_throw: true,
-      before, code, context, error,
-    }, ...logs);
+      code: `ALK000t`, error: new Error(`ALKiln default error`),
+      ...throw_opts,
+      do_throw: true, level: `error`, icon: `🤕`,
+    }, ...logs );
   }
 
   _save_to_debug_safely( save_debug_opts = {} ) {
@@ -962,18 +1113,19 @@ class Log {
   }
 
   clear() {
-    /** Empty all files possible without deleting them.
+    /** Empty all files possible without deleting them. Never throw. This is
+     *     nice to have, but not crucial.
      *
      * @returns { Log } Self.
      * */
     try { fs.writeFileSync( `${ this.path }/${ this.debug_log_filename }`, `` ); }
-    catch (error) { /* Fail without throwing. Nice to have, not crucial. */ }
+    catch (error) {}
     try { fs.writeFileSync( `${ this.path }/${ this.report_log_filename }`, `` ); }
-    catch (error) { /* Fail without throwing. Nice to have, not crucial. */ }
+    catch (error) {}
     try { fs.writeFileSync( `${ this.path }/${ this.report_filename }`, `` ); }
-    catch (error) { /* Fail without throwing. Nice to have, not crucial. */ }
+    catch (error) {}
     try { fs.writeFileSync( `${ this.path }/${ this.unexpected_filename }`, `` ); }
-    catch (error) { /* Fail without throwing. Nice to have, not crucial. */ }
+    catch (error) {}
     return this;
   }