sus 0.34.0 → 0.35.0

data/lib/sus/be_within.rb

@@ -4,16 +4,25 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
+	# Represents a predicate that checks if the subject is within a tolerance of a value.
 	class BeWithin
+		# Represents a bounded range check.
 		class Bounded
+			# Initialize a new bounded predicate.
+			# @parameter range [Range] The range to check against.
 			def initialize(range)
 				@range = range
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("be within ", :variable, @range, :reset)
 			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(@range.include?(subject))
@@ -21,26 +30,39 @@ module Sus
 			end
 		end
 		
+		# Initialize a new BeWithin predicate.
+		# @parameter tolerance [Numeric] The tolerance value.
 		def initialize(tolerance)
 			@tolerance = tolerance
 		end
 		
+		# Create a bounded predicate that checks if the subject is within tolerance of a value.
+		# @parameter value [Numeric] The value to check against.
+		# @returns [Bounded] A new Bounded predicate.
 		def of(value)
 			tolerance = @tolerance.abs
 			
 			return Bounded.new(Range.new(value - tolerance, value + tolerance))
 		end
 		
+		# Create a bounded predicate that checks if the subject is within a percentage tolerance of a value.
+		# @parameter value [Numeric] The value to check against.
+		# @returns [Bounded] A new Bounded predicate.
 		def percent_of(value)
 			tolerance = Rational(@tolerance, 100)
 			
 			return Bounded.new(Range.new(value - value * tolerance, value + value * tolerance))
 		end
 		
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("be within ", :variable, @tolerance, :reset)
 		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 < @tolerance, self)
@@ -49,6 +71,9 @@ module Sus
 	end
 	
 	class Base
+		# Create a predicate that checks if the subject is within a tolerance or range.
+		# @parameter value [Numeric, Range] The tolerance value or range to check against.
+		# @returns [BeWithin, BeWithin::Bounded] A BeWithin predicate.
 		def be_within(value)
 			case value
 			when Range

data/lib/sus/clock.rb

@@ -4,17 +4,24 @@
 # Copyright, 2022-2023, by Samuel Williams.
 
 module Sus
+	# Represents a clock for measuring elapsed time during test execution.
 	class Clock
 		include Comparable
 		
+		# Create a new clock and start it immediately.
+		# @returns [Clock] A new started clock.
 		def self.start!
 			self.new.tap(&:start!)
 		end
 		
+		# Initialize a new clock.
+		# @parameter duration [Float] Initial duration in seconds.
 		def initialize(duration = 0.0)
 			@duration = duration
 		end
 		
+		# Get the current elapsed duration.
+		# @returns [Float] The elapsed duration in seconds.
 		def duration
 			if @start_time
 				now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -25,18 +32,27 @@ module Sus
 			return @duration
 		end
 		
+		# Compare this clock's duration with another value.
+		# @parameter other [Numeric] The value to compare against.
+		# @returns [Integer] -1, 0, or 1 depending on comparison result.
 		def <=>(other)
 			duration <=> other.to_f
 		end
 		
+		# Convert the duration to a float.
+		# @returns [Float] The duration in seconds.
 		def to_f
 			duration
 		end
 		
+		# Get the duration in milliseconds.
+		# @returns [Float] The duration in milliseconds.
 		def ms
 			duration * 1000.0
 		end
 		
+		# Get a human-readable string representation of the duration.
+		# @returns [String] A formatted duration string (e.g., "1.5ms", "2.3s").
 		def to_s
 			duration = self.duration
 			
@@ -49,14 +65,19 @@ module Sus
 			end
 		end
 		
+		# Reset the clock to a specific duration.
+		# @parameter duration [Float] The duration to reset to.
 		def reset!(duration = 0.0)
 			@duration = duration
 		end
 		
+		# Start the clock.
 		def start!
 			@start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 		end
 		
+		# Stop the clock and return the final duration.
+		# @returns [Float] The final duration in seconds.
 		def stop!
 			if @start_time
 				now = Process.clock_gettime(Process::CLOCK_MONOTONIC)

data/lib/sus/config.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require_relative "clock"
 require_relative "registry"
 
 module Sus
+	# Represents the configuration for running tests.
 	class Config
+		# The default path to the configuration file.
 		PATH = "config/sus.rb"
 		
