sus 0.37.1 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adb6aea1bd43dd00163501093a72b5e3ed4e599462248a7aacc4bd98732fd35e
-  data.tar.gz: 603c5afe02ea770e0826ab158b84543f4b64e2ece0de9c303b8efa22ab092812
+  metadata.gz: d3dcb5de6597ebcc7d81b78022f79f4b5de62ec5c902f76bed8f23d2fe9ca8fa
+  data.tar.gz: 1eeddde2ea281d7e0d277726905c233de4febb80f5560f03b48b36d6e1d9e0e6
 SHA512:
-  metadata.gz: 5c3b7d6b3a32c817fa0b4e473556a272acd573a41d3b0a54ff760208f9037944d8b6c07725e70d96399058cc9e0ae6cf25c3f4aa50714e06aeb5a3b1ecd3f436
-  data.tar.gz: 11e25dfb46c632ffe7f02ea0a3ccc63b8932749b58cba9564f8d465481b80db4d90504ab1db07e1648a31e7034cd32b99d3a2f9743a35d5032fa750faff2e366
+  metadata.gz: 542588a3f55fa3d835ccced647fea9b5469f01c82c79ea2bf5fbaf96f45faf6f98e621a8c1802934c7cc2a56ab763ab4464346606449165fc3321325fb378dee
+  data.tar.gz: 2de2a0703afeb06798257b642d507cfee6a2377b6fd23ea391db10bede8b9b093e9f7e9c02a6bdbd2069da0318c089aaea5b16b3dc70033a537f86e6e3268f9f

data/context/shared-contexts.md

@@ -198,6 +198,50 @@ end
 
 Note the use of `unique: adapter.name` to ensure each test is uniquely identified, which is useful for reporting and debugging - otherwise the same test line number would be used for all iterations, which can make it hard to identify which specific test failed.
 
+## Isolated Ruby
+
+Use `Sus::Fixtures::IsolatedRubyContext` to evaluate Ruby in a fresh process and assert on its result. This is useful for code that relies on a working directory, environment variables, or constants which must be isolated from other tests.
+
+```ruby
+require "sus/fixtures/isolated_ruby_context"
+require "sus/fixtures/temporary_directory_context"
+
+describe "isolated evaluation" do
+	include Sus::Fixtures::IsolatedRubyContext
+	include Sus::Fixtures::TemporaryDirectoryContext
+	
+	it "reads files in the fixture directory" do
+		File.write(File.join(root, "value.txt"), "example")
+		result = isolated_ruby(<<~RUBY, chdir: root)
+			{value: File.read("value.txt")}
+		RUBY
+		
+		expect(result[:value]).to be == "example"
+	end
+end
+```
+
+The final expression is returned using `Marshal.dump` and `Marshal.load`, preserving Ruby types, hash keys, string encodings, and shared or cyclic references. The result must support Marshal serialization, and any custom classes it uses must also be loaded in the caller.
+
+Exceptions raised while loading requested features, evaluating source, or serializing the result are marshaled back and re-raised in the caller with their original class, message, and backtrace. Custom exception classes must also be loaded in the caller. Returning an exception object as the final expression returns it as a value.
+
+Printed output goes to the inherited stderr, keeping it separate from the result. An unsuccessful child that cannot return an exception raises `IsolatedRubyContext::Error`, which exposes its `status`; diagnostics appear directly on stderr. This includes startup failures, unsuccessful explicit exits, and exceptions that cannot be marshaled. A successful exit without a result, such as `exit(0)`, returns `nil`.
+
+The fixture uses the current Ruby interpreter and defaults to the caller's working directory. `chdir:` changes only the child's directory, so evaluations can run concurrently. The child inherits the environment, including `RUBYOPT` so coverage and other startup hooks continue to run. `env:` supplies child environment overrides; a nil value removes a variable. For a clean startup without inherited Ruby or Bundler hooks, pass `env: {"RUBYOPT" => nil, "BUNDLER_SETUP" => nil}`.
+
+Use `requires:` to load features before evaluating the source. To set up a particular bundle, use an absolute Gemfile path:
+
+```ruby
+result = isolated_ruby(
+	'require "my_gem"; {version: MyGem::VERSION}',
+	chdir: root,
+	env: {"BUNDLE_GEMFILE" => File.expand_path("gems.rb")},
+	requires: ["bundler/setup"]
+)
+```
+
+The fixture accepts source code rather than a block; parent local variables and loaded Ruby state are not transferred to the child. It works independently of `TemporaryDirectoryContext`.
+
 ## Best Practices
 
 1. **Organize by domain**: Group related shared contexts together in modules

