sus 0.34.0 → 0.35.0

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.34.0"
+	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,18 @@ 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).

data/releases.md

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -54,8 +54,7 @@ files:
 - 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
@@ -70,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

data/context/usage.md

@@ -1,380 +0,0 @@
-# Using Sus Testing Framework
-
-## Overview
-
-Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
-
-## Basic Structure
-
-Here is an example structure for testing with Sus - the actual structure may vary based on your gem's organization, but aside from the `lib/` directory, sus expects the following structure:
-
-```
-my-gem/
-├── config/
-│   └── sus.rb                     # Sus configuration file
-├── lib/
-│   ├── my_gem.rb
-│   └── my_gem/
-│       └── my_thing.rb
-├── fixtures/
-│   └── my_gem/
-│       └── a_thing.rb               # Provides MyGem::AThing shared context
-└── test/
-    ├── my_gem.rb                    # Tests MyGem
-    └── my_gem/
-        └── my_thing.rb              # Tests MyGem::MyThing
-```
-
-### Configuration File
-
-Create `config/sus.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-# Use the covered gem for test coverage reporting:
-require 'covered/sus'
-include Covered::Sus
-
-def before_tests(assertions, output: self.output)
-	# Starts the clock and sets up the test environment:
-	super
-end
-
-def after_tests(assertions, output: self.output)
-	# Stops the clock and prints the test results:
-	super
-end
-```
-
-### Fixtures Files
-
-`fixtures/` gets added to the `$LOAD_PATH` automatically, so you can require files from there without needing to specify the full path.
-
-### Test Files
-
-Sus runs all Ruby files in the `test/` directory by default. But you can also create tests in any file, and run them with the `sus my_tests.rb` command.
-
-## Basic Syntax
-
-```ruby
-# frozen_string_literal: true
-
-describe MyThing do
-	let(:my_thing) {subject.new}
-	
-	with "#my_method" do
-		it "does something" do
-			expect(my_thing.my_method).to be == 42
-		end
-	end
-end
-```
-
-### `describe` - Test Groups
-
-Use `describe` to group related tests:
-
-```ruby
-describe MyThing do
-	# The subject will be whatever is described:
-	let(:my_thing) {subject.new}
-end
-```
-
-### `it` - Individual Tests
-
-Use `it` to define individual test cases:
-
-```ruby
-it "returns the expected value" do
-	expect(result).to be == "expected"
-end
-```
-
-You can use `it` blocks at the top level or within `describe` or `with` blocks.
-
-### `with` - Context Blocks
-
-Use `with` to create context-specific test groups:
-
-```ruby
-with "valid input" do
-	let(:input) {"valid input"}
-	it "succeeds" do
-		expect{my_thing.process(input)}.not.to raise_exception
-	end
-end
-
-# Non-lazy state can be provided as keyword arguments:
-with "invalid input", input: nil do
-	it "raises an error" do
-		expect{my_thing.process(input)}.to raise_exception(ArgumentError)
-	end
-end
-```
-
-When testing methods, use `with` to specify the method being tested:
-
-```ruby
-with "#my_method" do
-	it "results a value" do
-		expect(my_thing.method).to be == 42
-	end
-end
-
-with ".my_class_method" do
-	it "returns a value" do
-		expect(MyThing.class_method).to be == "class value"
-	end
-end
-```
-
-### `let` - Lazy Variables
-
-Use `let` to define variables that are evaluated when first accessed:
-
-```ruby
-let(:helper) {subject.new}
-let(:test_data) {"test value"}
-
-it "uses the helper" do
-	expect(helper.process(test_data)).to be_truthy
-end
-```
-
-### `before` and `after` - Setup/Teardown
-
-Use `before` and `after` for setup and teardown logic:
-
-```ruby
-before do
-	# Setup logic.
-end
-
-after do
-	# Cleanup logic.
-end
-```
-
-Error handling in `after` allows you to perform cleanup even if the test fails with an exception (not a test failure).
-
-```ruby
-after do |error = nil|
-	if error
-		# The state of the test is unknown, so you may want to forcefully kill processes or clean up resources.
-		Process.kill(:KILL, @child_pid)
-	else
-		# Normal cleanup logic.
-		Process.kill(:TERM, @child_pid)
-	end
-	
-	Process.waitpid(@child_pid)
-end
-```
-
-### `around` - Setup/Teardown
-
-Use `around` for setup and teardown logic:
-
-```ruby
-around do |&block|
-	# Setup logic.
-	super() do
-		# Run the test.
-		block.call
-	end
-ensure
-	# Cleanup logic.
-end
-```
-
-Invoking `super()` calls any parent `around` block, allowing you to chain setup and teardown logic.
-
-## Assertions
-
-### Basic Assertions
-
-```ruby
-expect(value).to be == expected
-exepct(value).to be >= 10
-expect(value).to be <= 100
-expect(value).to be > 0
-expect(value).to be < 1000
-expect(value).to be_truthy
-expect(value).to be_falsey
-expect(value).to be_nil
-expect(value).to be_equal(another_value)
-expect(value).to be_a(Class)
-```
-
-### Strings
-
-```ruby
-expect(string).to be(:start_with?, "prefix")
-expect(string).to be(:end_with?, "suffix")
-expect(string).to be(:match?, /pattern/)
-expect(string).to be(:include?, "substring")
-```
-
-### Ranges and Tolerance
-
-```ruby
-expect(value).to be_within(0.1).of(5.0)
-expect(value).to be_within(5).percent_of(100)
-```
-
-### Method Calls
-
-To call methods on the expected object:
-
-```ruby
-expect(array).to be(:include?, "value")
-expect(string).to be(:start_with?, "prefix")
-expect(object).to be(:respond_to?, :method_name)
-```
-
-### Collection Assertions
-
-```ruby
-expect(array).to have_attributes(length: be == 1)
-expect(array).to have_value(be > 1)
-
-expect(hash).to have_keys(:key1, "key2")
-expect(hash).to have_keys(key1: be == 1, "key2" => be == 2)
-```
-
-### Attribute Testing
-
-```ruby
-expect(user).to have_attributes(
-  name: be == "John",
-  age: be >= 18,
-  email: be(:include?, "@")
-)
-```
-
-### Exception Assertions
-
-```ruby
-expect do
-	risky_operation
-end.to raise_exception(RuntimeError, message: be =~ /expected error message/)
-```
-
-## Combining Predicates
-
-Predicates can be nested.
-
-```ruby
-expect(user).to have_attributes(
-	name: have_attributes(
-		first: be == "John",
-		last: be == "Doe"
-	),
-	comments: have_value(be =~ /test comment/),
-	created_at: be_within(1.minute).of(Time.now)
-)
-```
-
-### Logical Combinations
-
-```ruby
-expect(value).to (be > 10).and(be < 20)
-expect(value).to be_a(String).or(be_a(Symbol), be_a(Integer))
-```
-
-### Custom Predicates
-
-You can create custom predicates for more complex assertions:
-
-```ruby
-def be_small_prime
-	(be == 2).or(be == 3, be == 5, be == 7)
-end
-```
-
-## Block Expectations
-
-### Testing Blocks
-
-```ruby
-expect{operation}.to raise_exception(Error)
-expect{operation}.to have_duration(be < 1.0)
-```
-
-### Performance Testing
-
-You should generally avoid testing performance in unit tests, as it will be highly unstable and dependent on the environment. However, if you need to test performance, you can use:
-
-```ruby
-expect{slow_operation}.to have_duration(be < 2.0)
-expect{fast_operation}.to have_duration(be < 0.1)
-```
-
-- For less unsable performance tests, you can use the `sus-fixtures-time` gem which tries to compensate for the environment by measuring execution time.
-
-- For benchmarking, you can use the `sus-fixtures-benchmark` gem which measures a block of code multiple times and reports the execution time.
-
-## File Operations
-
-### Temporary Directories
-
-Use `Dir.mktmpdir` for isolated test environments:
-
-```ruby
-around do |block|
-	Dir.mktmpdir do |root|
-		@root = root
-		block.call
-	end
-end
-
-let(:test_path) {File.join(@root, "test.txt")}
-
-it "can create a file" do
-	File.write(test_path, "content")
-	expect(File).to be(:exist?, test_path)
-end
-```
-
-## Test Output
-
-In general, tests should not produce output unless there is an error or failure.
-
-### Informational Output
-
-You can use `inform` to print informational messages during tests:
-
-```ruby
-it "logs an informational message" do
-	rate = copy_data(source, destination)
-	inform "Copied data at #{rate}MB/s"
-	expect(rate).to be > 0
-end
-```
-
-This can be useful for debugging or providing context during test runs.
-
-### Console Output
-
-The `sus-fixtures-console` gem provides a way to surpress and capture console output during tests. If you are using code which generates console output, you can use this gem to capture it and assert on it.
-
-## Running Tests
-
-```bash
-# Run all tests
-bundle exec sus
-
-# Run specific test file
-bundle exec sus test/specific_test.rb
-```
-
-## Best Practices
-
-1. **Use real objects** instead of mocks when possible.
-2. **Dependency injection** for testability.
-3. **Isolatae mutable state** using temporary directories.
-4. **Clear test descriptions** that explain the behavior.
-5. **Group tests** with `describe` (classes) and `with` for better organization.
-6. **Keep tests simple** and focused on one behavior.