sus 0.33.1 → 0.35.0

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

data/lib/sus/respond_to.rb

@@ -1,16 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 module Sus
+	# Represents a predicate that checks if an object responds to a method.
 	class RespondTo
+		# Represents a constraint on method parameters.
 		class WithParameters
-			# @parameter [Array(Symbol)] List of method parameters in the expected order, must include at least all required parameters but can also list optional parameters.
+			# Initialize a new WithParameters constraint.
+			# @parameter parameters [Array(Symbol)] List of method parameters in the expected order, must include at least all required parameters but can also list optional parameters.
 			def initialize(parameters)
 				@parameters = parameters
 			end
 			
+			# Evaluate this constraint against method parameters.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Array] The method parameters to check.
 			def call(assertions, subject)
 				parameters = @parameters.dup
 				
@@ -32,15 +38,23 @@ module Sus
 			end
 		end
 		
+		# Represents a constraint on method keyword options.
 		class WithOptions
+			# Initialize a new WithOptions constraint.
+			# @parameter options [Array(Symbol)] The option names that should be present.
 			def initialize(options)
 				@options = options
 			end
-						
+			
+			# Print a representation of this constraint.
+			# @parameter output [Output] The output target.
 			def print(output)
 				output.write("with options ", :variable, @options.inspect)
 			end
 			
+			# Evaluate this constraint against method parameters.
+			# @parameter assertions [Assertions] The assertions instance to use.
+			# @parameter subject [Array] The method parameters to check.
 			def call(assertions, subject)
 				options = {}
 				@options.each{|name| options[name] = nil}
@@ -57,21 +71,31 @@ module Sus
 			end
 		end
 		
+		# Initialize a new RespondTo predicate.
+		# @parameter method [Symbol, String] The method name to check for.
 		def initialize(method)
 			@method = method
 			@parameters = nil
 			@options = nil
 		end
 		
+		# Specify that the method should have specific keyword options.
+		# @parameter options [Array(Symbol)] The option names that should be present.
+		# @returns [RespondTo] Returns self for method chaining.
 		def with_options(*options)
 			@options = WithOptions.new(options)
 			return self
 		end
 		