data/lib/sus/be.rb

@@ -46,7 +46,7 @@ module Sus
 			# @parameter other [Object] Another predicate to combine.
 			# @returns [Or] A new OR predicate.
 			def |(other)
-				Or.new(self, other)
+				Or.new([self, other])
 			end
 		end
 		
@@ -93,7 +93,7 @@ module Sus
 			# @parameter other [Object] Another predicate to combine.
 			# @returns [And] A new AND predicate.
 			def &(other)
-				And.new(self, other)
+				And.new([self, other])
 			end
 			
 			# Combine this predicate with another using OR logic.

data/lib/sus/config.rb

@@ -27,8 +27,9 @@ module Sus
 		# 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.
+		# @parameter env [Hash] The environment to inspect for debug/verbose settings.
 		# @returns [Config] A new Config instance.
-		def self.load(root: Dir.pwd, arguments: ARGV)
+		def self.load(root: Dir.pwd, arguments: ARGV, env: ENV)
 			derived = Class.new(self)
 			
 			if path = self.path(root)
@@ -38,12 +39,40 @@ module Sus
 			end
 			
 			options = {
-				verbose: !!arguments.delete("--verbose")
+				verbose: !!arguments.delete("--verbose") || self.verbose_from_environment?(env)
 			}
 			
 			return derived.new(root, arguments, **options)
 		end
 		
+		# Maps CI environment variables to the values they take when the CI provider is running in debug/verbose mode. When any of these match, we enable verbose output automatically.
+		#
+		# - `RUNNER_DEBUG` is set by GitHub Actions when a workflow is re-run with "Enable debug logging".
+		# - `CI_DEBUG_TRACE` is set by GitLab CI when debug logging (tracing) is enabled.
+		# - `BUILDKITE_AGENT_DEBUG` is set by Buildkite when agent debug is enabled.
+		# - `SYSTEM_DEBUG` is set by Azure Pipelines when the `system.debug` variable is enabled.
+		# - `SUS_VERBOSE` can be set explicitly to enable verbose output regardless of the CI provider.
+		DEBUG_ENVIRONMENT = {
+			"SUS_VERBOSE" => "true",
+			"RUNNER_DEBUG" => "1",
+			"CI_DEBUG_TRACE" => "true",
+			"BUILDKITE_AGENT_DEBUG" => "true",
+			"SYSTEM_DEBUG" => "true",
+		}
+		
+		# Whether verbose output should be enabled based on the environment.
+		#
+		# Detects CI environments that request debug logging, e.g. GitHub Actions
+		# sets `RUNNER_DEBUG=1` when a workflow is re-run with "Enable debug logging".
+		#
+		# @parameter env [Hash] The environment to inspect.
+		# @returns [Boolean] Whether verbose output should be enabled.
+		def self.verbose_from_environment?(env = ENV)
+			DEBUG_ENVIRONMENT.any? do |key, value|
+				env[key] == value
+			end
+		end
+		
 		# Initialize a new Config instance.
 		# @parameter root [String] The root directory for the project.
 		# @parameter paths [Array] Optional paths to specific test files.
@@ -196,13 +225,16 @@ module Sus
 		
 		# 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
-			
-			total = assertions.total
-			count = assertions.count
+		# @parameter assertions [Assertions | Nil] The assertions instance.
+		# @parameter duration [Float] The total duration of the test suite.
+		# @parameter count [Integer] The number of assertions.
+		# @parameter total [Integer] The number of tests.
+		def print_test_feedback(output, assertions = nil,
+			duration: @clock.duration,
+			count: assertions.count,
+			total: assertions.total
+		)
+			rate = count / duration
 			
 			if total < 10 or count < 10
 				output.puts "😭 You should write more tests and assertions!"
@@ -212,7 +244,7 @@ module Sus
 			end
 			
 			# Check whether there is at least, on average, one assertion (or more) per test:
-			assertions_per_test = assertions.count / assertions.total
+			assertions_per_test = count / total
 			if assertions_per_test < 1.0
 				output.puts "😩 Your tests don't have enough assertions (#{assertions_per_test.round(1)} < 1.0)!"
 			end
