sus 0.34.0 → 0.35.0

data/lib/sus/filter.rb

@@ -12,13 +12,18 @@ module Sus
 	#
 	# When the filter is used to enumerate the registry, it will only return the tests that match the suffix.
 	class Filter
+		# Represents an index of contexts by their identity keys.
 		class Index
+			# Initialize a new Index.
 			def initialize
 				@contexts = {}
 			end
 			
+			# @attribute [Hash] A hash mapping identity keys to contexts.
 			attr :contexts
 			
+			# Add all children from a parent context to the index.
+			# @parameter parent [Object] The parent context.
 			def add(parent)
 				parent.children&.each do |identity, child|
 					insert(identity, child)
@@ -26,6 +31,10 @@ module Sus
 				end
 			end
 			
+			# Insert a context into the index.
+			# @parameter identity [Identity] The identity of the context.
+			# @parameter context [Object] The context to index.
+			# @raises [KeyError] If a context with the same key already exists.
 			def insert(identity, context)
 				key = identity.key
 				
@@ -36,17 +45,24 @@ module Sus
 				end
 			end
 			
+			# Look up a context by its key.
+			# @parameter key [String] The identity key.
+			# @returns [Object, nil] The context if found.
 			def [] key
 				@contexts[key]
 			end
 		end
 		
+		# Initialize a new Filter.
+		# @parameter registry [Registry] The registry to filter.
 		def initialize(registry = Registry.new)
 			@registry = registry
 			@index = nil
 			@keys = Array.new
 		end
 		
+		# Load a target path, optionally with a filter suffix.
+		# @parameter target [String] The target path, optionally with a ":suffix" filter.
 		def load(target)
 			path, filter = target.split(":", 2)
 			
@@ -57,6 +73,8 @@ module Sus
 			end
 		end
 		
+		# Iterate over filtered test cases.
+		# @yields {|test| ...} Each test case that matches the filter.
 		def each(&block)
 			if @keys.any?
 				@index = Index.new
@@ -72,6 +90,9 @@ module Sus
 			end
 		end
 		
+		# Execute filtered tests.
+		# @parameter assertions [Assertions] Optional assertions instance to use.
+		# @returns [Assertions] The assertions instance with results.
 		def call(assertions = Assertions.default)
 			if @keys.any?
 				@index = Index.new

data/lib/sus/fixtures/temporary_directory_context.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require "tmpdir"
+
+module Sus
+	module Fixtures
+		# Provides a temporary directory context for tests that need isolated file system access.
+		module TemporaryDirectoryContext
+			# Set up a temporary directory before the test and clean it up after.
+			# @yields {|&block| ...} The test block to execute.
+			def around(&block)
+				Dir.mktmpdir do |root|
+					@root = root
+					super(&block)
+					@root = nil
+				end
+			end
+			
+			# @attribute [String] The path to the temporary directory root.
+			attr :root
+		end
+	end
+end
+

data/lib/sus/fixtures.rb

@@ -4,6 +4,7 @@
 # Copyright, 2022, by Samuel Williams.
 
 module Sus
+	# @namespace
 	module Fixtures
 	end
 end

data/lib/sus/have/all.rb

@@ -5,11 +5,16 @@
 
 module Sus
 	module Have
+		# Represents a predicate that checks if the subject matches all of the given predicates.
 		class All
+			# Initialize a new All predicate.
+			# @parameter predicates [Array] The predicates to check.
 			def initialize(predicates)
 				@predicates = predicates
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				first = true
 				output.write("have {")
@@ -25,6 +30,9 @@ module Sus
 				output.write("}")
 			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|

data/lib/sus/have/any.rb

@@ -5,11 +5,16 @@
 
 module Sus
 	module Have
+		# Represents a predicate that checks if the subject matches any of the given predicates.
 		class Any
+			# Initialize a new Any predicate.
+			# @parameter predicates [Array] The predicates to check.
 			def initialize(predicates)
 				@predicates = predicates
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				first = true
 				output.write("have any {")
