sus 0.33.1 → 0.35.0

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"

data/lib/sus/output/status.rb

@@ -5,27 +5,38 @@
 
 module Sus
 	module Output
+		# Represents a status indicator for test execution.
 		class Status
+			# Register status styling with an output handler.
+			# @parameter output [Output] The output handler to register with.
 			def self.register(output)
 				output[:free] ||= output.style(:blue)
 				output[:busy] ||= output.style(:orange)
 			end
 			
+			# Initialize a new Status indicator.
+			# @parameter state [Symbol] The state (:free or :busy).
+			# @parameter context [Object, nil] Optional context to display.
 			def initialize(state = :free, context = nil)
 				@state = state
 				@context = context
 			end
 			
+			# Status indicators for different states.
 			INDICATORS = {
 				busy: ["◑", "◒", "◐", "◓"],
 				free: ["◌"]
 			}
 			
+			# Update the status.
+			# @parameter state [Symbol] The new state.
+			# @parameter context [Object, nil] Optional new context.
 			def update(state, context = nil)
 				@state = state
 				@context = context
 			end
 			
+			# @returns [String] The current indicator character (animated for busy state).
 			def indicator
 				if indicators = INDICATORS[@state]
 					return indicators[(Time.now.to_f * 10) % indicators.size]
@@ -34,6 +45,8 @@ module Sus
 				return " "
 			end
 			