+		# Find the configuration file path for the given root directory.
+		# @parameter root [String] The root directory to search in.
+		# @returns [String | Nil] The path to the configuration file if it exists.
 		def self.path(root)
 			path = ::File.join(root, PATH)
 			
@@ -18,6 +23,10 @@ module Sus
 			end
 		end
 		
+		# Load configuration from the given root directory.
+		# @parameter root [String] The root directory to load configuration from.
+		# @parameter arguments [Array] Command line arguments to parse.
+		# @returns [Config] A new Config instance.
 		def self.load(root: Dir.pwd, arguments: ARGV)
 			derived = Class.new(self)
 			
@@ -34,6 +43,10 @@ module Sus
 			return derived.new(root, arguments, **options)
 		end
 		
+		# Initialize a new Config instance.
+		# @parameter root [String] The root directory for the project.
+		# @parameter paths [Array] Optional paths to specific test files.
+		# @parameter verbose [Boolean] Whether to output verbose information.
 		def initialize(root, paths, verbose: false)
 			@root = root
 			@paths = paths
@@ -44,6 +57,8 @@ module Sus
 			self.add_default_load_paths
 		end
 		
+		# Add a directory to the load path.
+		# @parameter path [String] The path to add.
 		def add_load_path(path)
 			path = ::File.expand_path(path, @root)
 			
@@ -52,36 +67,50 @@ module Sus
 			end
 		end
 		
+		# Add default load paths (lib and fixtures).
 		def add_default_load_paths
 			add_load_path("lib")
 			add_load_path("fixtures")
 		end
 		
+		# @attribute [String] The root directory for the project.
 		attr :root
+		
+		# @attribute [Array] Optional paths to specific test files.
 		attr :paths
 		
+		# @returns [Boolean] Whether verbose output is enabled.
 		def verbose?
 			@verbose
 		end
 		
+		# @returns [Boolean] Whether only a partial set of tests is being run.
 		def partial?
 			@paths.any?
 		end
 		
+		# @returns [Output] The output handler to use.
 		def output
 			@output ||= Sus::Output.default
 		end
 		
+		# The default pattern for finding test files.
 		DEFAULT_TEST_PATTERN = "test/**/*.rb"
 		
+		# @returns [Array(String)] Paths to all test files matching the default pattern.
 		def test_paths
 			return Dir.glob(DEFAULT_TEST_PATTERN, base: @root)
 		end
 		
+		# Create a new registry instance.
+		# @returns [Registry] A new Registry instance.
 		def make_registry
 			Sus::Registry.new(root: @root)
 		end
 		
+		# Load the test registry, optionally filtering by paths.
+		# @parameter paths [Array | Nil] Optional paths to filter tests by.
+		# @returns [Registry, Filter] The loaded registry, possibly wrapped in a Filter.
 		def load_registry(paths = @paths)
 			registry = make_registry
 			
@@ -99,14 +128,19 @@ module Sus
 			return registry
 		end
 		
+		# @returns [Registry] The test registry, loading it if necessary.
 		def registry
 			@registry ||= self.load_registry
 		end
 		
+		# Prepare Ruby warnings for deprecated features.
 		def prepare_warnings!
 			Warning[:deprecated] = true
 		end
 		
+		# Called before tests are run.
+		# @parameter assertions [Assertions] The assertions instance.
+		# @parameter output [Output] The output handler.
 		def before_tests(assertions, output: self.output)
 			@clock.reset!
 			@clock.start!
@@ -114,6 +148,9 @@ module Sus
 			prepare_warnings!
 		end
 		
+		# Called after tests are run.
+		# @parameter assertions [Assertions] The assertions instance.
+		# @parameter output [Output] The output handler.
 		def after_tests(assertions, output: self.output)
 			@clock.stop!
 			
@@ -122,6 +159,9 @@ module Sus
 		
 		protected
 		
+		# Print a summary of test results.
+		# @parameter output [Output] The output handler.
+		# @parameter assertions [Assertions] The assertions instance.
 		def print_summary(output, assertions)
 			assertions.print(output)
 			output.puts
@@ -136,6 +176,9 @@ module Sus
 			print_failed_assertions(output, assertions)
 		end
 		