@@ -25,6 +30,9 @@ module Sus
 				output.write("}")
 			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|

data/lib/sus/have.rb

@@ -7,17 +7,27 @@ require_relative "have/all"
 require_relative "have/any"
 
 module Sus
+	# Represents predicates for checking collections and object attributes.
 	module Have
+		# Represents a predicate that checks if a hash has a specific key.
 		class Key
+			# Initialize a new Key predicate.
+			# @parameter name [Object] The key name to check for.
+			# @parameter predicate [Object, nil] Optional predicate to apply to the key's value.
 			def initialize(name, predicate = nil)
 				@name = name
 				@predicate = predicate
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("key ", :variable, @name.inspect, :reset, " ", @predicate, :reset)
 			end
 			
+			# Evaluate this predicate against a subject.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Object] The subject to evaluate (should be a hash).
 			def call(assertions, subject)
 				# We want to group all the assertions in to a distinct group:
 				assertions.nested(self, distinct: true) do |assertions|
@@ -29,16 +39,25 @@ module Sus
 			end
 		end
 		
+		# Represents a predicate that checks if an object has a specific attribute.
 		class Attribute
+			# Initialize a new Attribute predicate.
+			# @parameter name [Symbol, String] The attribute name to check for.
+			# @parameter predicate [Object] The predicate to apply to the attribute's value.
 			def initialize(name, predicate)
 				@name = name
 				@predicate = predicate
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("attribute ", :variable, @name.to_s, :reset, " ", @predicate, :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, distinct: true) do |assertions|
 					assertions.assert(subject.respond_to?(@name), "has attribute")
@@ -49,15 +68,23 @@ module Sus
 			end
 		end
 		
+		# Represents a predicate that checks if a collection has a value matching a predicate.
 		class Value
+			# Initialize a new Value predicate.
+			# @parameter predicate [Object, nil] The predicate to apply to each value in the collection.
 			def initialize(predicate)
 				@predicate = predicate
 			end
 			
+			# Print a representation of this predicate.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("value ", @predicate, :reset)
 			end
 			
+			# Evaluate this predicate against a subject.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Object] The subject to evaluate (should be enumerable).
 			def call(assertions, subject)
 				index = 0
 				
@@ -73,10 +100,16 @@ module Sus
 	end
 	
 	class Base
+		# Create a predicate that checks if the subject has all of the given predicates.
+		# @parameter predicates [Array] The predicates to check.
+		# @returns [Have::All] A Have::All predicate.
 		def have(*predicates)
 			Have::All.new(predicates)
 		end
 		
+		# Create a predicate that checks if the subject (hash) has the specified keys.
+		# @parameter keys [Array] Keys to check for. Can be symbols/strings or hashes with key-predicate pairs.
+		# @returns [Have::All] A Have::All predicate.
 		def have_keys(*keys)
 			predicates = []
 			
@@ -93,6 +126,9 @@ module Sus
 			Have::All.new(predicates)
 		end
 		
+		# Create a predicate that checks if the subject has the specified attributes with matching values.
+		# @parameter attributes [Hash] A hash of attribute names to predicates.
+		# @returns [Have::All] A Have::All predicate.
 		def have_attributes(**attributes)
 			predicates = attributes.map do |key, value|
 				Have::Attribute.new(key, value)
@@ -101,10 +137,16 @@ module Sus
 			Have::All.new(predicates)
 		end
 		
+		# Create a predicate that checks if the subject matches any of the given predicates.
+		# @parameter predicates [Array] The predicates to check.
+		# @returns [Have::Any] A Have::Any predicate.
 		def have_any(*predicates)
 			Have::Any.new(predicates)
 		end
 		
+		# Create a predicate that checks if the subject (collection) has any value matching the predicate.
+		# @parameter predicate [Object] The predicate to apply to each value.
+		# @returns [Have::Any] A Have::Any predicate.
 		def have_value(predicate)
 			Have::Any.new([Have::Value.new(predicate)])
 		end

