sus 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8e0db7c132f0bf73f74ed8e0def2d4e53d41d48133f8cd3183c18fa530ec847
-  data.tar.gz: f0e3c8b30d700ed917d2a74a81837f21278c4f45fdc3271a7a9213a0dd631895
+  metadata.gz: 13490197ec8a1933e204be63306d7073dc91031f91014540d2fb32f28a5a9fe8
+  data.tar.gz: d95be355e8ee973b7c6873024dea1aca229ead1ca07ac32ee758c1c200cffa2c
 SHA512:
-  metadata.gz: 0f5d22b2d3548fef4d43afeea24fa74a2c47fa99d6640b7db4c0b6af00ecd07cdcb52303c4d3276fc32d4e62e7ae045eeffbbef54c379bd0f21f207e820b9aef
-  data.tar.gz: 8b1485cee341ba0b8083bda0c5da868f97f68002657f051d977b590fbb4e1bf7a97e9fa816c6949961740b39704de507e003e5c6dc6c213b6791f7ebdc7d53dc
+  metadata.gz: e7282096b713bbaf9b6e08839ccc8436c4660c4e2b913c08a9af6867b84ea518f0ba2366db46a67d30e81d20ce845a32dcfb4f13e1712fdc6aabe01e7f67b4af
+  data.tar.gz: be1584808b3db0e3ef6bfc1c9d06c928ad0ca292244dd8a53633cc619107ac74604240d5fb916329654ac68df5033456e1802db28f9af308528341b17bf899c4

data/context/getting-started.md

@@ -108,7 +108,7 @@ Use `describe` to group related tests:
 ```ruby
 describe MyThing do
 	# The subject will be whatever is described:
-	let(:my_thing){subject.new}
+	let(:my_thing) {subject.new}
 end
 ```
 

data/lib/sus/be.rb

@@ -146,7 +146,10 @@ module Sus
 			output.write("be ", :be, operation.to_s, :reset)
 			
 			if arguments.any?
-				output.write(" ", :variable, arguments.map(&:inspect).join, :reset)
+				output.write(" ")
+				arguments.each do |argument|
+					output.variable(argument)
+				end
 			end
 		end
 		

data/lib/sus/expect.rb

@@ -15,8 +15,8 @@ module Sus
 			@assertions = assertions
 			@subject = subject
 			
-			# We capture this here, as changes to state may cause the inspect output to change, affecting the output produced by #print.
-			@inspect = @subject.inspect
+			# We capture this here, as changes to state may cause the inspect output to change, affecting the output produced by #print. The representation is buffered (as a stream of styled tokens) and truncated to avoid excessively noisy output for large subjects; colours are resolved later when the buffer is replayed into the output.
+			@inspect = Output::Variable.buffer(@subject)
 			
 			@inverted = inverted
 			@distinct = true
@@ -39,7 +39,9 @@ module Sus
 		# Print a representation of this expectation.
 		# @parameter output [Output] The output target.
 		def print(output)
-			output.write("expect ", :variable, @inspect, :reset, " ")
+			output.write("expect ")
+			output.append(@inspect)
+			output.write(" ")
 			
 			if @inverted
 				output.write("not to", :reset)

data/lib/sus/have.rb

@@ -5,6 +5,7 @@
 
 require_relative "have/all"
 require_relative "have/any"
+require_relative "output/variable"
 
 module Sus
 	# Represents predicates for checking collections and object attributes.
@@ -22,7 +23,9 @@ module Sus
 			# Print a representation of this predicate.
 			# @parameter output [Output] The output target.
 			def print(output)
-				output.write("key ", :variable, @name.inspect, :reset, " ", @predicate, :reset)
+				output.write("key ")
+				output.variable(@name)
+				output.write(" ", @predicate, :reset)
 			end
 			
 			# Evaluate this predicate against a subject.
@@ -89,7 +92,13 @@ module Sus
 				index = 0
 				
 				subject.each do |value|