+		# Print finished statistics.
+		# @parameter output [Output] The output handler.
+		# @parameter assertions [Assertions] The assertions instance.
 		def print_finished_statistics(output, assertions)
 			duration = @clock.duration
 			rate = assertions.count / duration
@@ -143,6 +186,9 @@ module Sus
 			output.puts "🏁 Finished in ", @clock, "; #{rate.round(3)} assertions per second."
 		end
 		
+		# Print feedback about the test suite.
+		# @parameter output [Output] The output handler.
+		# @parameter assertions [Assertions] The assertions instance.
 		def print_test_feedback(output, assertions)
 			duration = @clock.duration
 			rate = assertions.count / duration
@@ -188,6 +234,10 @@ module Sus
 			end
 		end
 		
+		# Print information about slow tests.
+		# @parameter output [Output] The output handler.
+		# @parameter assertions [Assertions] The assertions instance.
+		# @parameter threshold [Float] The threshold in seconds for considering a test slow.
 		def print_slow_tests(output, assertions, threshold = 0.1)
 			slowest_tests = assertions.passed.select{|test| test.clock > threshold}.sort_by(&:clock).reverse!
 			
@@ -202,6 +252,10 @@ module Sus
 			end
 		end
 		
+		# Print a list of assertions.
+		# @parameter output [Output] The output handler.
+		# @parameter title [String] The title to print.
+		# @parameter assertions [Array] The assertions to print.
 		def print_assertions(output, title, assertions)
 			if assertions.any?
 				output.puts
@@ -213,6 +267,9 @@ module Sus
 			end
 		end
 		
+		# Print failed and errored assertions.
+		# @parameter output [Output] The output handler.
+		# @parameter assertions [Assertions] The assertions instance.
 		def print_failed_assertions(output, assertions)
 			print_assertions(output, "🤔 Failed assertions:", assertions.failed)
 			print_assertions(output, "🔥 Errored assertions:", assertions.errored)

data/lib/sus/context.rb

@@ -7,24 +7,36 @@ require_relative "assertions"
 require_relative "identity"
 
 module Sus
+	# Represents a test context that can contain nested tests and other contexts.
 	module Context
+		# @attribute [Identity, nil] The identity of this context.
 		attr_accessor :identity
+		
+		# @attribute [String, nil] The description of this context.
 		attr_accessor :description
+		
+		# @attribute [Hash] The child contexts and tests.
 		attr_accessor :children
 		
+		# Called when this module is extended.
+		# @parameter base [Class] The class being extended.
 		def self.extended(base)
 			base.children = Hash.new
 		end
 		
 		unless respond_to?(:set_temporary_name)
+			# Set a temporary name for this context.
+			# @parameter name [String] The temporary name.
 			def set_temporary_name(name)
 				# No-op.
 			end
 			
+			# @returns [String] A string representation of this context.
 			def to_s
 				(self.description || self.name).to_s
 			end
 			
+			# @returns [String] An inspect representation of this context.
 			def inspect
 				if description = self.description
 					"\#<#{self.name || "Context"} #{self.description}>"
@@ -34,28 +46,37 @@ module Sus
 			end
 		end
 		
+		# Add a child context or test to this context.
+		# @parameter child [Object] The child to add.
 		def add(child)
 			@children[child.identity] = child
 		end
 		
+		# @returns [Boolean] Whether this context has no children.
 		def empty?
 			@children.nil? || @children.empty?
 		end
 		
+		# @returns [Boolean] Always returns false, as contexts are not leaf nodes.
 		def leaf?
 			false
 		end
 		
+		# Print a representation of this context.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("context ", :context, self.description, :reset)
 		end
 		
+		# @returns [String] The full name of this context.
 		def full_name
 			output = Output::Buffered.new
 			print(output)
 			return output.string
 		end
 		
+		# Execute all child contexts and tests.
+		# @parameter assertions [Assertions] The assertions instance to use.
 		def call(assertions)
 			return if self.empty?
 			
@@ -66,6 +87,8 @@ module Sus
 			end
 		end
 		
+		# Iterate over all leaf nodes (test cases) in this context.
+		# @yields {|test| ...} Each test case.
 		def each(&block)
 			self.children.each do |identity, child|
 				if child.leaf?
@@ -76,11 +99,11 @@ module Sus
 			end
 		end
 		
