sus 0.34.0 → 0.35.0

data/lib/sus/mock.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require_relative "expect"
 
 module Sus
+	# Represents a mock object that can intercept and replace method calls on a target object.
 	class Mock
+		# Initialize a new mock for the given target.
+		# @parameter target [Object] The object to mock.
 		def initialize(target)
 			@target = target
 			@interceptor = Module.new
@@ -14,18 +17,26 @@ module Sus
 			@target.singleton_class.prepend(@interceptor)
 		end
 		
+		# @attribute [Object] The target object being mocked.
 		attr :target
 		
+		# Print a representation of this mock.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("mock ", :context, @target.inspect)
 		end
 		
+		# Clear all mocked methods from the target.
 		def clear
 			@interceptor.instance_methods.each do |method_name|
 				@interceptor.remove_method(method_name)
 			end
 		end
 		
+		# Replace a method implementation.
+		# @parameter method [Symbol] The method name to replace.
+		# @yields {|*arguments, **options, &block| ...} The replacement implementation.
+		# @returns [Mock] Returns self for method chaining.
 		def replace(method, &hook)
 			execution_context = Thread.current
 			
@@ -40,6 +51,10 @@ module Sus
 			return self
 		end
 		
+		# Add a hook that runs before a method is called.
+		# @parameter method [Symbol] The method name to hook.
+		# @yields {|*arguments, **options, &block| ...} The hook to execute before the method.
+		# @returns [Mock] Returns self for method chaining.
 		def before(method, &hook)
 			execution_context = Thread.current
 			
@@ -51,6 +66,10 @@ module Sus
 			return self
 		end
 		
+		# Add a hook that runs after a method is called.
+		# @parameter method [Symbol] The method name to hook.
+		# @yields {|result, *arguments, **options, &block| ...} The hook to execute after the method, receiving the result as the first argument.
+		# @returns [Mock] Returns self for method chaining.
 		def after(method, &hook)
 			execution_context = Thread.current
 			
@@ -64,6 +83,8 @@ module Sus
 		end
 		
 		# Wrap a method, yielding the original method as the first argument, so you can call it from within the hook.
+		# @parameter method [Symbol] The method name to wrap.
+		# @yields {|original, *arguments, **options, &block| ...} The wrapper implementation, receiving the original method as the first argument.
 		def wrap(method, &hook)
 			execution_context = Thread.current
 			
@@ -81,13 +102,20 @@ module Sus
 		end
 	end
 	
+	# Provides mock management functionality for test cases.
 	module Mocks
+		# Clean up all mocks after the test completes.
+		# @parameter error [Exception | Nil] The error that occurred, if any.
 		def after(error = nil)
 			super
 			
 			@mocks&.each_value(&:clear)
 		end
 		
+		# Create or access a mock for the given target.
+		# @parameter target [Object] The object to mock.
+		# @yields {|mock| ...} Optional block to configure the mock.
+		# @returns [Mock] The mock instance for the target.
 		def mock(target)
 			validate_mock!(target)
 			
@@ -102,20 +130,30 @@ module Sus
 		
 		private
 		
+		# Error raised when attempting to mock a frozen object.
 		MockTargetError = Class.new(StandardError)
 		
+		# Validate that the target can be mocked.
+		# @parameter target [Object] The object to validate.
+		# @raises [MockTargetError] If the target is frozen.
 		def validate_mock!(target)
 			if target.frozen?
 				raise MockTargetError, "Cannot mock frozen object #{target.inspect}!"
 			end
 		end
 		
+		# Get the mocks hash, creating it if necessary.
+		# @returns [Hash] A hash mapping targets to their mock instances.
 		def mocks
 			@mocks ||= Hash.new{|h,k| h[k] = Mock.new(k)}.compare_by_identity
 		end
 	end
 	
 	class Base
+		# Create or access a mock for the given target.
+		# @parameter target [Object] The object to mock.
+		# @yields {|mock| ...} Optional block to configure the mock.
+		# @returns [Mock] The mock instance for the target.
 		def mock(target, &block)
 			# Pull in the extra functionality:
 			self.singleton_class.prepend(Mocks)

data/lib/sus/output/backtrace.rb