+			# Print the status to the output.
+			# @parameter output [Output] The output handler.
 			def print(output)
 				output.write(
 					@state, self.indicator, " "

data/lib/sus/output/structured.rb

@@ -6,22 +6,35 @@
 require_relative "null"
 
 module Sus
-	# Styled output output.
 	module Output
+		# Represents a structured JSON output handler for machine-readable output.
 		class Structured < Null
+			# Create a buffered structured output handler.
+			# @parameter io [IO] The IO object to write to.
+			# @parameter identity [Identity, nil] Optional identity.
+			# @returns [Buffered] A new Buffered instance wrapping a Structured handler.
 			def self.buffered(...)
 				Buffered.new(self.new(...))
 			end
 			
+			# Initialize a new Structured output handler.
+			# @parameter io [IO] The IO object to write to.
+			# @parameter identity [Identity, nil] Optional identity.
 			def initialize(io, identity = nil)
 				@io = io
 				@identity = identity
 			end
 			
+			# Output a skip message as JSON.
+			# @parameter reason [String] The reason for skipping.
+			# @parameter identity [Identity, nil] The identity where the skip occurred.
 			def skip(reason, identity)
 				inform(reason.to_s, identity)
 			end
 			
+			# Output an informational message as JSON.
+			# @parameter message [String, Object] The message to output.
+			# @parameter identity [Identity, nil] The identity where the message was generated.
 			def inform(message, identity)
 				unless message.is_a?(String)
 					message = message.inspect

data/lib/sus/output/text.rb

@@ -8,9 +8,12 @@ require_relative "buffered"
 
 module Sus
 	module Output
+		# Represents a plain text output handler without color support.
 		class Text
 			include Messages
 			
+			# Initialize a new Text output handler.
+			# @parameter io [IO] The IO object to write to.
 			def initialize(io)
 				@io = io
 				
@@ -20,30 +23,41 @@ module Sus
 				@styles[:indent] = @indent
 			end
 			
+			# @attribute [Hash] The style definitions.
 			attr :styles
 			
+			# Create a buffered output handler.
+			# @returns [Buffered] A new Buffered instance.
 			def buffered
 				Buffered.new(self)
 			end
 			
+			# Append and replay chunks from a buffer.
+			# @parameter buffer [Buffered] The buffer to append from.
 			def append(buffer)
 				buffer.each do |operation|
 					self.public_send(*operation)
 				end
 			end
 			
+			# @attribute [IO] The IO object to write to.
 			attr :io
 			
+			# The indentation string.
 			INDENTATION = "\t"
 			
+			# Increase indentation level.
 			def indent
 				@indent << INDENTATION
 			end
 			
+			# Decrease indentation level.
 			def outdent
 				@indent.slice!(INDENTATION)
 			end
 			
+			# Execute a block with increased indentation.
+			# @yields {...} The block to execute.
 			def indented
 				self.indent
 				yield
@@ -51,33 +65,49 @@ module Sus
 				self.outdent
 			end
 			
+			# @returns [Boolean] Whether the IO is interactive (a TTY).
 			def interactive?
 				@io.tty?
 			end
 			
+			# Get a style by key.
+			# @parameter key [Symbol] The style key.
+			# @returns [String] The style value.
 			def [] key
 				@styles[key]
 			end
 			
+			# Set a style by key.
+			# @parameter key [Symbol] The style key.
+			# @parameter value [String] The style value.
 			def []= key, value
 				@styles[key] = value
 			end
 			
+			# @returns [Array(Integer)] The terminal size [height, width] (defaults to [24, 80]).
 			def size
 				[24, 80]
 			end
 			
+			# @returns [Integer] The terminal width (defaults to 80).
 			def width
 				size.last
 			end
 			
+			# @returns [Boolean] Always returns false, as Text output doesn't support colors.
 			def colors?
 				false
 			end
 			
+			# Create a style string (no-op for Text output).
+			# @parameter foreground [Symbol, nil] The foreground color.
+			# @parameter background [Symbol, nil] The background color.
+			# @parameter attributes [Array] Additional style attributes.
+			# @returns [String] An empty string.
 			def style(foreground, background = nil, *attributes)
 			end
 			
+			# @returns [String] An empty string (no reset needed for plain text).
 			def reset
 			end
 			
@@ -85,6 +115,7 @@ module Sus
 			# When the argument is a symbol, look up the style and inject it into the io stream.
 			# When the argument is a proc/lambda, call it with self as the argument.
 			# When the argument is anything else, write it directly to the io.
+			# @parameter arguments [Array] The arguments to write.
 			def write(*arguments)
 				arguments.each do |argument|
 					case argument
@@ -102,7 +133,8 @@ module Sus
 				end
 			end
 			
-			# Print out the arguments as per {#print}, followed by the reset sequence and a newline.
+			# Print out the arguments as per {#write}, followed by the reset sequence and a newline.
+			# @parameter arguments [Array] The arguments to write.
 			def puts(*arguments)
 				write(*arguments)
 				@io.puts(self.reset)

data/lib/sus/output/xterm.rb

@@ -8,9 +8,10 @@ require "io/console"
 require_relative "text"
 
 module Sus
-	# Styled output output.
 	module Output
+		# Represents an XTerm-compatible output handler with color and style support.
 		class XTerm < Text
+			# Color codes for ANSI terminal colors.
 			COLORS = {
 				black: 0,
 				red: 1,
@@ -23,6 +24,7 @@ module Sus
 				default: 9,
 			}
 			
+			# Style attribute codes for ANSI terminal attributes.
 			ATTRIBUTES = {
 				normal: 0,
 				bold: 1,
@@ -35,14 +37,21 @@ module Sus
 				hidden: 8,
 			}
 			
+			# @returns [Boolean] Always returns true, as XTerm output supports colors.
 			def colors?
 				true
 			end
 			
+			# @returns [Array(Integer)] The terminal size [height, width].
 			def size
 				@io.winsize
 			end
 			
+			# Create an ANSI escape sequence for styling.
+			# @parameter foreground [Symbol, nil] The foreground color name.
+			# @parameter background [Symbol, nil] The background color name.
+			# @parameter attributes [Array] Additional style attributes.
+			# @returns [String] An ANSI escape sequence.
 			def style(foreground, background = nil, *attributes)
 				tokens = []
 				
@@ -61,6 +70,7 @@ module Sus
 				return "\e[#{tokens.join(';')}m"
 			end
 			
+			# @returns [String] The ANSI reset sequence.
 			def reset
 				"\e[0m"
 			end

data/lib/sus/output.rb

@@ -11,7 +11,11 @@ require_relative "output/null"
 require_relative "output/progress"
 
 module Sus
+	# Represents output handlers for test results and messages.
 	module Output
+		# Create an appropriate output handler for the given IO.
+		# @parameter io [IO] The IO object to write to.
+		# @returns [XTerm, Text] An XTerm handler if the IO is a TTY, otherwise a Text handler.
 		def self.for(io)
 			if io.isatty
 				XTerm.new(io)
@@ -20,6 +24,9 @@ module Sus
 			end
 		end
 		
+		# Create a default output handler with styling configured.
+		# @parameter io [IO] The IO object to write to (defaults to $stderr).
+		# @returns [XTerm, Text] A configured output handler.
 		def self.default(io = $stderr)
 			output = self.for(io)
 			
@@ -47,6 +54,8 @@ module Sus
 			return output
 		end
 		
+		# Create a buffered output handler.
+		# @returns [Buffered] A new buffered output handler.
 		def self.buffered
 			Buffered.new
 		end

data/lib/sus/raise_exception.rb

@@ -4,18 +4,28 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
+	# Represents a predicate that checks if a block raises an exception.
 	class RaiseException
+		# Initialize a new RaiseException predicate.
+		# @parameter exception_class [Class] The exception class to expect.
+		# @parameter message [String, Regexp, Object | Nil] Optional message matcher.
 		def initialize(exception_class = Exception, message: nil)
 			@exception_class = exception_class
 			@message = message
 			@predicate = nil
 		end
 		
+		# Add an additional predicate to check on the exception.
+		# @parameter predicate [Object] The predicate to apply to the exception.
+		# @returns [RaiseException] Returns self for method chaining.
 		def and(predicate)
 			@predicate = predicate
 			return self
 		end
 		
+		# Evaluate this predicate against a subject (block).
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Proc] The block to evaluate.
 		def call(assertions, subject)
 			assertions.nested(self) do |assertions|
 				begin
