sus 0.37.2 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 356b7bfa38432ef766bae5c9ef40f7e0d08cacf9423544c1226ac86c92e78f16
-  data.tar.gz: 21ea8115de9084304ad615db7d33d7facafa7255e1d3bafd408c9885ce14044e
+  metadata.gz: d3dcb5de6597ebcc7d81b78022f79f4b5de62ec5c902f76bed8f23d2fe9ca8fa
+  data.tar.gz: 1eeddde2ea281d7e0d277726905c233de4febb80f5560f03b48b36d6e1d9e0e6
 SHA512:
-  metadata.gz: a3db361e81379abc117c1f977a979b66f6dcd1c42270fee895db1cb1d1bef0f6c64ed45fe51084de4d0e4671d6a83475cc7dc74523221340dbfeee5921bdbc8f
-  data.tar.gz: fe44089f8600b62d4255ecdaeb3b8e15060735a7ad8e5e9d78a8e5a5dfb05a63ae999b0681ccba55ce18048fa9cd5c94c8cbb221561b72328eee96b273d002f1
+  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/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.

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/version.rb

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

data/readme.md

@@ -33,6 +33,10 @@ 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.

data/releases.md

@@ -1,5 +1,9 @@
 # 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.

data.tar.gz.sig

@@ -1,2 +1,2 @@
-F�a���@2R�)Y�R���g쮉Z�^�&,j(t��]��zN���upd��!`���,_��]�ܸ����O�,����n�r��	��Dc�����cg�L�[�Ve��"%(駗���P,\����@�����Po�Z)��&��dM��W���
-7�׃`Ơ����ۨ�cl���lӵZ�H�vV:��He�l���sM"C�imO�������X�������r;��N����<�����"�`�3��˵��y����eԭlH���o�������ۭzq���,�S�,��6��&U�~tH9�>bլ�ə��m��:��p���� N2h�9��x�	�R��YX1�]��J�`��!y�<�;t�T3�>
�׋�!����U
+K�%��ZP�7�$<
��Q��x��|��O�#�X����bD�`u�`��@�s���92+K�x���O��B���h����x��eO�g���n��6�����p��ʈ2�Q��@�.�L#��MU/�H�?О)�G3�as��ZQ��*d؊ ��!�5P���Gv|L�!��tZ��m%HP:;�Q4Wd	DW!�����],�ܶ��@�#�Cl�t
=I�ձ�*�R45�Z�Q���[d��M�y0��];���!��F���#`	-E#�5�\N�-O�I{ء�
+������4���ё`���FK�D>���n:���E���Fd�P�V^^R�^BKܐ{ʾ�L��nD�4�„�s8�o� ����!��|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus
 version: !ruby/object:Gem::Version
-  version: 0.37.2
+  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: []