@@ -5,21 +5,32 @@
 
 module Sus
 	module Output
-		# Print out a backtrace relevant to the given test identity if provided.
+		# Represents a backtrace for displaying error locations.
 		class Backtrace
+			# Create a backtrace from the first caller location.
+			# @parameter identity [Identity, nil] Optional identity to filter by path.
+			# @returns [Backtrace] A new Backtrace instance.
 			def self.first(identity = nil)
 				# This implementation could be a little more efficient.
 				self.new(caller_locations(1), identity&.path, 1)
 			end
 			
+			# Create a backtrace from an exception.
+			# @parameter exception [Exception] The exception to extract the backtrace from.
+			# @parameter identity [Identity, nil] Optional identity to filter by path.
+			# @returns [Backtrace] A new Backtrace instance.
 			def self.for(exception, identity = nil)
 				# I've disabled the root filter here, because partial backtraces are not very useful.
 				# We might want to do something to improve presentation of the backtrace based on the root instead.
 				self.new(extract_stack(exception), identity&.path)
 			end
 			
+			# Represents a location in a backtrace.
 			Location = Struct.new(:path, :lineno, :label)
 			
+			# Extract the stack trace from an exception.
+			# @parameter exception [Exception] The exception to extract from.
+			# @returns [Array] An array of location objects.
 			def self.extract_stack(exception)
 				if stack = exception.backtrace_locations
 					return stack
@@ -32,16 +43,29 @@ module Sus
 				end
 			end
 			
+			# Initialize a new Backtrace.
+			# @parameter stack [Array] The stack trace locations.
+			# @parameter root [String, nil] Optional root path to filter by.
+			# @parameter limit [Integer, nil] Optional limit on the number of frames.
 			def initialize(stack, root = nil, limit = nil)
 				@stack = stack
 				@root = root
 				@limit = limit
 			end
 			
+			# @attribute [Array] The stack trace locations.
 			attr :stack
+			
+			# @attribute [String, nil] The root path to filter by.
 			attr :root
+			
+			# @attribute [Integer, nil] The limit on the number of frames.
 			attr :limit
 			
+			# Filter the backtrace by root path and limit.
+			# @parameter root [String, nil] Optional root path to filter by.
+			# @parameter limit [Integer, nil] Optional limit on the number of frames.
+			# @returns [Array, Enumerator] The filtered stack trace.
 			def filter(root: @root, limit: @limit)
 				if root
 					if limit
@@ -60,6 +84,8 @@ module Sus
 				end
 			end
 			
+			# Print the backtrace to the output.
+			# @parameter output [Output] The output handler.
 			def print(output)
 				if @limit == 1
 					filter.each do |frame|
@@ -74,6 +100,10 @@ module Sus
 				end
 			end
 			
+			# Select items up to and matching a condition.
+			# @parameter things [Enumerable] The items to filter.
+			# @yields {|thing| ...} The condition to match.
+			# @returns [Array] The filtered items.
 			private def up_to_and_matching(things, &block)
 				preface = true
 				things.select do |thing|

data/lib/sus/output/bar.rb

@@ -5,7 +5,9 @@
 
 module Sus
 	module Output
+		# Represents a progress bar for displaying test execution progress.
 		class Bar
+			# Unicode block characters for drawing the progress bar.
 			BLOCK = [
 				" ",
 				"▏",
@@ -18,6 +20,10 @@ module Sus
 				"█",
 			]
 			
+			# Initialize a new progress bar.
+			# @parameter current [Integer] The current progress value.
+			# @parameter total [Integer] The total value.
+			# @parameter message [String, nil] Optional message to display.
 			def initialize(current = 0, total = 0, message = nil)
 				@maximum_message_width = 0
 				
@@ -26,19 +32,30 @@ module Sus
 				@message = message
 			end
 			
+			# Update the progress bar values.
+			# @parameter current [Integer] The current progress value.
+			# @parameter total [Integer] The total value.
+			# @parameter message [String, nil] Optional message to display.
 			def update(current, total, message)
 				@current = current
 				@total = total
 				@message = message
 			end
 			
+			# Register progress bar styling with an output handler.
+			# @parameter output [Output] The output handler to register with.
 			def self.register(output)
 				output[:progress_bar] ||= output.style(:blue, :white)
 			end
 			
