sus 0.34.0 → 0.35.0

data/lib/sus/assertions.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "output"
 require_relative "clock"
@@ -9,13 +9,25 @@ require_relative "clock"
 require_relative "output/backtrace"
 
 module Sus
+	# Represents a collection of test assertions and their results. Tracks passed, failed, skipped, and errored assertions.
 	class Assertions
+		# Create a new assertions instance with default options.
+		# @parameter options [Hash] Options to pass to {#initialize}.
+		# @returns [Assertions] A new assertions instance.
 		def self.default(**options)
 			self.new(**options)
 		end
 		
-		# @parameter orientation [Boolean] Whether the assertions are positive or negative in general.
+		# Initialize a new assertions instance.
+		# @parameter identity [Identity, nil] The identity used to identify this set of assertions.
+		# @parameter target [Object, nil] The specific target of the assertions, e.g. the test case or nested test assertions.
+		# @parameter output [Output] The output buffer used to capture output from the assertions.
 		# @parameter inverted [Boolean] Whether the assertions are inverted with respect to the parent.
+		# @parameter orientation [Boolean] Whether the assertions are positive or negative in general.
+		# @parameter isolated [Boolean] Whether this set of assertions is isolated from the parent.
+		# @parameter distinct [Boolean] Whether this set of assertions should be treated as a single statement.
+		# @parameter measure [Boolean] Whether to measure execution time.
+		# @parameter verbose [Boolean] Whether to output verbose information.
 		def initialize(identity: nil, target: nil, output: Output.buffered, inverted: false, orientation: true, isolated: false, distinct: false, measure: false, verbose: false)
 			# In theory, the target could carry the identity of the assertion group, but it's not really necessary, so we just handle it explicitly and pass it into any nested assertions.
 			@identity = identity
@@ -42,53 +54,60 @@ module Sus
 			@count = 0
 		end
 		
-		# The identity that is used to identify this set of assertions.
+		# @attribute [Identity, nil] The identity that is used to identify this set of assertions.
 		attr :identity
 		
-		# The specific target of the assertions, e.g. the test case or nested test assertions.
+		# @attribute [Object, nil] The specific target of the assertions, e.g. the test case or nested test assertions.
 		attr :target
 		
-		# The output buffer used to capture output from the assertions.
+		# @attribute [Output] The output buffer used to capture output from the assertions.
 		attr :output
 		
-		# The nesting level of this set of assertions.
+		# @attribute [Integer, nil] The nesting level of this set of assertions.
 		attr :level
 		
-		# Whether this aset of assertions is inverted, i.e. the assertions are expected to fail relative to the parent. Used for grouping assertions and ensuring they are added to the parent passed/failed array correctly.
+		# @attribute [Boolean] Whether this set of assertions is inverted, i.e. the assertions are expected to fail relative to the parent. Used for grouping assertions and ensuring they are added to the parent passed/failed array correctly.
 		attr :inverted
 		
-		# The absolute orientation of this set of assertions, i.e. whether the assertions are expected to pass or fail regardless of the parent. Used for correctly formatting the output.
+		# @attribute [Boolean] The absolute orientation of this set of assertions, i.e. whether the assertions are expected to pass or fail regardless of the parent. Used for correctly formatting the output.
 		attr :orientation
 		
-		# Whether this set of assertions is isolated from the parent. This is used to ensure that any deferred assertions are competed before the parent is completed. This is used by `receive` assertions which are deferred until the user code of the test has completed.
+		# @attribute [Boolean] Whether this set of assertions is isolated from the parent. This is used to ensure that any deferred assertions are completed before the parent is completed. This is used by `receive` assertions which are deferred until the user code of the test has completed.
 		attr :isolated
 		
-		# Distinct is used to identify a set of assertions as a single statement for the purpose of user feedback. It's used by top level ensure statements to ensure that error messages are captured and reported on those statements.
+		# @attribute [Boolean] Distinct is used to identify a set of assertions as a single statement for the purpose of user feedback. It's used by top level ensure statements to ensure that error messages are captured and reported on those statements.
 		attr :distinct
 		
+		# @attribute [Boolean] Whether to output verbose information.
 		attr :verbose
 		