data/lib/sus/have_duration.rb

@@ -4,16 +4,24 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
+	# Represents a predicate that measures the duration of a block execution.
 	class HaveDuration
+		# Initialize a new HaveDuration predicate.
+		# @parameter predicate [Object] The predicate to apply to the measured duration.
 		def initialize(predicate)
 			@predicate = predicate
 		end
 		
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("have duration ")
 			@predicate.print(output)
 		end
 		
+		# Evaluate this predicate against a subject (block).
+		# @parameter assertions [Assertions] The assertions instance to use.
+		# @parameter subject [Proc] The block to measure.
 		def call(assertions, subject)
 			assertions.nested(self) do |assertions|
 				Expect.new(assertions, measure(subject)).to(@predicate)
@@ -22,6 +30,9 @@ module Sus
 		
 		private
 		
+		# Measure the duration of executing a block.
+		# @parameter subject [Proc] The block to measure.
+		# @returns [Float] The duration in seconds.
 		def measure(subject)
 			start_time = now
 			
@@ -30,12 +41,17 @@ module Sus
 			return now - start_time
 		end
 		
+		# Get the current monotonic time.
+		# @returns [Float] The current time in seconds.
 		def now
 			::Process.clock_gettime(Process::CLOCK_MONOTONIC)
 		end
 	end
 	
 	class Base
+		# Create a predicate that measures the duration of a block execution.
+		# @parameter predicate [Object] The predicate to apply to the measured duration.
+		# @returns [HaveDuration] A new HaveDuration predicate.
 		def have_duration(...)
 			HaveDuration.new(...)
 		end

data/lib/sus/identity.rb

@@ -4,22 +4,42 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
+	# Represents a unique identity for a test or context, used for identification and location tracking.
 	class Identity
+		# Create an identity for a file.
+		# @parameter parent [Identity, nil] The parent identity.
+		# @parameter path [String] The file path.
+		# @parameter name [String] The name (defaults to path).
+		# @parameter options [Hash] Additional options.
+		# @returns [Identity] A new Identity instance.
 		def self.file(parent, path, name = path, **options)
 			self.new(path, name, nil, nil, **options)
 		end
 		
+		# Create a nested identity.
+		# @parameter parent [Identity, nil] The parent identity.
+		# @parameter name [String] The name of this identity.
+		# @parameter location [Thread::Backtrace::Location, nil] Optional location (defaults to caller location).
+		# @parameter options [Hash] Additional options.
+		# @returns [Identity] A new Identity instance.
 		def self.nested(parent, name, location = nil, **options)
 			location ||= caller_locations(3...4).first
 			
 			self.new(location.path, name, location.lineno, parent, **options)
 		end
 		
+		# Create an identity for the current location.
+		# @returns [Identity] A new Identity instance for the current caller location.
 		def self.current
 			self.nested(nil, nil, caller_locations(1...2).first)
 		end
 		
-		# @parameter unique [Boolean | Symbol] Whether this identity is unique or needs a unique key/line number suffix.
+		# Initialize a new Identity.
+		# @parameter path [String] The file path.
+		# @parameter name [String, nil] Optional name.
+		# @parameter line [Integer, nil] Optional line number.
+		# @parameter parent [Identity, nil] Optional parent identity.
+		# @parameter unique [Boolean, Symbol] Whether this identity is unique or needs a unique key/line number suffix.
 		def initialize(path, name = nil, line = nil, parent = nil, unique: true)
 			@path = path
 			@name = name
@@ -30,20 +50,34 @@ module Sus
 			@key = nil
 		end
 		
+		# Create a new identity with a different line number.
+		# @parameter line [Integer] The line number.
+		# @returns [Identity] A new Identity instance.
 		def with_line(line)
 			self.class.new(@path, @name, line, @parent, unique: @unique)
 		end
 		
+		# @attribute [String] The file path.
 		attr :path
+		
+		# @attribute [String, nil] The name.
 		attr :name