-		# Include an around method to the context class, that invokes the given block before running the test.
+		# Include a before hook to the context class, that invokes the given block before running each test.
 		#
 		# Before hooks are usually invoked in the order they are defined, i.e. the first defined hook is invoked first.
 		#
-		# @parameter hook [Proc] The block to execute before each test.
+		# @yields {...} The block to execute before each test.
 		def before(&hook)
 			wrapper = Module.new
 			
@@ -93,11 +116,11 @@ module Sus
 			self.include(wrapper)
 		end
 		
-		# Include an around method to the context class, that invokes the given block after running the test.
+		# Include an after hook to the context class, that invokes the given block after running each test.
 		#
 		# After hooks are usually invoked in the reverse order they are defined, i.e. the last defined hook is invoked first.
 		#
-		# @parameter hook [Proc] The block to execute after each test. An `error` argument is passed if the test failed with an exception.
+		# @yields {|error| ...} The block to execute after each test. An `error` argument is passed if the test failed with an exception.
 		def after(&hook)
 			wrapper = Module.new
 			
@@ -118,7 +141,7 @@ module Sus
 		#
 		# The top level `around` implementation invokes before and after hooks.
 		#
-		# @paremeter block [Proc] The block to execute around each test.
+		# @yields {|&block| ...} The block to execute around each test.
 		def around(&block)
 			wrapper = Module.new
 			

data/lib/sus/describe.rb

@@ -6,11 +6,19 @@
 require_relative "context"
 
 module Sus
+	# Represents a test group that describes a subject (class, module, or feature).
 	module Describe
 		extend Context
 		
+		# @attribute [Object] The subject being described.
 		attr_accessor :subject
 		
+		# Build a new describe block class.
+		# @parameter parent [Class] The parent context class.
+		# @parameter subject [Object] The subject to describe.
+		# @parameter unique [Boolean] Whether the identity should be unique.
+		# @yields {...} Optional block containing nested tests.
+		# @returns [Class] A new describe block class.
 		def self.build(parent, subject, unique: true, &block)
 			base = Class.new(parent)
 			base.singleton_class.prepend(Describe)
@@ -29,6 +37,8 @@ module Sus
 			return base
 		end
 		
+		# Print a representation of this describe block.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write(
 				"describe ", :describe, self.description, :reset,
@@ -38,6 +48,10 @@ module Sus
 	end
 	
 	module Context
+		# Define a new test group describing a subject.
+		# @parameter subject [Object] The subject to describe (class, module, or feature).
+		# @parameter options [Hash] Additional options.
+		# @yields {...} Optional block containing nested tests.
 		def describe(subject, **options, &block)
 			add Describe.build(self, subject, **options, &block)
 		end

data/lib/sus/expect.rb

@@ -4,7 +4,13 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
+	# Represents an expectation that can be used with predicates to make assertions.
 	class Expect
+		# Initialize a new Expect instance.
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Object] The subject to make expectations about.
+		# @parameter inverted [Boolean] Whether the expectation is inverted (not).
+		# @parameter distinct [Boolean] Whether this expectation should be treated as distinct.
 		def initialize(assertions, subject, inverted: false, distinct: false)
 			@assertions = assertions
 			@subject = subject
@@ -16,15 +22,22 @@ module Sus
 			@distinct = true
 		end
 		
+		# @attribute [Object] The subject being tested.
 		attr :subject
+		
+		# @attribute [Boolean] Whether the expectation is inverted.
 		attr :inverted
 		
+		# Invert this expectation (expect not).
+		# @returns [Expect] A new Expect instance with inverted expectation.
 		def not
 			self.dup.tap do |expect|
 				expect.instance_variable_set(:@inverted, !@inverted)
 			end
 		end
 		
+		# Print a representation of this expectation.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("expect ", :variable, @inspect, :reset, " ")
 			
@@ -35,6 +48,9 @@ module Sus
 			end
 		end
 		
+		# Apply a predicate to this expectation.
+		# @parameter predicate [Object] The predicate to apply.
+		# @returns [Expect] Returns self for method chaining.
 		def to(predicate)
 			# This gets the identity scoped to the current call stack, which ensures that any failures are logged at this point in the code.
 			identity = @assertions.identity&.scoped