+		# @attribute [Clock, nil] The clock used to measure execution time, if measurement is enabled.
 		attr :clock
 		
-		# Nested assertions that have passed.
+		# @attribute [Array] Nested assertions that have passed.
 		attr :passed
 		
-		# Nested assertions that have failed.
+		# @attribute [Array] Nested assertions that have failed.
 		attr :failed
 		
-		# Nested assertions have been deferred.
+		# @attribute [Array] Nested assertions that have been deferred.
 		attr :deferred
 		
+		# @attribute [Array] Nested assertions that have been skipped.
 		attr :skipped
+		
+		# @attribute [Array] Nested assertions that have errored.
 		attr :errored
 		
-		# The total number of assertions performed:
+		# @attribute [Integer] The total number of assertions performed.
 		attr :count
 		
+		# @returns [String] A string representation of the assertions instance.
 		def inspect
 			"\#<#{self.class} #{@passed.size} passed #{@failed.size} failed #{@deferred.size} deferred #{@skipped.size} skipped #{@errored.size} errored>"
 		end
 		
+		# @returns [Hash] A hash containing the output text and location of the assertions.
 		def message
 			{
 				text: @output.string,
@@ -96,10 +115,14 @@ module Sus
 			}
 		end
 		
+		# @returns [Integer] The total number of assertions (passed, failed, deferred, skipped, and errored).
 		def total
 			@passed.size + @failed.size + @deferred.size + @skipped.size + @errored.size
 		end
 		
+		# Print a summary of the assertions to the output.
+		# @parameter output [Output] The output target.
+		# @parameter verbose [Boolean] Whether to include verbose information.
 		def print(output, verbose: @verbose)
 			if verbose && @target
 				@target.print(output)
@@ -133,14 +156,18 @@ module Sus
 			end
 		end
 		
+		# Print a message to the output buffer.
+		# @parameter message [Array] The message parts to print.
 		def puts(*message)
 			@output.puts(:indent, *message)
 		end
 		
+		# @returns [Boolean] Whether there are no assertions (passed, failed, deferred, skipped, or errored).
 		def empty?
 			@passed.empty? and @failed.empty? and @deferred.empty? and @skipped.empty? and @errored.empty?
 		end
 		
+		# @returns [Boolean] Whether all assertions passed and none errored.
 		def passed?
 			if @inverted
 				# Inverted assertions:
@@ -151,29 +178,43 @@ module Sus
 			end
 		end
 		
+		# @returns [Boolean] Whether any assertions failed or errored.
 		def failed?
 			!self.passed?
 		end
 		
+		# @returns [Boolean] Whether any assertions errored.
 		def errored?
 			@errored.any?
 		end
 		
+		# Represents a single assertion result.
 		class Assert
+			# Initialize a new assertion result.
+			# @parameter identity [Identity, nil] The identity of the assertion.
+			# @parameter backtrace [Array] The backtrace where the assertion was made.
+			# @parameter assertions [Assertions] The assertions instance that contains this assertion.
 			def initialize(identity, backtrace, assertions)
 				@identity = identity
 				@backtrace = backtrace
 				@assertions = assertions
 			end
 			
+			# @attribute [Identity, nil] The identity of the assertion.
 			attr :identity
+			
+			# @attribute [Array] The backtrace where the assertion was made.
 			attr :backtrace
+			
+			# @attribute [Assertions] The assertions instance that contains this assertion.
 			attr :assertions
 			
+			# @yields {|assert| ...} Yields this assertion as a failure.
 			def each_failure(&block)
 				yield self
 			end
 			