+			# The minimum width for the progress bar.
 			MINIMUM_WIDTH = 8
+			
+			# The suffix to append to messages.
 			MESSAGE_SUFFIX = ": "
 			
+			# Print the progress bar to the output.
+			# @parameter output [Output] The output handler.
 			def print(output)
 				width = output.width
 				

data/lib/sus/output/buffered.rb

@@ -7,17 +7,23 @@ require "io/console"
 require "stringio"
 
 module Sus
-	# Styled output output.
 	module Output
+		# Represents a buffered output handler that stores output operations for later replay.
 		class Buffered
+			# Initialize a new Buffered output handler.
+			# @parameter tee [Output, nil] Optional output handler to tee output to.
 			def initialize(tee = nil)
 				@chunks = Array.new
 				@tee = tee
 			end
 			
+			# @attribute [Array] The stored output chunks.
 			attr :chunks
+			
+			# @attribute [Output, nil] The output handler to tee to.
 			attr :tee
 			
+			# @returns [String] A string representation of this buffered output.
 			def inspect
 				if @tee
 					"\#<#{self.class.name} #{@chunks.size} chunks -> #{@tee.class}>"
@@ -26,39 +32,52 @@ module Sus
 				end
 			end
 			
+			# Create a nested buffered output handler.
+			# @returns [Buffered] A new Buffered instance that tees to this one.
 			def buffered
 				self.class.new(self)
 			end
 			
+			# Iterate over stored chunks.
+			# @yields {|chunk| ...} Each stored chunk.
 			def each(&block)
 				@chunks.each(&block)
 			end
 			
+			# Append chunks from another buffer.
+			# @parameter buffer [Buffered] The buffer to append from.
 			def append(buffer)
 				@chunks.concat(buffer.chunks)
 				@tee&.append(buffer)
 			end
 			
+			# @returns [String] The buffered output as a string.
 			def string
 				io = StringIO.new
 				Text.new(io).append(@chunks)
 				return io.string
 			end
 			
+			# The indent operation marker.
 			INDENT = [:indent].freeze
 			
+			# Increase indentation level.
 			def indent
 				@chunks << INDENT
 				@tee&.indent
 			end
 			
+			# The outdent operation marker.
 			OUTDENT = [:outdent].freeze
 			
+			# Decrease indentation level.
 			def outdent
 				@chunks << OUTDENT
 				@tee&.outdent
 			end
 			
+			# Execute a block with increased indentation.
+			# @yields {...} The block to execute.
 			def indented
 				self.indent
 				yield
@@ -66,31 +85,43 @@ module Sus
 				self.outdent
 			end
 			
+			# Write output.
+			# @parameter arguments [Array] The arguments to write.
 			def write(*arguments)
 				@chunks << [:write, *arguments]
 				@tee&.write(*arguments)
 			end
 			
+			# Write output followed by a newline.
+			# @parameter arguments [Array] The arguments to write.
 			def puts(*arguments)
 				@chunks << [:puts, *arguments]
 				@tee&.puts(*arguments)
 			end
 			
+			# Record an assertion.
+			# @parameter arguments [Array] The assertion arguments.
 			def assert(*arguments)
 				@chunks << [:assert, *arguments]
 				@tee&.assert(*arguments)
 			end
 			
+			# Record a skip.
+			# @parameter arguments [Array] The skip arguments.
 			def skip(*arguments)
 				@chunks << [:skip, *arguments]
 				@tee&.skip(*arguments)
 			end
 			
+			# Record an error.
+			# @parameter arguments [Array] The error arguments.
 			def error(*arguments)
 				@chunks << [:error, *arguments]
 				@tee&.error(*arguments)
 			end
 			
+			# Record an informational message.
+			# @parameter arguments [Array] The message arguments.
 			def inform(*arguments)
 				@chunks << [:inform, *arguments]
 				@tee&.inform(*arguments)

data/lib/sus/output/lines.rb

@@ -7,7 +7,10 @@ require "io/console"
 
 module Sus
 	module Output
+		# Represents a line buffer for managing multiple lines of output on a terminal.
 		class Lines