-					assertions.nested("[#{index}] = #{value.inspect}", distinct: true) do |assertions|
+					# Capture the label (index and value) as a buffer of formatting
+					# instructions, so the value is truncated/styled consistently:
+					label = Output::Buffered.new
+					label.write("[#{index}] = ")
+					label.variable(value)
+					
+					assertions.nested(label, distinct: true) do |assertions|
 						@predicate&.call(assertions, value)
 					end
 					

data/lib/sus/output/buffered.rb

@@ -6,6 +6,8 @@
 require "io/console"
 require "stringio"
 
+require_relative "text"
+
 module Sus
 	module Output
 		# Represents a buffered output handler that stores output operations for later replay.
@@ -51,6 +53,14 @@ module Sus
 				@tee&.append(buffer)
 			end
 			
+			# Replay this buffer into the given output. This allows a buffer (a captured
+			# stream of formatting instructions) to be used anywhere a printable target
+			# is expected, e.g. as a nested assertion label.
+			# @parameter output [Output] The output target.
+			def print(output)
+				output.append(self)
+			end
+			
 			# @returns [String] The buffered output as a string.
 			def string
 				io = StringIO.new
@@ -99,6 +109,14 @@ module Sus
 				@tee&.puts(*arguments)
 			end
 			
+			# Write a value in the variable style: a compact, truncated representation
+			# (handling large values, recursion and styling internally).
+			# @parameter value [Object] The value to represent.
+			# @parameter limit [Integer] The maximum length of the representation.
+			def variable(value, limit: Variable::TRUNCATION_LIMIT)
+				Variable.format(self, value, limit: limit)
+			end
+			
 			# Record an assertion.
 			# @parameter arguments [Array] The assertion arguments.
 			def assert(*arguments)

data/lib/sus/output/text.rb

@@ -139,6 +139,14 @@ module Sus
 				write(*arguments)
 				@io.puts(self.reset)
 			end
+			
+			# Write a value in the variable style: a compact, truncated representation
+			# (handling large values, recursion and styling internally).
+			# @parameter value [Object] The value to represent.
+			# @parameter limit [Integer] The maximum length of the representation.
+			def variable(value, limit: Variable::TRUNCATION_LIMIT)
+				Variable.format(self, value, limit: limit)
+			end
 		end
 	end
 end

