sus 0.34.0 → 0.35.0

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
+			# A predicate that matches at least one call.
 			AT_LEAST_ONCE = Be.new(:>=, 1)
 			
+			# 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

data/lib/sus/registry.rb

@@ -19,25 +19,34 @@ require_relative "include_context"
 require_relative "let"
 
 module Sus
+	# Represents a registry of test files and contexts.
 	class Registry
+		# The glob pattern used to find Ruby files in directories.
 		DIRECTORY_GLOB = "**/*.rb"
 		
-		# Create a top level scope with self as the instance:
+		# Initialize a new registry.
+		# @parameter options [Hash] Options to pass to the base context.
 		def initialize(**options)
 			@base = Sus.base(self, **options)
 			@loaded = {}
 		end
 		
+		# @attribute [Class] The base test context class.
 		attr :base
 		
+		# Print a representation of this registry.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("Test Registry")
 		end
 		
+		# @returns [String] A string representation of this registry.
 		def to_s
 			@base&.identity&.to_s || self.class.name
 		end
 		
+		# Load a test file or directory.
+		# @parameter path [String] The path to load (file or directory).
 		def load(path)
 			if ::File.directory?(path)
 				load_directory(path)
@@ -46,24 +55,34 @@ module Sus
 			end
 		end
 		
+		# Load a single test file.
+		# @parameter path [String] The path to the test file.
 		private def load_file(path)
 			@loaded[path] ||= @base.file(path)
 		end
 		
+		# Load all Ruby files in a directory.
+		# @parameter path [String] The directory path.
 		private def load_directory(path)
 			::Dir.glob(::File.join(path, DIRECTORY_GLOB), &self.method(:load_file))
 		end
 		
+		# Execute all tests in the registry.
+		# @parameter assertions [Assertions] Optional assertions instance to use.
+		# @returns [Assertions] The assertions instance with results.
 		def call(assertions = Assertions.default)
 			@base.call(assertions)
 			
 			return assertions
 		end
 		
+		# Iterate over all test cases in the registry.
+		# @yields {|test| ...} Each test case.
 		def each(...)
 			@base.each(...)
 		end
 		
+		# @returns [Hash] The child contexts and tests.
 		def children
 			@base.children
 		end