+		
+		# @attribute [Integer, nil] The line number.
 		attr :line
+		
+		# @attribute [Identity, nil] The parent identity.
 		attr :parent
+		
+		# @attribute [Boolean, Symbol] Whether this identity is unique.
 		attr :unique
 		
+		# @returns [String] A string representation of this identity (the key).
 		def to_s
 			self.key
 		end
 		
+		# @returns [Hash] A hash containing the path and line number.
 		def to_location
 			{
 				path: ::File.expand_path(@path),
@@ -51,10 +85,14 @@ module Sus
 			}
 		end
 		
+		# @returns [String] An inspect representation of this identity.
 		def inspect
 			"\#<#{self.class} #{self.to_s}>"
 		end
 		
+		# Check if this identity matches another.
+		# @parameter other [Identity] The identity to match against.
+		# @returns [Boolean] Whether the identities match.
 		def match?(other)
 			if path = other.path
 				return false unless path === @path
@@ -69,12 +107,15 @@ module Sus
 			end
 		end
 		
+		# Iterate over this identity and all its parents.
+		# @yields {|identity| ...} Each identity in the chain.
 		def each(&block)
 			@parent&.each(&block)
 			
 			yield self
 		end
 		
+		# @returns [String] A unique key for this identity.
 		def key
 			unless @key
 				key = Array.new
@@ -89,6 +130,8 @@ module Sus
 		end
 		
 		# Given a set of locations, find the first one which matches this identity and return a new identity with the updated line number. This can be used to extract a location from a backtrace.
+		# @parameter locations [Array(Thread::Backtrace::Location), nil] Optional locations to search (defaults to caller locations).
+		# @returns [Identity] A new identity with updated line number if a match is found, otherwise returns self.
 		def scoped(locations = nil)
 			if locations
 				# This code path is normally taken if we've got an exception with a backtrace:

data/lib/sus/integrations.rb

@@ -4,6 +4,7 @@
 # Copyright, 2023, by Samuel Williams.
 
 module Sus
+	# @namespace
 	module Integrations
 	end
 end

data/lib/sus/it.rb

@@ -6,7 +6,14 @@
 require_relative "context"
 
 module Sus
+	# Represents an individual test case.
 	module It
+		# Build a new test case class.
+		# @parameter parent [Class] The parent context class.
+		# @parameter description [String | Nil] Optional description of the test.
+		# @parameter unique [Boolean] Whether the identity should be unique.
+		# @yields {...} Optional block containing the test code.
+		# @returns [Class] A new test case class.
 		def self.build(parent, description = nil, unique: true, &block)
 			base = Class.new(parent)
 			base.extend(It)
@@ -21,20 +28,26 @@ module Sus
 			return base
 		end
 		
+		# @returns [Boolean] Always returns true, as test cases are leaf nodes.
 		def leaf?
 			true
 		end
 		
+		# Print a representation of this test case.
+		# @parameter output [Output] The output target.
 		def print(output)
 			self.superclass.print(output)
 			
 			output.write(" it ", :it, self.description, :reset, " ", :identity, self.identity.to_s, :reset)
 		end
 		
+		# @returns [String] A string representation of this test case.
 		def to_s
 			"it #{description}"
 		end
 		
+		# Execute this test case.
+		# @parameter assertions [Assertions] The assertions instance to use.
 		def call(assertions)
 			assertions.nested(self, identity: self.identity, isolated: true, measure: true) do |assertions|
 				instance = self.new(assertions)
@@ -45,6 +58,10 @@ module Sus
 			end
 		end
 		
+		# Handle skip logic for the test case.
+		# @parameter instance [Base] The test instance.
+		# @parameter assertions [Assertions] The assertions instance.
+		# @returns [Object] The result of calling the test instance.
 		def handle_skip(instance, assertions)
 			catch(:skip) do
 				return instance.call
@@ -53,6 +70,10 @@ module Sus
 	end
 	
 	module Context