data/lib/sus/output/variable.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "buffered"
+
+module Sus
+	module Output
+		# Provides a compact, truncated representation of values for output.
+		#
+		# Rather than building a full `inspect` string and then truncating it, we walk
+		# the value and stream tokens directly into an output, aborting as soon as a
+		# character budget is exhausted. This means we never materialize the full
+		# representation of a large subject (e.g. a big array or richly inspected
+		# instance).
+		#
+		# Containers (arrays and hashes) are formatted directly so we can recurse with
+		# the budget; leaf values delegate to native `inspect` so their formatting
+		# exactly matches Ruby. The value itself is emitted in a single style (matching
+		# the rest of sus's output), and only the truncation ellipsis is highlighted
+		# distinctly so it's clear where output was cut.
+		module Variable
+			# The maximum length of an inspected value before it is truncated. Override
+			# it with the `SUS_OUTPUT_VARIABLE_TRUNCATION_LIMIT` environment variable; a
+			# value of `0` (or `nil`) disables truncation entirely.
+			TRUNCATION_LIMIT = ENV.fetch("SUS_OUTPUT_VARIABLE_TRUNCATION_LIMIT", 100).then do |value|
+				value = Integer(value)
+				value.zero? ? nil : value
+			end
+			
+			# The string appended to a truncated value.
+			ELLIPSIS = "…"
+			
+			# Walks a value and emits styled tokens to an output, aborting once the
+			# character budget is exhausted.
+			class Formatter
+				# Raised internally to abort formatting once the limit is reached.
+				class Truncated < StandardError
+				end
+				
+				# @parameter output [Output] The output target to write tokens to.
+				# @parameter limit [Integer] The maximum number of characters to emit.
+				def initialize(output, limit:)
+					@output = output
+					@remaining = limit
+					@seen = nil
+				end
+				
+				# Emit a token in the variable style, truncating and aborting once the
+				# budget is exceeded.
+				# @parameter text [String] The token text to emit.
+				def emit(text)
+					truncated = false
+					
+					if text.length > @remaining
+						text = text[0, @remaining]
+						truncated = true
+					end
+					
+					@remaining -= text.length
+					
+					@output.write(:variable, text, :reset)
+					
+					raise Truncated if truncated
+				end
+				
+				# Format a value, emitting styled tokens to the output.
+				# @parameter value [Object] The value to format.
+				def format(value)
+					case value
+					when String
+						# Inspect only a prefix so we never escape a huge string:
+						slice = value.length > @remaining ? value[0, @remaining] : value
+						emit(slice.inspect)
+					when Array
+						format_array(value)
+					when Hash
+						format_hash(value)
+					else
+						format_object(value)
+					end
+				end
+				
+				private
+				
+				def format_array(array)
+					if @seen&.key?(array.object_id)
+						return emit("[...]")
+					end
+					
+					(@seen ||= {})[array.object_id] = true
+					
+					begin
+						emit("[")
+						array.each_with_index do |element, index|
+							emit(", ") if index > 0
+							format(element)
+						end
+						emit("]")
+					ensure
+						@seen.delete(array.object_id)
+					end
+				end
+				
+				def format_hash(hash)
+					if @seen&.key?(hash.object_id)
+						return emit("{...}")
+					end
+					
+					(@seen ||= {})[hash.object_id] = true
+					
+					begin
+						emit("{")
+						first = true
+						hash.each do |key, value|
+							emit(", ") unless first
+							first = false
+							
+							if key.is_a?(Symbol)
+								# Label form for symbol keys, e.g. `key: value`:
+								emit("#{key.inspect.delete_prefix(":")}: ")
+							else
+								format(key)
+								emit(" => ")
+							end
+							
+							format(value)
+						end
+						emit("}")
+					ensure
+						@seen.delete(hash.object_id)
+					end
+				end
+				
+				def format_object(value)
+					emit(value.inspect)
+				rescue Truncated
+					raise
+				rescue => error
+					emit("#<#{value.class} (inspect failed: #{error.class})>")
+				end
+			end
+			
+			# Format a value into the given output, truncating at the limit.
+			# @parameter output [Output] The output target.
+			# @parameter value [Object] The value to format.
+			# @parameter limit [Integer] The maximum length of the representation.
+			def self.format(output, value, limit: TRUNCATION_LIMIT)
+				# With no limit, the formatter would produce exactly `value.inspect`, so
+				# we can skip walking the value and emit it directly:
+				unless limit
+					return output.write(:variable, value.inspect, :reset)
+				end
+				
+				formatter = Formatter.new(output, limit: limit)
+				
+				begin
+					formatter.format(value)
+				rescue Formatter::Truncated
+					output.write(:ellipsis, ELLIPSIS, :reset)
+				end
+			end
+			
+			# Capture a value's representation into a buffer, resolving the value
+			# immediately, but deferring colour resolution until the buffer is replayed
+			# into a real output.
+			# @parameter value [Object] The value to capture.
+			# @parameter limit [Integer] The maximum length of the representation.
+			# @returns [Buffered] A buffer containing the captured representation.
+			def self.buffer(value, limit: TRUNCATION_LIMIT)
+				buffer = Buffered.new
+				self.format(buffer, value, limit: limit)
+				return buffer
+			end
+		end
+	end
+end

data/lib/sus/output.rb

@@ -49,6 +49,10 @@ module Sus
 			
 			output[:variable] = output.style(:blue, nil, :bold)
 			
+			# The ellipsis marks where an inspected value was truncated; it is shown
+			# faintly so it reads as "trailing off" without competing with the value.
+			output[:ellipsis] = output.style(nil, nil, :faint)
+			
 			output[:path] = output.style(:yellow)
 			output[:line] = output.style(:yellow)
 			output[:identity] = output.style(:yellow)

data/lib/sus/raise_exception.rb