+			# Initialize a new Lines buffer.
+			# @parameter output [Output] The output handler to write to.
 			def initialize(output)
 				@output = output
 				@lines = []
@@ -15,21 +18,28 @@ module Sus
 				@current_count = 0
 			end
 			
+			# @returns [Integer] The height of the terminal.
 			def height
 				@output.size.first
 			end
 			
+			# Set a line at the given index.
+			# @parameter index [Integer] The line index.
+			# @parameter line [Object] The line content (should respond to #print).
 			def []= index, line
 				@lines[index] = line
 				
 				redraw(index)
 			end
 			
+			# Clear all lines.
 			def clear
 				@lines.clear
 				write
 			end
 			
+			# Redraw a specific line or all lines.
+			# @parameter index [Integer] The line index to redraw.
 			def redraw(index)
 				if index < @current_count
 					update(index, @lines[index])

data/lib/sus/output/messages.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 module Sus
-	# Styled output output.
 	module Output
+		# Provides message formatting methods for output handlers.
 		module Messages
+			# The prefix for passed assertions.
 			PASSED_PREFIX = [:passed, "✓ "].freeze
+			
+			# The prefix for failed assertions.
 			FAILED_PREFIX = [:failed, "✗ "].freeze
 			
+			# Get the prefix for a passed assertion based on orientation.
+			# @parameter orientation [Boolean] The orientation of the assertions.
+			# @returns [Array] The prefix array.
 			def pass_prefix(orientation)
 				if orientation
 					PASSED_PREFIX
@@ -18,6 +24,9 @@ module Sus
 				end
 			end
 			
+			# Get the prefix for a failed assertion based on orientation.
+			# @parameter orientation [Boolean] The orientation of the assertions.
+			# @returns [Array] The prefix array.
 			def fail_prefix(orientation)
 				if orientation
 					FAILED_PREFIX
@@ -26,6 +35,7 @@ module Sus
 				end
 			end
 			
+			# Print an assertion result.
 			# If the orientation is true, and the test passed, then it is a successful outcome.
 			# If the orientation is false, and the test failed, then it is a successful outcome.
 			# Otherwise, it is a failed outcome.
@@ -33,7 +43,7 @@ module Sus
 			# @parameter condition [Boolean] The result of the test.
 			# @parameter orientation [Boolean] The orientation of the assertions.
 			# @parameter message [String] The message to display.
-			# @parameter backtrace [Array] The backtrace to display.
+			# @parameter backtrace [Backtrace] The backtrace to display.
 			def assert(condition, orientation, message, backtrace)
 				if condition
 					self.puts(:indent, *pass_prefix(orientation), message, backtrace)
@@ -42,18 +52,27 @@ module Sus
 				end
 			end
 			
+			# @returns [String] The prefix for skipped tests.
 			def skip_prefix
 				"⏸ "
 			end
 			
+			# Print a skip message.
+			# @parameter reason [String] The reason for skipping.
+			# @parameter identity [Identity, nil] The identity where the skip occurred.
 			def skip(reason, identity)
 				self.puts(:indent, :skipped, skip_prefix, reason)
 			end
 			
+			# @returns [Array] The prefix for error messages.
 			def error_prefix
 				[:errored, "⚠ "]
 			end
 			
+			# Print an error message.
+			# @parameter error [Exception] The error to display.
+			# @parameter identity [Identity, nil] The identity where the error occurred.
+			# @parameter prefix [Array] Optional prefix to use.
 			def error(error, identity, prefix = error_prefix)
 				lines = error.message.split(/\r?\n/)
 				
@@ -70,10 +89,14 @@ module Sus
 				end
 			end
 			
+			# @returns [String] The prefix for informational messages.
 			def inform_prefix
 				"ℹ "
 			end
 			
+			# Print an informational message.
+			# @parameter message [String] The message to display.
+			# @parameter identity [Identity, nil] The identity where the message was generated.
 			def inform(message, identity)
 				self.puts(:indent, :inform, inform_prefix, message)
 			end

data/lib/sus/output/null.rb

@@ -1,42 +1,56 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "messages"
 
 module Sus
-	# Styled output output.
 	module Output
+		# Represents a null output handler that discards all output.
 		class Null
 			include Messages
 			
+			# Initialize a new Null output handler.
 			def initialize
 			end
 			
