Use standard log utility

src/spectator.cr

@@ -1,6 +1,9 @@
+require "log"
 require "./spectator/includes"
 require "./spectator_test_context"
 
+Log.setup_from_env
+
 # Module that contains all functionality related to Spectator.
 module Spectator
   extend self
@@ -8,13 +11,8 @@ module Spectator
   # Current version of the Spectator library.
   VERSION = {{ `shards version #{__DIR__}`.stringify.chomp }}
 
-  # Inserts code to produce a debug message.
-  # The code will only be injected when `spectator_debug` is defined (`-Dspectator_debug`).
-  macro debug(message)
-    {% if flag?(:spectator_debug) %}
-      STDERR.puts {{message}}
-    {% end %}
-  end
+  # Logger for Spectator internals.
+  Log = ::Log.for(self)
 
   # Top-level describe method.
   # All specs in a file must be wrapped in this call.
@@ -103,7 +101,7 @@ module Spectator
     # But if an exception occurs outside an example,
     # it's likely the fault of the test framework (Spectator).
     # So we display a helpful error that could be reported and return non-zero.
-    display_framework_error(ex)
+    Log.fatal(exception: ex) { "Spectator encountered an unexpected error" }
     false
   end
 
@@ -143,15 +141,4 @@ module Spectator
   private def apply_command_line_args : Nil
     CommandLineArgumentsConfigSource.new.apply_to(@@config_builder)
   end
-
-  # Displays a complete error stack.
-  # Prints an error and everything that caused it.
-  # Stacktrace is included.
-  private def display_framework_error(error) : Nil
-    STDERR.puts
-    STDERR.puts "!> Spectator encountered an unexpected error."
-    STDERR.puts "!> This is probably a bug and should be reported."
-    STDERR.puts
-    error.inspect_with_backtrace(STDERR)
-  end
 end

src/spectator/example.cr

@@ -28,7 +28,7 @@ module Spectator
     # Returns the result of the execution.
     # The result will also be stored in `#result`.
     def run : Result
-      Spectator.debug("Running example #{self}")
+      Log.debug { "Running example #{self}" }
       @delegate.call(self)
       raise NotImplementedError.new("#run")
     end

src/spectator/spec_builder.cr

@@ -8,6 +8,8 @@ module Spectator
   # A stack is used to track the current example group.
   # Adding an example or group will nest it under the group at the top of the stack.
   class SpecBuilder
+    Log = ::Spectator::Log.for(self)
+
     # Stack tracking the current group.
     # The bottom of the stack (first element) is the root group.
     # The root group should never be removed.
@@ -36,7 +38,7 @@ module Spectator
     # The newly created group is returned.
     # It shouldn't be used outside of this class until a matching `#end_group` is called.
     def start_group(name, source = nil) : ExampleGroup
-      Spectator.debug("Start group: #{name.inspect} @ #{source}")
+      Log.trace { "Start group: #{name.inspect} @ #{source}" }
       ExampleGroup.new(name, source, current_group).tap do |group|
         @group_stack << group
       end
@@ -49,7 +51,7 @@ module Spectator
     # At this point, it is safe to use the group.
     # All of its examples and sub-groups have been populated.
     def end_group : ExampleGroup
-      Spectator.debug("End group: #{current_group}")
+      Log.trace { "End group: #{current_group}" }
       raise "Can't pop root group" if root?
 
       @group_stack.pop
@@ -74,7 +76,7 @@ module Spectator
     #
     # The newly created example is returned.
     def add_example(name, source, context, &block : Example, Context ->) : Example
-      Spectator.debug("Add example: #{name} @ #{source}")
+      Log.trace { "Add example: #{name} @ #{source}" }
       delegate = ExampleContextDelegate.new(context, block)
       Example.new(delegate, name, source, current_group)
       # The example is added to the current group by `Example` initializer.