@@ -8,7 +8,7 @@ module Sus
 	class RaiseException
 		# Initialize a new RaiseException predicate.
 		# @parameter exception_class [Class] The exception class to expect.
-		# @parameter message [String, Regexp, Object | Nil] Optional message matcher.
+		# @parameter message [String | Regexp | Object | Nil] Optional message matcher.
 		def initialize(exception_class = Exception, message: nil)
 			@exception_class = exception_class
 			@message = message
@@ -68,7 +68,7 @@ module Sus
 	class Base
 		# Create a predicate that checks if a block raises an exception.
 		# @parameter exception_class [Class] The exception class to expect.
-		# @parameter message [String, Regexp, Object | Nil] Optional message matcher.
+		# @parameter message [String | Regexp | Object | Nil] Optional message matcher.
 		# @returns [RaiseException] A new RaiseException predicate.
 		def raise_exception(...)
 			RaiseException.new(...)

data/lib/sus/respond_to.rb

@@ -49,7 +49,8 @@ module Sus
 			# Print a representation of this constraint.
 			# @parameter output [Output] The output target.
 			def print(output)
-				output.write("with options ", :variable, @options.inspect)
+				output.write("with options ")
+				output.variable(@options)
 			end
 			
 			# Evaluate this constraint against method parameters.

data/lib/sus/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Sus
-	VERSION = "0.36.0"
+	VERSION = "0.37.0"
 end

data/lib/sus.rb

@@ -6,6 +6,7 @@
 require_relative "sus/version"
 require_relative "sus/config"
 require_relative "sus/registry"
+require_relative "sus/output/variable"
 require_relative "sus/assertions"
 require_relative "sus/tree"
 

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.37.0
+
+  - Long values in verbose (and failure) output are now truncated to a configurable length (default 100 characters), preventing huge objects from flooding the output. Set the `SUS_OUTPUT_VARIABLE_TRUNCATION_LIMIT` environment variable to change the limit, or `0` to disable truncation.
+
 ### v0.36.0
 
   - Hard code `XTerm` output for GitHub Actions, as it supports ANSI escape codes.
@@ -57,6 +61,7 @@ Please see the [project releases](https://socketry.github.io/sus/releases/index)
 ## See Also
 
   - [sus-vscode](https://github.com/socketry/sus-vscode) - Visual Studio Code extension for Sus.
+  - [minitest-sus](https://github.com/socketry/minitest-sus) - Use Sus fixtures within Minitest tests.
 
 ## Contributing
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.37.0
+
+  - Long values in verbose (and failure) output are now truncated to a configurable length (default 100 characters), preventing huge objects from flooding the output. Set the `SUS_OUTPUT_VARIABLE_TRUNCATION_LIMIT` environment variable to change the limit, or `0` to disable truncation.
+
 ## v0.36.0
 
   - Hard code `XTerm` output for GitHub Actions, as it supports ANSI escape codes.

data.tar.gz.sig

@@ -1 +1,4 @@
-��Hk��r�YikJ
+#�l~���ͬ�[�WE�P�,9��q���5���-� ��I�sՁ��Hk\n���֍H1fS Ldz���70�=��^�]Ӏ��£���1g2-~.p/U\�O�V��̺հ���>�����3�/�d ��J��P�֮B�ѐ{���p{�E�r��V�j��r(��0	@���@�ڂ!���ֈ��jumО�=VU��R�L�yuf2Q����c�*$5�	������"��<���M&A
�{ev�
+TS%�)iiLN���ɶ��bD�G3���O�:�+B����e�#�"�z��'���,*-;�|L�v6x��w3I��	!Ҝ��^t���k�*���p�c�?l@o�) �_
+
+2�:�R�=C9=��y�$�i[��j��L�b^r���s���<

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -93,6 +93,7 @@ files:
 - lib/sus/output/status.rb
 - lib/sus/output/structured.rb
 - lib/sus/output/text.rb
+- lib/sus/output/variable.rb
 - lib/sus/output/xterm.rb
 - lib/sus/raise_exception.rb
 - lib/sus/receive.rb
@@ -126,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A fast and scalable test runner.
 test_files: []