+			# Create a buffered output handler.
+			# @returns [Buffered] A new Buffered instance.
 			def buffered
 				Buffered.new(nil)
 			end
 			
+			# @attribute [Hash, nil] Optional options (unused).
 			attr :options
 			
+			# Append chunks from a buffer (no-op).
+			# @parameter buffer [Buffered] The buffer to append from.
 			def append(buffer)
 			end
 			
+			# Increase indentation (no-op).
 			def indent
 			end
 			
+			# Decrease indentation (no-op).
 			def outdent
 			end
 			
+			# Execute a block with indentation (no-op, just yields).
+			# @yields {...} The block to execute.
 			def indented
 				yield
 			end
 			
+			# Write output (no-op).
+			# @parameter arguments [Array] The arguments to write.
 			def write(*arguments)
 				# Do nothing.
 			end
 			
+			# Write output followed by a newline (no-op).
+			# @parameter arguments [Array] The arguments to write.
 			def puts(*arguments)
 				# Do nothing.
 			end

data/lib/sus/output/progress.rb

@@ -9,11 +9,18 @@ require_relative "lines"
 
 module Sus
 	module Output
+		# Represents a progress tracker for test execution.
 		class Progress
+			# Get the current monotonic time.
+			# @returns [Float] The current time in seconds.
 			def self.now
 				::Process.clock_gettime(Process::CLOCK_MONOTONIC)
 			end
 			
+			# Initialize a new Progress tracker.
+			# @parameter output [Output] The output handler.
+			# @parameter total [Integer] The total number of items to track.
+			# @parameter minimum_output_duration [Float] Minimum duration before showing output (unused).
 			def initialize(output, total = 0, minimum_output_duration: 1.0)
 				@output = output
 				@subject = subject
@@ -30,35 +37,47 @@ module Sus
 				@total = total
 			end
 			
+			# @attribute [Object, nil] The subject being tracked.
 			attr :subject
+			
+			# @attribute [Integer] The current progress value.
 			attr :current
+			
+			# @attribute [Integer] The total value.
 			attr :total
 			
+			# @returns [Float] The elapsed duration in seconds.
 			def duration
 				Progress.now - @start_time
 			end
 			
+			# @returns [Float] The progress as a fraction (0.0 to 1.0).
 			def progress
 				@current.to_f / @total.to_f
 			end
 			
+			# @returns [Integer] The remaining items to process.
 			def remaining
 				@total - @current
 			end
 			
+			# @returns [Float, nil] The average duration per item, or nil if no items completed.
 			def average_duration
 				if @current > 0
 					duration / @current
 				end
 			end
 			
+			# @returns [Float, nil] The estimated remaining time, or nil if cannot be calculated.
 			def estimated_remaining_time
 				if average_duration = self.average_duration
 					average_duration * remaining
 				end
 			end
 			
-			# Increase the amont of work done.
+			# Increase the amount of work done.
+			# @parameter amount [Integer] The amount to increment by.
+			# @returns [Progress] Returns self for method chaining.
 			def increment(amount = 1)
 				@current += amount
 				
@@ -69,6 +88,8 @@ module Sus
 			end
 			
 			# Increase the total size of the progress.
+			# @parameter amount [Integer] The amount to expand by.
+			# @returns [Progress] Returns self for method chaining.
 			def expand(amount = 1)
 				@total += amount
 				
@@ -78,16 +99,23 @@ module Sus
 				return self
 			end
 			
+			# Report the status of a specific item.
+			# @parameter index [Integer] The index of the item.
+			# @parameter context [Object] The context to display.
+			# @parameter state [Symbol] The state (:free or :busy).
+			# @returns [Progress] Returns self for method chaining.
 			def report(index, context, state)
 				@lines&.[]=(index+1, Status.new(state, context))
 				
 				return self
 			end
 			
+			# Clear the progress display.
 			def clear
 				@lines&.clear
 			end
 			
+			# @returns [String] A string representation of the progress.
 			def to_s
 				if estimated_remaining_time = self.estimated_remaining_time
 					"#{@current}/#{@total} completed in #{formatted_duration(self.duration)}, #{formatted_duration(estimated_remaining_time)} remaining"