+		# Define a new test case.
+		# @parameter description [String] The description of the test.
+		# @parameter options [Hash] Additional options.
+		# @yields {...} The test code.
 		def it(...)
 			add It.build(self, ...)
 		end
@@ -66,30 +87,42 @@ module Sus
 			throw :skip, reason
 		end
 		
+		# Skip the test unless a method is defined on the target.
+		# @parameter method [Symbol] The method name to check.
+		# @parameter target [Module, Class] The target class or module to check.
 		def skip_unless_method_defined(method, target)
 			unless target.method_defined?(method)
 				skip "Method #{method} is not defined in #{target}!"
 			end
 		end
 		
+		# Skip the test unless a constant is defined.
+		# @parameter constant [Symbol, String] The constant name to check.
+		# @parameter target [Module, Class] The target class or module to check.
 		def skip_unless_constant_defined(constant, target = Object)
 			unless target.const_defined?(constant)
 				skip "Constant #{constant} is not defined in #{target}!"
 			end
 		end
 		
+		# Skip the test unless the Ruby version meets the minimum requirement.
+		# @parameter version [String] The minimum Ruby version required.
 		def skip_unless_minimum_ruby_version(version)
 			unless RUBY_VERSION >= version
 				skip "Ruby #{version} is required, but running #{RUBY_VERSION}!"
 			end
 		end
 		
+		# Skip the test if the Ruby version exceeds the maximum supported version.
+		# @parameter version [String] The maximum Ruby version supported.
 		def skip_if_maximum_ruby_version(version)
 			if RUBY_VERSION >= version
 				skip "Ruby #{version} is not supported, but running #{RUBY_VERSION}!"
 			end
 		end
 		
+		# Skip the test if the Ruby platform matches the pattern.
+		# @parameter pattern [Regexp] The platform pattern to match against.
 		def skip_if_ruby_platform(pattern)
 			if match = RUBY_PLATFORM.match(pattern)
 				skip "Ruby platform #{match} is not supported!"

data/lib/sus/it_behaves_like.rb

@@ -6,11 +6,20 @@
 require_relative "context"
 
 module Sus
+	# Represents a test context that behaves like a shared context.
 	module ItBehavesLike
 		extend Context
 		
+		# @attribute [Shared] The shared context being used.
 		attr_accessor :shared
 		
+		# Build a new ItBehavesLike context.
+		# @parameter parent [Class] The parent context class.
+		# @parameter shared [Shared] The shared context to use.
+		# @parameter arguments [Array | Nil] Optional arguments to pass to the shared context.
+		# @parameter unique [Boolean] Whether the identity should be unique.
+		# @yields {...} Optional block to execute before the shared context.
+		# @returns [Class] A new test class that behaves like the shared context.
 		def self.build(parent, shared, arguments = nil, unique: false, &block)
 			base = Class.new(parent)
 			base.singleton_class.prepend(ItBehavesLike)
@@ -28,6 +37,8 @@ module Sus
 			return base
 		end
 		
+		# Print a representation of this context.
+		# @parameter output [Output] The output target.
 		def print(output)
 			self.superclass.print(output)
 			output.write(" it behaves like ", :describe, self.description, :reset)
@@ -35,6 +46,11 @@ module Sus
 	end
 	
 	module Context
+		# Define a test context that behaves like a shared context.
+		# @parameter shared [Shared] The shared context to use.
+		# @parameter arguments [Array] Optional arguments to pass to the shared context.
+		# @parameter options [Hash] Additional options.
+		# @yields {...} Optional block to execute before the shared context.
 		def it_behaves_like(shared, *arguments, **options, &block)
 			add ItBehavesLike.build(self, shared, arguments, **options, &block)
 		end

data/lib/sus/let.rb

@@ -7,6 +7,9 @@ require_relative "context"
 
 module Sus
 	module Context
+		# Define a lazy variable that is evaluated when first accessed.
+		# @parameter name [Symbol] The name of the variable.
+		# @yields {...} The block that computes the variable value.
 		def let(name, &block)
 			instance_variable = :"@#{name}"