+			# @returns [Hash] A hash containing the output text and location of the assertion.
 			def message
 				{
 					# It's possible that several Assert instances might share the same output text. This is because the output is buffered for each test and each top-level test expectation.
@@ -183,6 +224,9 @@ module Sus
 			end
 		end
 		
+		# Make an assertion about a condition.
+		# @parameter condition [Boolean] The condition to assert.
+		# @parameter message [String | Nil] Optional message describing the assertion.
 		def assert(condition, message = nil)
 			@count += 1
 			
@@ -199,6 +243,9 @@ module Sus
 			end
 		end
 		
+		# Iterate over all failures in this assertions instance.
+		# @yields {|failure| ...} Each failure (failed assertion or error).
+		# @returns [Enumerator] An enumerator if no block is given.
 		def each_failure(&block)
 			return to_enum(__method__) unless block_given?
 			
@@ -215,12 +262,16 @@ module Sus
 			end
 		end
 		
+		# Skip this set of assertions with a reason.
+		# @parameter reason [String] The reason for skipping.
 		def skip(reason)
 			@output.skip(reason, @identity&.scoped)
 			
 			@skipped << self
 		end
 		
+		# Print an informational message during test execution.
+		# @parameter message [String | Nil] The message to print, or a block that returns a message.
 		def inform(message = nil)
 			if message.nil? and block_given?
 				begin
@@ -233,17 +284,18 @@ module Sus
 			@output.inform(message, @identity&.scoped)
 		end
 		
-		# Add deferred assertions.
+		# Add a deferred assertion that will be resolved later.
+		# @yields {|assertions| ...} The block that will be called to resolve the deferred assertion.
 		def defer(&block)
 			@deferred << block
 		end
 		
-		# Whether there are any deferred assertions.
+		# @returns [Boolean] Whether there are any deferred assertions.
 		def deferred?
 			@deferred.any?
 		end
 		
-		# This resolves all deferred assertions in order.
+		# Resolve all deferred assertions in order.
 		def resolve!
 			@output.indented do
 				while block = @deferred.shift
@@ -252,19 +304,28 @@ module Sus
 			end
 		end
 		
+		# Represents an error that occurred during test execution.
 		class Error
+			# Initialize a new error result.
+			# @parameter identity [Identity, nil] The identity where the error occurred.
+			# @parameter error [Exception] The exception that was raised.
 			def initialize(identity, error)
 				@identity = identity
 				@error = error
 			end
 			
+			# @attribute [Identity, nil] The identity where the error occurred.
 			attr :identity
+			
+			# @attribute [Exception] The exception that was raised.
 			attr :error
 			
+			# @yields {|error| ...} Yields this error as a failure.
 			def each_failure(&block)
 				yield self
 			end
 			
+			# @returns [Hash] A hash containing the error message and location.
 			def message
 				{
 					text: @error.full_message,
@@ -273,6 +334,8 @@ module Sus
 			end
 		end
 		
+		# Record an error that occurred during test execution.
+		# @parameter error [Exception] The exception that was raised.
 		def error!(error)
 			identity = @identity&.scoped(error.backtrace_locations)
 			
@@ -282,6 +345,15 @@ module Sus
 			@output.error(error, @identity)
 		end
 		
+		# Create a nested set of assertions.
+		# @parameter target [Object] The target object for the nested assertions.
+		# @parameter identity [Identity, nil] The identity for the nested assertions.
+		# @parameter isolated [Boolean] Whether the nested assertions are isolated from the parent.
+		# @parameter distinct [Boolean] Whether the nested assertions should be treated as a single statement.
+		# @parameter inverted [Boolean] Whether the nested assertions are inverted.
+		# @parameter options [Hash] Additional options to pass to the nested assertions instance.
+		# @yields {|assertions| ...} The nested assertions instance.
+		# @returns [Object] The result of the block.
 		def nested(target, identity: @identity, isolated: false, distinct: false, inverted: false, **options)
 			result = nil
 			
@@ -317,7 +389,8 @@ module Sus
 			return result
 		end
 		
-		# Add the child assertions which were nested to this instance.
+		# Add child assertions that were nested to this instance.
+		# @parameter assertions [Assertions] The child assertions to add.
 		def add(assertions)
 			# All child assertions should be resolved by this point:
 			raise "Nested assertions must be fully resolved!" if assertions.deferred?

data/lib/sus/base.rb

@@ -6,12 +6,15 @@
 require_relative "context"
 
 module Sus
-	# The base test case class. We need to be careful about what local state is stored.
+	# Represents the base test case class. Provides core functionality for test execution including hooks for setup and teardown.
 	class Base
+		# Initialize a new test case instance.
+		# @parameter assertions [Assertions] The assertions instance used to track test results.
 		def initialize(assertions)
 			@__assertions__ = assertions
 		end
 		
+		# @returns [String] A string representation of the test case.
 		def inspect
 			"\#<Sus::Base for #{self.class.description.inspect}>"
 		end
@@ -43,15 +46,24 @@ module Sus
 			self.after(error)
 		end
 		
+		# Make an assertion about a condition.
+		# @parameter condition [Boolean] The condition to assert.
+		# @parameter message [String | Nil] Optional message describing the assertion.
 		def assert(...)
 			@__assertions__.assert(...)
 		end
 		
+		# Print an informational message during test execution.
+		# @parameter message [String | Nil] The message to print, or a block that returns a message.
 		def inform(...)
 			@__assertions__.inform(...)
 		end
 	end
 	
+	# Create a new base test class with the given description.
+	# @parameter description [String | Nil] Optional description for the test class.
+	# @parameter root [String | Nil] Optional root path for the test identity.
+	# @returns [Class] A new test class that extends {Base}.
 	def self.base(description = nil, root: nil)
 		base = Class.new(Base)
 		

data/lib/sus/be.rb

@@ -4,12 +4,18 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
+	# Represents a predicate matcher that can be used with `expect(...).to be(...)`.
 	class Be
+		# Represents a logical AND combination of multiple predicates.
 		class And
+			# Initialize a new AND predicate.
+			# @parameter predicates [Array] The predicates to combine with AND logic.
 			def initialize(predicates)
 				@predicates = predicates
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				@predicates.each_with_index do |predicate, index|
 					if index > 0
@@ -20,26 +26,40 @@ module Sus
 				end
 			end
 			
+			# Evaluate this predicate against a subject.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Object] The subject to evaluate.
 			def call(assertions, subject)
 				@predicates.each do |predicate|
 					predicate.call(assertions, subject)
 				end
 			end
 			
+			# Combine this predicate with another using AND logic.
+			# @parameter other [Object] Another predicate to combine.
+			# @returns [And] A new AND predicate.
 			def &(other)
 				And.new(@predicates + [other])
 			end
 			
+			# Combine this predicate with another using OR logic.
+			# @parameter other [Object] Another predicate to combine.
+			# @returns [Or] A new OR predicate.
 			def |(other)
 				Or.new(self, other)
 			end
 		end
 		
+		# Represents a logical OR combination of multiple predicates.
 		class Or
+			# Initialize a new OR predicate.
+			# @parameter predicates [Array] The predicates to combine with OR logic.
 			def initialize(predicates)
 				@predicates = predicates
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				@predicates.each_with_index do |predicate, index|
 					if index > 0
@@ -50,6 +70,9 @@ module Sus
 				end
 			end
 			
+			# Evaluate this predicate against a subject.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Object] The subject to evaluate.
 			def call(assertions, subject)
 				assertions.nested(self) do |assertions|
 					@predicates.each do |predicate|
@@ -66,35 +89,57 @@ module Sus
 				end
 			end
 			
+			# Combine this predicate with another using AND logic.
+			# @parameter other [Object] Another predicate to combine.
+			# @returns [And] A new AND predicate.
 			def &(other)
 				And.new(self, other)
 			end
 			
+			# Combine this predicate with another using OR logic.
+			# @parameter other [Object] Another predicate to combine.
+			# @returns [Or] A new OR predicate.
 			def |(other)
 				Or.new(@predicates + [other])
 			end
 		end
 		
+		# Initialize a new Be predicate.
+		# @parameter arguments [Array] The method name and arguments to call on the subject.
 		def initialize(*arguments)
 			@arguments = arguments
 		end
 		
+		# Combine this predicate with another using OR logic.
+		# @parameter other [Object] Another predicate to combine.
+		# @returns [Or] A new OR predicate.
 		def |(other)
 			Or.new([self, other])
 		end
 		
+		# Combine this predicate with others using OR logic.
+		# @parameter others [Array] Other predicates to combine.
+		# @returns [Or] A new OR predicate.
 		def or(*others)
 			Or.new([self, *others])
 		end
 		
+		# Combine this predicate with another using AND logic.
+		# @parameter other [Object] Another predicate to combine.
+		# @returns [And] A new AND predicate.
 		def &(other)
 			And.new([self, other])
 		end
 		
+		# Combine this predicate with others using AND logic.
+		# @parameter others [Array] Other predicates to combine.
+		# @returns [And] A new AND predicate.
 		def and(*others)
 			And.new([self, *others])
 		end
 		
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def print(output)
 			operation, *arguments = *@arguments
 			
@@ -105,6 +150,9 @@ module Sus
 			end
 		end
 		
+		# Evaluate this predicate against a subject.
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Object] The subject to evaluate.
 		def call(assertions, subject)
 			assertions.nested(self) do |assertions|
 				assertions.assert(subject.public_send(*@arguments))
@@ -112,43 +160,71 @@ module Sus
 		end
 		
 		class << self
+			# Create a predicate that checks equality.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def == value
 				Be.new(:==, value)
 			end
 			
+			# Create a predicate that checks inequality.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def != value
 				Be.new(:!=, value)
 			end
 			
+			# Create a predicate that checks if the subject is greater than a value.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def > value
 				Be.new(:>, value)
 			end
 			
+			# Create a predicate that checks if the subject is greater than or equal to a value.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def >= value
 				Be.new(:>=, value)
 			end
 			
+			# Create a predicate that checks if the subject is less than a value.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def < value
 				Be.new(:<, value)
 			end
 			
+			# Create a predicate that checks if the subject is less than or equal to a value.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def <= value
 				Be.new(:<=, value)
 			end
 			
+			# Create a predicate that checks if the subject matches a pattern.
+			# @parameter value [Regexp, Object] The pattern to match against.
+			# @returns [Be] A new Be predicate.
 			def =~ value
 				Be.new(:=~, value)
 			end
 			
+			# Create a predicate that checks case equality.
+			# @parameter value [Object] The value to compare against.
+			# @returns [Be] A new Be predicate.
 			def === value
 				Be.new(:===, value)
 			end
 		end
 		
+		# A predicate that checks if the subject is nil.
 		NIL = Be.new(:nil?)
 	end
 	
 	class Base
+		# Create a Be predicate matcher.
+		# @parameter arguments [Array] Optional method name and arguments to call on the subject.
+		# @returns [Be, Class] A Be predicate if arguments are provided, otherwise the Be class.
 		def be(*arguments)
 			if arguments.any?
 				Be.new(*arguments)
@@ -157,14 +233,22 @@ module Sus
 			end
 		end
 		
+		# Create a predicate that checks if the subject is an instance of a class.
+		# @parameter klass [Class] The class to check against.
+		# @returns [Be] A new Be predicate.
 		def be_a(klass)
 			Be.new(:is_a?, klass)
 		end
 		
+		# Create a predicate that checks if the subject is nil.
+		# @returns [Be] A Be predicate that checks for nil.
 		def be_nil
 			Be::NIL
 		end
 		
+		# Create a predicate that checks object identity equality.
+		# @parameter other [Object] The object to compare against.
+		# @returns [Be] A new Be predicate.
 		def be_equal(other)
 			Be.new(:equal?, other)
 		end

data/lib/sus/be_truthy.rb

@@ -4,11 +4,17 @@
 # Copyright, 2022-2023, by Samuel Williams.
 
 module Sus
+	# Represents a predicate that checks if the subject is truthy.
 	module BeTruthy
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def self.print(output)
 			output.write("be truthy")
 		end
 		
+		# Evaluate this predicate against a subject.
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Object] The subject to evaluate.
 		def self.call(assertions, subject)
 			assertions.nested(self) do |assertions|
 				assertions.assert(subject, self)
@@ -16,11 +22,17 @@ module Sus
 		end
 	end
 	
+	# Represents a predicate that checks if the subject is falsey.
 	module BeFalsey
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def self.print(output)
 			output.write("be falsey")
 		end
 		
+		# Evaluate this predicate against a subject.
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Object] The subject to evaluate.
 		def self.call(assertions, subject)
 			assertions.nested(self) do |assertions|
 				assertions.assert(!subject, self)
@@ -29,10 +41,14 @@ module Sus
 	end
 	
 	class Base
+		# Create a predicate that checks if the subject is truthy.
+		# @returns [BeTruthy] A BeTruthy predicate.
 		def be_truthy
 			BeTruthy
 		end
 		
+		# Create a predicate that checks if the subject is falsey.
+		# @returns [BeFalsey] A BeFalsey predicate.
 		def be_falsey
 			BeFalsey
 		end