@@ -46,12 +62,19 @@ module Sus
 			return self
 		end
 		
+		# Apply another predicate to this expectation (alias for {#to}).
+		# @parameter predicate [Object] The predicate to apply.
+		# @returns [Expect] Returns self for method chaining.
 		def and(predicate)
 			return to(predicate)
 		end
 	end
 	
 	class Base
+		# Create an expectation about a subject or block.
+		# @parameter subject [Object, nil] The subject to make expectations about.
+		# @yields {...} Optional block to make expectations about.
+		# @returns [Expect] A new Expect instance.
 		def expect(subject = nil, &block)
 			if block_given?
 				Expect.new(@__assertions__, block, distinct: true)

data/lib/sus/file.rb

@@ -11,7 +11,10 @@ Sus::TOPLEVEL_CLASS_EVAL = ->(__klass__, __path__){__klass__.class_eval(::File.r
 
 # This is a hack to allow us to get the line number of a syntax error.
 unless SyntaxError.method_defined?(:lineno)
+	# Extension to SyntaxError to extract line numbers from error messages.
 	class SyntaxError
+		# Extract the line number from the error message.
+		# @returns [Integer, nil] The line number if found in the message.
 		def lineno
 			if message =~ /:(\d+):/
 				$1.to_i
@@ -21,17 +24,27 @@ unless SyntaxError.method_defined?(:lineno)
 end
 
 module Sus
+	# Represents a test file that can be loaded and executed.
 	module File
 		extend Context
 		
+		# Load a test file.
+		# @parameter path [String] The path to the test file.
+		# @returns [Class] A test class representing the file.
 		def self.[] path
 			self.build(Sus.base, path)
 		end
 		
+		# Called when this module is extended.
+		# @parameter base [Class] The class being extended.
 		def self.extended(base)
 			base.children = Hash.new
 		end
 		
+		# Build a test class from a file path.
+		# @parameter parent [Class] The parent context class.
+		# @parameter path [String] The path to the test file.
+		# @returns [Class] A test class representing the file.
 		def self.build(parent, path)
 			base = Class.new(parent)
 			
@@ -50,12 +63,20 @@ module Sus
 			return base
 		end
 		
+		# Print a representation of this file context.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("file ", :path, self.identity, :reset)
 		end
 	end
 	
+	# Represents an error that occurred while loading a test file.
 	class FileLoadError
+		# Build a new FileLoadError.
+		# @parameter parent [Object] The parent context.
+		# @parameter path [String] The path to the file that failed to load.
+		# @parameter error [Exception] The error that occurred.
+		# @returns [FileLoadError] A new FileLoadError instance.
 		def self.build(parent, path, error)
 			identity = Identity.file(parent.identity, path)
 			
@@ -69,33 +90,48 @@ module Sus
 			self.new(identity, path, error)
 		end
 		
+		# Initialize a new FileLoadError.
+		# @parameter identity [Identity] The identity where the error occurred.
+		# @parameter path [String] The path to the file.
+		# @parameter error [Exception] The error that occurred.
 		def initialize(identity, path, error)
 			@identity = identity
 			@path = path
 			@error = error
 		end
 		
+		# @attribute [Identity] The identity where the error occurred.
 		attr :identity
+		
+		# @attribute [Exception] The error that occurred.
 		attr :error
 		
+		# @returns [Boolean] Always returns true, as errors are leaf nodes.
 		def leaf?
 			true
 		end
 		
+		# An empty hash used for children.
 		EMPTY = Hash.new.freeze
 		
+		# @returns [Hash] Always returns an empty hash.
 		def children
 			EMPTY
 		end
 		
+		# @returns [String] The file path.
 		def description
 			@path
 		end
 		
+		# Print a representation of this error.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("file ", :path, @identity)
 		end
 		
+		# Execute this error, recording it in assertions.
+		# @parameter assertions [Assertions] The assertions instance.
 		def call(assertions)
 			assertions.nested(self, identity: @identity, isolated: true) do |assertions|
 				assertions.error!(@error)
@@ -106,6 +142,8 @@ module Sus
 	private_constant :FileLoadError
 	
 	module Context
+		# Load a test file as a child context.
+		# @parameter path [String] The path to the test file.
 		def file(path)
 			add File.build(self, path)
 		end