@@ -36,6 +46,8 @@ module Sus
 			end
 		end
 		
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("raise exception")
 			
@@ -54,6 +66,10 @@ module Sus
 	end
 	
 	class Base
+		# Create a predicate that checks if a block raises an exception.
+		# @parameter exception_class [Class] The exception class to expect.
+		# @parameter message [String, Regexp, Object | Nil] Optional message matcher.
+		# @returns [RaiseException] A new RaiseException predicate.
 		def raise_exception(...)
 			RaiseException.new(...)
 		end

data/lib/sus/receive.rb

@@ -6,7 +6,12 @@
 require_relative "respond_to"
 
 module Sus
+	# Represents an expectation that a method will be called on an object.
 	class Receive
+		# Initialize a new Receive expectation.
+		# @parameter base [Object] The base object (usually self from Base).
+		# @parameter method [Symbol] The method name to expect.
+		# @yields {...} Optional block that returns the value to return from the method.
 		def initialize(base, method, &block)
 			@base = base
 			@method = method
@@ -19,46 +24,73 @@ module Sus
 			@returning = block
 		end
 		
+		# Print a representation of this expectation.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("receive ", :variable, @method.to_s, :reset)
 		end
 		
+		# Specify that the method should be called with specific arguments.
+		# @parameter predicate [Object] The predicate to match against the arguments.
+		# @returns [Receive] Returns self for method chaining.
 		def with_arguments(predicate)
 			@arguments = WithArguments.new(predicate)
 			return self
 		end
 		
+		# Specify that the method should be called with specific keyword options.
+		# @parameter predicate [Object] The predicate to match against the options.
+		# @returns [Receive] Returns self for method chaining.
 		def with_options(predicate)
 			@options = WithOptions.new(predicate)
 			return self
 		end
 		
+		# Specify that the method should be called with a block.
+		# @parameter predicate [Object] Optional predicate to match against the block.
+		# @returns [Receive] Returns self for method chaining.
 		def with_block(predicate = Be.new(:!=, nil))
 			@block = WithBlock.new(predicate)
 			return self
 		end
 		
+		# Specify that the method should be called with specific arguments and options.
+		# @parameter arguments [Array] The positional arguments to match.
+		# @parameter options [Hash] The keyword arguments to match.
+		# @returns [Receive] Returns self for method chaining.
 		def with(*arguments, **options)
 			with_arguments(Be.new(:==, arguments)) if arguments.any?
 			with_options(Be.new(:==, options)) if options.any?
 			return self
 		end
 		
+		# Specify that the method should be called exactly once.
+		# @returns [Receive] Returns self for method chaining.
 		def once
 			@times = Times.new(Be.new(:==, 1))
 			return self
 		end
 		
+		# Specify that the method should be called exactly twice.
+		# @returns [Receive] Returns self for method chaining.
 		def twice
 			@times = Times.new(Be.new(:==, 2))
 			return self
 		end
 		
+		# Specify a predicate to match against the call count.
+		# @parameter predicate [Object] The predicate to match against the call count.
+		# @returns [Receive] Returns self for method chaining.
 		def with_call_count(predicate)
 			@times = Times.new(predicate)
 			return self
 		end
 		
+		# Specify the value to return when the method is called.
+		# @parameter returning [Array] Values to return. If one value, returns it directly; if multiple, returns an array.
+		# @yields {...} Optional block that computes the return value.
+		# @returns [Receive] Returns self for method chaining.
+		# @raises [ArgumentError] If both values and a block are provided.
 		def and_return(*returning, &block)
 			if block_given?
 				if returning.any?