+		# Print a representation of this predicate.
+		# @parameter output [Output] The output target.
 		def print(output)
 			output.write("respond to ", :variable, @method.to_s, :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|
 				condition = subject.respond_to?(@method)
@@ -87,6 +111,9 @@ module Sus
 	end
 	
 	class Base
+		# Create a predicate that checks if the subject responds to a method.
+		# @parameter method [Symbol, String] The method name to check for.
+		# @returns [RespondTo] A new RespondTo predicate.
 		def respond_to(method)
 			RespondTo.new(method)
 		end

data/lib/sus/shared.rb

@@ -6,10 +6,18 @@
 require_relative "context"
 
 module Sus
+	# Represents a shared test context that can be reused across multiple test files.
 	module Shared
+		# @attribute [String] The name of the shared context.
 		attr_accessor :name
+		
+		# @attribute [Proc] The block containing the shared test code.
 		attr_accessor :block
 		
+		# Build a new Shared context.
+		# @parameter name [String] The name of the shared context.
+		# @parameter block [Proc] The block containing the shared test code.
+		# @returns [Module] A new Shared module.
 		def self.build(name, block)
 			base = Module.new
 			base.extend(Shared)
@@ -19,15 +27,23 @@ module Sus
 			return base
 		end
 		
+		# Called when this module is included in a test class.
+		# @parameter base [Class] The class including this module.
 		def included(base)
 			base.class_exec(&self.block)
 		end
 		
+		# Called when this module is prepended to a test class.
+		# @parameter base [Class] The class prepending this module.
 		def prepended(base)
 			base.class_exec(&self.block)
 		end
 	end
 	
+	# Create a new shared test context.
+	# @parameter name [String] The name of the shared context.
+	# @yields {...} The block containing the shared test code.
+	# @returns [Shared] A new Shared module.
 	def self.Shared(name, &block)
 		Shared.build(name, block)
 	end

data/lib/sus/tree.rb

@@ -4,11 +4,18 @@
 # Copyright, 2023, by Samuel Williams.
 
 module Sus
+	# Represents a tree structure of test contexts.
 	class Tree
+		# Initialize a new Tree.
+		# @parameter context [Object] The root context.
 		def initialize(context)
 			@context = context
 		end
 		
+		# Traverse the tree, yielding each context.
+		# @parameter current [Object] The current context (defaults to root).
+		# @yields {|context| ...} Each context in the tree.
+		# @returns [Hash] A hash representation of the tree.
 		def traverse(current = @context, &block)
 			node = {}
 			
@@ -23,6 +30,9 @@ module Sus
 			return node
 		end
 		
+		# Convert the tree to JSON.
+		# @parameter options [Hash, nil] Options to pass to JSON.generate.
+		# @returns [String] A JSON representation of the tree.
 		def to_json(options = nil)
 			traverse do |context|
 				[context.identity.to_s, context.description.to_s, context.leaf?]

data/lib/sus/version.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
+# @namespace
 module Sus
-	VERSION = "0.33.1"
+	VERSION = "0.35.0"
 end

data/lib/sus/with.rb

@@ -6,12 +6,23 @@
 require_relative "context"
 
 module Sus
+	# Represents a test context with specific conditions or variables.
 	module With
 		extend Context
 		
+		# @attribute [String] The subject description of this context.
 		attr_accessor :subject
+		
+		# @attribute [Hash] The variables available in this context.
 		attr_accessor :variables
 		
+		# Build a new with block class.
+		# @parameter parent [Class] The parent context class.
+		# @parameter subject [String] The subject description.
+		# @parameter variables [Hash] Variables to make available in the context.
+		# @parameter unique [Boolean] Whether the identity should be unique.
+		# @yields {...} Optional block containing nested tests.
+		# @returns [Class] A new with block class.
 		def self.build(parent, subject, variables, unique: true, &block)
 			base = Class.new(parent)
 			base.singleton_class.prepend(With)
@@ -36,6 +47,8 @@ module Sus
 			return base
 		end
 		
+		# Print a representation of this with block.
+		# @parameter output [Output] The output target.
 		def print(output)
 			self.superclass.print(output)
 			
@@ -47,6 +60,11 @@ module Sus
 	end
 	
 	module Context
+		# Define a new test context with specific conditions or variables.
+		# @parameter subject [String | Nil] Optional subject description. If nil, uses variables.inspect.
+		# @parameter unique [Boolean] Whether the identity should be unique.
+		# @parameter variables [Hash] Variables to make available in the context.
+		# @yields {...} Optional block containing nested tests.
 		def with(subject = nil, unique: true, **variables, &block)
 			subject ||= variables.inspect
 			

data/readme.md

@@ -25,10 +25,22 @@ Please see the [project documentation](https://socketry.github.io/sus/) for more
 
   - [Getting Started](https://socketry.github.io/sus/guides/getting-started/index) - This guide explains how to use the `sus` gem to write tests for your Ruby projects.
 
+  - [Mocking](https://socketry.github.io/sus/guides/mocking/index) - This guide explains how to use mocking in sus to isolate dependencies and verify interactions in your tests.
+
+  - [Shared Test Behaviors and Fixtures](https://socketry.github.io/sus/guides/shared-contexts/index) - This guide explains how to use shared test contexts and fixtures in sus to reduce duplication and ensure consistent test behavior across your test suite.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/sus/releases/index) for all releases.
 
+### v0.35.0
+
+  - Add `Sus::Fixtures::TemporaryDirectoryContext`.
+
+### v0.34.0
+
+  - Allow `expect(...).to receive(...)` to accept one or more calls (at least once).
+
 ### v0.33.0
 
   - Add support for `agent-context` gem.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.35.0
+
+  - Add `Sus::Fixtures::TemporaryDirectoryContext`.
+
+## v0.34.0
+
+  - Allow `expect(...).to receive(...)` to accept one or more calls (at least once).
+
 ## v0.33.0
 
   - Add support for `agent-context` gem.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus
 version: !ruby/object:Gem::Version
-  version: 0.33.1
+  version: 0.35.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -51,9 +51,10 @@ files:
 - bin/sus-host
 - bin/sus-parallel
 - bin/sus-tree
+- context/getting-started.md
+- context/index.yaml
 - context/mocking.md
-- context/shared.md
-- context/usage.md
+- context/shared-contexts.md
 - lib/sus.rb
 - lib/sus/assertions.rb
 - lib/sus/base.rb
@@ -68,6 +69,7 @@ files:
 - lib/sus/file.rb
 - lib/sus/filter.rb
 - lib/sus/fixtures.rb
+- lib/sus/fixtures/temporary_directory_context.rb
 - lib/sus/have.rb
 - lib/sus/have/all.rb
 - lib/sus/have/any.rb
@@ -123,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A fast and scalable test runner.
 test_files: []