@@ -242,6 +274,8 @@ module Sus
 			end
 		end
 		
+		public :print_test_feedback
+		
 		# Print information about slow tests.
 		# @parameter output [Output] The output handler.
 		# @parameter assertions [Assertions] The assertions instance.

data/lib/sus/context.rb

@@ -24,28 +24,6 @@ module Sus
 			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}>"
-				else
-					self.name
-				end
-			end
-		end
-		
 		# Add a child context or test to this context.
 		# @parameter child [Object] The child to add.
 		def add(child)

data/lib/sus/fixtures/isolated_ruby_context.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "rbconfig"
+
+# @namespace
+module Sus
+	# @namespace
+	module Fixtures
+		# Evaluates Ruby in a fresh process and returns its result through Marshal.
+		module IsolatedRubyContext
+			# Raised when the child process exits unsuccessfully without returning an exception.
+			class Error < RuntimeError
+				# @parameter status [Process::Status] The child process's exit status.
+				def initialize(status)
+					@status = status
+					super("Isolated Ruby failed (#{status})")
+				end
+				
+				# @attribute [Process::Status] The child process's exit status.
+				attr :status
+			end
+			
+			# Evaluate source using the current Ruby interpreter, without sharing Ruby state or changing the caller's working directory.
+			# The final expression is serialized with Marshal.dump and restored with Marshal.load. Printed output goes to the inherited stderr.
+			# Exceptions are marshaled back and re-raised with their original backtraces. SystemExit follows the child process's exit status.
+			# @parameter source [String] Ruby source code to evaluate.
+			# @parameter chdir [String] The child process's working directory.
+			# @parameter env [Hash(String, String | Nil)] Child environment overrides; nil removes a variable. The environment is inherited by default, including RUBYOPT for coverage hooks.
+			# @parameter requires [Array(String)] Features to require before evaluating source, such as bundler/setup.
+			# @returns [Object] The unmarshaled result, or nil if the child exits successfully without a result. Classes used by the result must be available in the caller.
+			# @raises [Exception] The exception raised in the child process, if it can be marshaled back.
+			# @raises [Error] If the child exits unsuccessfully without returning an exception.
+			# @raises [ArgumentError] If the result or exception uses a class unavailable in the caller.
+			def isolated_ruby(source, chdir: Dir.pwd, env: {}, requires: [])
+				script = <<~'RUBY'
+					->(output) do
+						$stdout.reopen($stderr)
+						begin
+							source = $stdin.read
+							ARGV.each{|feature| require feature}
+							result = eval(source, TOPLEVEL_BINDING, File.join(Dir.pwd, "(isolated ruby)"))
+							output.write(Marshal.dump([result, nil]))
+						rescue SystemExit
+							raise
+						rescue Exception => error
+							output.write(Marshal.dump([nil, error]))
+						end
+					end.call($stdout.dup.binmode)
+				RUBY
+				
+				output = IO.popen([env, RbConfig.ruby, "-e", script, "--", *requires], "r+b", chdir: chdir) do |process|
+					begin
+						process.write(source)
+					rescue Errno::EPIPE
+						# A startup failure may close stdin before accepting the source:
+					end
+					process.close_write
+					process.read
+				end
+				status = $?
+				raise Error.new(status) unless status.success?
+				return nil if output.empty?
+				
+				result, error = Marshal.load(output)
+				raise error if error
+				result
+			end
+		end
+	end
+end

data/lib/sus/fixtures/temporary_directory_context.rb

@@ -4,6 +4,7 @@
 # Copyright, 2025-2026, by Samuel Williams.
 
 require "tmpdir"
+require "fileutils"
 
 module Sus
 	module Fixtures
@@ -12,10 +13,17 @@ module Sus
 			# 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 = Dir.mktmpdir
+				
+				begin
 					@root = root
+					
 					super(&block)
+				ensure
 					@root = nil
+					
+					# Use forced removal so cleanup tolerates paths which were already removed by the test or an external process.
+					FileUtils.remove_entry(root, true)
 				end
 			end
 			
@@ -24,4 +32,3 @@ module Sus
 		end
 	end
 end
-

data/lib/sus/identity.rb

@@ -142,7 +142,7 @@ module Sus
 				end
 			else
 				# In theory this should be a bit faster:
-				each_caller_location do |location|
+				Thread.each_caller_location do |location|
 					if location.path == @path
 						return self.with_line(location.lineno)
 					end
@@ -154,16 +154,6 @@ module Sus
 		
 		protected
 		
-		if Thread.respond_to?(:each_caller_location)
-			def each_caller_location(&block)
-				Thread.each_caller_location(&block)
-			end
-		else
-			def each_caller_location(&block)
-				caller_locations(1).each(&block)
-			end
-		end
-		
 		def append_unique_key(key, unique = @unique)
 			if @parent
 				@parent.append_unique_key(key)

data/lib/sus/it.rb

@@ -107,17 +107,19 @@ module Sus
 		
 		# 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}!"
+		# @parameter ruby_version [String] The Ruby version to check.
+		def skip_unless_minimum_ruby_version(version, ruby_version = RUBY_VERSION)
+			unless compare_ruby_version(ruby_version, version) >= 0
+				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}!"
+		# @parameter ruby_version [String] The Ruby version to check.
+		def skip_if_maximum_ruby_version(version, ruby_version = RUBY_VERSION)
+			if compare_ruby_version(ruby_version, version) >= 0
+				skip "Ruby #{version} is not supported, but running #{ruby_version}!"
 			end
 		end
 		
@@ -128,5 +130,23 @@ module Sus
 				skip "Ruby platform #{match} is not supported!"
 			end
 		end
+		
+		private
+		
+		def compare_ruby_version(left, right)
+			left_segments = left.split(".").map(&:to_i)
+			right_segments = right.split(".").map(&:to_i)
+			length = [left_segments.size, right_segments.size].max
+			
+			length.times do |index|
+				left_segment = left_segments[index] || 0
+				right_segment = right_segments[index] || 0
+				
+				return -1 if left_segment < right_segment
+				return 1 if left_segment > right_segment
+			end
+			
+			return 0
+		end
 	end
 end

data/lib/sus/respond_to.rb

@@ -21,9 +21,9 @@ module Sus
 				parameters = @parameters.dup
 				
 				assertions.nested(self) do |assertions|
-					expected_name = parameters.shift
-					
 					subject.each do |type, name|
+						expected_name = parameters.shift
+						
 						case type
 						when :req
 							assertions.assert(name == expected_name, "parameter #{expected_name} is required, but was #{name}")

data/lib/sus/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Sus
-	VERSION = "0.37.1"
+	VERSION = "0.38.0"
 end

data/readme.md

@@ -33,6 +33,14 @@ Please see the [project documentation](https://socketry.github.io/sus/) for more
 
 Please see the [project releases](https://socketry.github.io/sus/releases/index) for all releases.
 
+### v0.38.0
+
+  - Add `Sus::Fixtures::IsolatedRubyContext#isolated_ruby` for evaluating Ruby in a fresh process with optional working directory and environment overrides, returning Ruby values and re-raising exceptions in the caller.
+
+### v0.37.2
+
+  - Make `Sus::Fixtures::TemporaryDirectoryContext` ignore temporary directory cleanup failures.
+
 ### v0.37.1
 
   - Fixed `Sus::Mock#wrap` to forward blocks to the original method, and fixed `receive(...).with_block(...)` to use the supplied predicate.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.38.0
+
+  - Add `Sus::Fixtures::IsolatedRubyContext#isolated_ruby` for evaluating Ruby in a fresh process with optional working directory and environment overrides, returning Ruby values and re-raising exceptions in the caller.
+
+## v0.37.2
+
+  - Make `Sus::Fixtures::TemporaryDirectoryContext` ignore temporary directory cleanup failures.
+
 ## v0.37.1
 
   - Fixed `Sus::Mock#wrap` to forward blocks to the original method, and fixed `receive(...).with_block(...)` to use the supplied predicate.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus
 version: !ruby/object:Gem::Version
-  version: 0.37.1
+  version: 0.38.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -70,6 +70,7 @@ files:
 - lib/sus/file.rb
 - lib/sus/filter.rb
 - lib/sus/fixtures.rb
+- lib/sus/fixtures/isolated_ruby_context.rb
 - lib/sus/fixtures/temporary_directory_context.rb
 - lib/sus/have.rb
 - lib/sus/have/all.rb
@@ -127,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A fast and scalable test runner.
 test_files: []