@@ -75,6 +107,9 @@ module Sus
 			return self
 		end
 		
+		# Specify that the method should raise an exception when called.
+		# @parameter exception [Class, String] The exception class or message to raise.
+		# @returns [Receive] Returns self for method chaining.
 		def and_raise(...)
 			@returning = proc do
 				raise(...)
@@ -83,6 +118,12 @@ module Sus
 			return self
 		end
 		
+		# Validate the method call arguments, options, and block.
+		# @parameter mock [Mock] The mock instance.
+		# @parameter assertions [Assertions] The assertions instance.
+		# @parameter arguments [Array] The positional arguments.
+		# @parameter options [Hash] The keyword arguments.
+		# @parameter block [Proc, nil] The block argument.
 		def validate(mock, assertions, arguments, options, block)
 			return unless @arguments or @options or @block
 			
@@ -93,6 +134,9 @@ module Sus
 			end
 		end
 		
+		# Evaluate this expectation against a subject.
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Object] The object to expect the method call on.
 		def call(assertions, subject)
 			assertions.nested(self) do |assertions|
 				mock = @base.mock(subject)
@@ -123,19 +167,28 @@ module Sus
 			end
 		end
 		
+		# @returns [Boolean] Whether the original method should be called.
 		def call_original?
 			@returning.nil?
 		end
 		
+		# Represents a constraint on method call arguments.
 		class WithArguments
+			# Initialize a new WithArguments constraint.
+			# @parameter predicate [Object] The predicate to match against arguments.
 			def initialize(predicate)
 				@predicate = predicate
 			end
 			
+			# Print a representation of this constraint.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("with arguments ", @predicate)
 			end
 			
+			# Evaluate this constraint against arguments.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Array] The arguments to check.
 			def call(assertions, subject)
 				assertions.nested(self) do |assertions|
 					Expect.new(assertions, subject).to(@predicate)
@@ -143,15 +196,23 @@ module Sus
 			end
 		end
 		
+		# Represents a constraint on method call keyword options.
 		class WithOptions
+			# Initialize a new WithOptions constraint.
+			# @parameter predicate [Object] The predicate to match against options.
 			def initialize(predicate)
 				@predicate = predicate
 			end
 			
+			# Print a representation of this constraint.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("with options ", @predicate)
 			end
 			
+			# Evaluate this constraint against options.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Hash] The options to check.
 			def call(assertions, subject)
 				assertions.nested(self) do |assertions|
 					Expect.new(assertions, subject).to(@predicate)
@@ -159,15 +220,23 @@ module Sus
 			end
 		end
 		
+		# Represents a constraint on method call block argument.
 		class WithBlock
+			# Initialize a new WithBlock constraint.
+			# @parameter predicate [Object] The predicate to match against the block.
 			def initialize(predicate)
 				@predicate = predicate
 			end
 			
+			# Print a representation of this constraint.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("with block", @predicate)
 			end
 			
+			# Evaluate this constraint against a block.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Proc, nil] The block to check.
 			def call(assertions, subject)
 				assertions.nested(self) do |assertions|
 					
@@ -176,17 +245,26 @@ module Sus
 			end
 		end
 		
+		# Represents a constraint on method call count.
 		class Times
-			ONCE = Be.new(:==, 1)
+			# A predicate that matches at least one call.
+			AT_LEAST_ONCE = Be.new(:>=, 1)
 			
-			def initialize(condition = ONCE)
+			# Initialize a new Times constraint.
+			# @parameter condition [Object] The predicate to match against the call count.
+			def initialize(condition = AT_LEAST_ONCE)
 				@condition = condition
 			end
-				
+			
+			# Print a representation of this constraint.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("with call count ", @condition)
 			end
 			
+			# Evaluate this constraint against a call count.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Integer] The call count to check.
 			def call(assertions, subject)
 				assertions.nested(self) do |assertions|
 					Expect.new(assertions, subject).to(@condition)
@@ -196,6 +274,10 @@ module Sus
 	end
 	
 	class Base
+		# Create an expectation that a method will be called.
+		# @parameter method [Symbol] The method name to expect.
+		# @yields {...} Optional block that returns the value to return from the method.
+		# @returns [Receive] A new Receive expectation.
 		def receive(method, &block)
 			Receive.new(self, method, &block)
 		end