minitest-memory 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ebf51378aad65a92a5563045128674d105040e0c8c6a923d8f94aea5a47099c
-  data.tar.gz: 4c3ac6868a00e6b00e47e4ccd96bb0d69ad275e3aa7d7287fdd0036c7d4c6f8d
+  metadata.gz: c37208f0d913977a738af1587640fccfef97dfa89cbcde685653b809e42463f0
+  data.tar.gz: 4889e9fa26a92c685079c12af6514d205c0b32c56bcdfdbcebae834f44801c9f
 SHA512:
-  metadata.gz: 23abb466ddad6de511d47c7d77a84a61c60f362cb815115a711f120ae59ba2920129644beee0d29fc4943ec55170aa152335a796444d4bd18f203c2ab95a4ed6
-  data.tar.gz: dda3dd7ebefb5aafe8f1225ea9760a194fb4cd951921c0566a0d32ef6c5acb65ee2372d2de4a388cc624da22c3eaf503aa40fd35dbfa0b916faa3c51e24ee26a
+  metadata.gz: 308e793bd885a60f51b1b756a7520fb38e61a5032eff3db8e8e56ed033b6b1ab12477cafd5e98c899f04ee1bc01fa1dc0950b9fc75219bcfd842a808b3db64f0
+  data.tar.gz: 9b84c7636fb559bcc634b7ed64eb8b58f48dd5ae5283eb991ab9d67f683bd175b8826a7fa604e6c5526f04911bafe4211128867b269b54c4ad3e5e43583e3955

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-03-08
+
+### Added
+
+- Allocation source locations in failure messages — when an assertion fails, the error message now includes where each allocation originated (file and line number), sorted by frequency
+- Minitest::Spec expectations — `must_limit_allocations`, `must_limit_retentions`, `wont_allocate`, and `wont_retain` (e.g. `_ { code }.must_limit_allocations(String => {count: 10})`)
+- `assert_retentions` — track retained objects that survive GC, detecting potential memory leaks (e.g. `assert_retentions(String => 0)`)
+- `refute_retentions` — fails if any of the given classes are retained after GC within a block
+- Global allocation limits — `assert_allocations` now accepts `:count` and `:size` symbol keys for total limits across all classes (e.g. `assert_allocations(count: 10)`)
+- Range-based limits — limits can be a Range (e.g. `String => 2..5`) to require allocations within a specific range, for both direct and hash-style `:count`/`:size` limits
+- `refute_allocations` — fails if any of the given classes are allocated within a block
+- Allocation size limits — `assert_allocations` now accepts hash limits with `:count` and/or `:size` keys (e.g. `String => { size: 1024 }`)
+
 ## [1.0.0] - 2026-03-06
 
 ### Added

data/README.md

@@ -37,7 +37,99 @@ class MyTest < Minitest::Test
 end
 ```
 
-It also works with `Minitest::Spec`:
+### Range limits
+
+Pass a Range to require allocations within a specific range:
+
+```ruby
+# Require between 2 and 5 String allocations
+assert_allocations(String => 2..5) { ... }
+
+# Range limits work with count and size in hashes too
+assert_allocations(String => { count: 2..5 }) { ... }
+assert_allocations(String => { size: 1024..4096 }) { ... }
+```
+
+### Size limits
+
+Pass a Hash with `:count` and/or `:size` keys to constrain total bytes
+allocated per class (beyond the base object slot size):
+
+```ruby
+# Limit total String bytes
+assert_allocations(String => { size: 1024 }) { ... }
+
+# Limit both count and size
+assert_allocations(String => { count: 2, size: 1024 }) { ... }
+
+# Count-only via hash (equivalent to String => 2)
+assert_allocations(String => { count: 2 }) { ... }
+```
+
+### Global limits
+
+Use the `:count` and `:size` symbol keys to set limits on total allocations
+across all classes:
+
+```ruby
+# Limit total object count across all classes
+assert_allocations(count: 10) { ... }
+
+# Limit total allocation bytes across all classes
+assert_allocations(size: 1024) { ... }
+
+# Limit both count and size
+assert_allocations(count: 10, size: 1024) { ... }
+
+# Ranges work too
+assert_allocations(count: 5..10) { ... }
+
+# Combine per-class and global limits
+assert_allocations(String => 2, count: 10) { ... }
+```
+
+### Retained object tracking
+
+Use `assert_retentions` to check which objects survive garbage collection,
+detecting potential memory leaks:
+
+> [!WARNING]
+> Garbage collection is disabled while the block executes. Avoid long-running
+> or memory-intensive code inside the block.
+
+```ruby
+# Limit retained String objects
+assert_retentions(String => 1) { ... }
+
+# Hash-style limits with count and size
+assert_retentions(String => { count: 1, size: 1024 }) { ... }
+
+# Range limits work too
+assert_retentions(String => 1..5) { ... }
+```
+
+Use `refute_retentions` to prevent any retained objects of the given types:
+
+```ruby
+refute_retentions(String, Array) do
+  # code that must not retain strings or arrays
+end
+```
+
+### `refute_allocations`
+
+Use `refute_allocations` to prevent any allocations of the given types:
+
+```ruby
+refute_allocations(String, Array) do
+  # code that must not allocate strings or arrays
+end
+```
+
+### Minitest::Spec
+
+It also works with `Minitest::Spec`. Include `Minitest::Memory` in your spec
+class to use both assertions and expectations:
 
 ```ruby
 require "minitest/autorun"
@@ -56,15 +148,43 @@ describe MyClass do
 end
 ```
 
+#### Expectations
+
+The following `must_*` / `wont_*` expectations are available:
+
+```ruby
+# Limit allocations per class (wraps assert_allocations)
+_ { code }.must_limit_allocations(String => 2)
+_ { code }.must_limit_allocations(String => { count: 2, size: 1024 })
+_ { code }.must_limit_allocations(String => 2..5)
+
+# Limit total allocations across all classes
+_ { code }.must_limit_allocations(count: 10)
+_ { code }.must_limit_allocations(count: 5..10, size: 1024)
+
+# Limit retained objects (wraps assert_retentions)
+_ { code }.must_limit_retentions(String => 1)
+_ { code }.must_limit_retentions(String => { count: 1, size: 1024 })
+
+# Prevent allocations of specific classes (wraps refute_allocations)
+_ { code }.wont_allocate(String, Array)
+
+# Prevent retained objects of specific classes (wraps refute_retentions)
+_ { code }.wont_retain(String, Array)
+```
+
 ## How It Works
 
 `assert_allocations` uses `ObjectSpace.trace_object_allocations` to track
 every object allocated during the block's execution. It then compares the
-counts per class against the limits you provide. If any class exceeds its
-limit, the assertion fails with a message like:
+counts and sizes per class against the limits you provide. If any class
+exceeds its limit, the assertion fails with a message that includes the
+source location of each allocation, sorted by frequency:
 
 ```
-Expected at most 0 String allocations, got 3
+Expected no String allocations, got 3
+  2× at app/models/user.rb:42
+  1× at lib/serializer.rb:18
 ```
 
 ## License

data/lib/minitest/memory/version.rb

@@ -3,6 +3,6 @@ module Minitest # :nodoc:
   # Version information for minitest-memory.
   module Memory
     # Current version of minitest-memory.
-    VERSION = "1.0.0".freeze
+    VERSION = "1.1.0".freeze
   end
 end

data/lib/minitest/memory.rb

@@ -14,47 +14,371 @@ module Minitest
     # Counts object allocations within a block using ObjectSpace.
     class AllocationCounter
       ##
-      # Counts allocations by class within a block. Returns a Hash
-      # mapping each class to its allocation count. Temporarily
+      # Tracks allocation count and total byte size for a class.
+      Allocation = Struct.new(:count, :size, :sources) # rubocop:disable Lint/StructNewOverride
+
+      ##
+      # Holds allocation counting results: +allocated+ maps matched
+      # classes to Allocations, +ignored+ maps unmatched classes,
+      # and +total+ is the aggregate Allocation across all objects.
+      Result = Struct.new(:allocated, :ignored, :total)
+
+      ##
+      # Base memory size of an empty Ruby object slot.
+      SLOT_SIZE = ObjectSpace.memsize_of(Object.new)
+
+      empty_sources = {} #: Hash[String, Integer]
+
+      ##
+      # An empty allocation with zero count and size.
+      EMPTY = Allocation.new(0, 0, empty_sources.freeze).freeze
+
+      ##
+      # Returns +false+ on TruffleRuby where ObjectSpace tracing
+      # is not supported, +true+ otherwise.
+
+      def self.supported?
+        # :nocov:
+        return false if RUBY_ENGINE == "truffleruby"
+        # :nocov:
+
+        ObjectSpace.respond_to?(:trace_object_allocations)
+      end
+
+      ##
+      # Counts allocations by class within a block. Returns a
+      # Result. When +klasses+ are given, objects are matched via
+      # +is_a?+; unmatched objects go to +ignored+. Temporarily
       # disables GC during counting.
 
-      def self.count(&)
+      def self.count(klasses = [], &)
+        trace(klasses, &)
+      end
+
+      ##
+      # Counts retained allocations by class within a block.
+      # Returns a Result. Runs GC after the block to identify
+      # objects that survive garbage collection.
+
+      def self.count_retained(klasses = [], &)
+        trace(klasses, retain: true, &)
+      end
+
+      ##
+      # Returns a Result of allocations from the given +generation+.
+      # When +klasses+ are given, objects are matched via +is_a?+
+      # and unmatched objects are tracked separately in +ignored+.
+
+      def self.count_allocations(generation, klasses = [])
+        allocated = {} #: Hash[untyped, Allocation]
+        ignored = {} #: Hash[untyped, Allocation]
+        total = new_allocation
+
+        ObjectSpace.each_object do |obj|
+          next unless ObjectSpace.allocation_generation(obj) == generation
+
+          tally(obj, total, bucket_for(obj, klasses, allocated, ignored))
+        end
+
+        Result.new(allocated, ignored, total)
+      end
+
+      ##
+      # Traces object allocations within a block, optionally
+      # running GC to identify retained objects. Returns a Result.
+
+      def self.trace(klasses, retain: false, &)
+        # :nocov:
+        return Result.new({}, {}, EMPTY) unless supported?
+        # :nocov:
+
         GC.start
         GC.disable
         generation = GC.count
         ObjectSpace.trace_object_allocations(&)
-        count_allocations generation
+        GC.start if retain
+        count_allocations(generation, klasses)
       ensure
         GC.enable
       end
+      private_class_method :trace
 
       ##
-      # Returns a Hash of allocations from the given +generation+.
+      # Tallies one object's count and byte size into both the
+      # +total+ and per-class +bucket+ entries.
 
-      def self.count_allocations generation
-        allocations = Hash.new(0)
-        ObjectSpace.each_object do |obj|
-          allocations[obj.class] += 1 if ObjectSpace.allocation_generation(obj) == generation
-        end
-        allocations
+      def self.tally(obj, total, bucket)
+        size = ObjectSpace.memsize_of(obj) - SLOT_SIZE
+        total.count += 1
+        total.size += size
+        bucket.count += 1
+        bucket.size += size
+        record_source(obj, total, bucket)
+      end
+      private_class_method :tally
+
+      ##
+      # Records the source location of +obj+ into +total+ and
+      # +bucket+ source hashes. Skips objects without source info.
+
+      def self.record_source(obj, total, bucket)
+        file = ObjectSpace.allocation_sourcefile(obj)
+        # :nocov:
+        return unless file
+        # :nocov:
+
+        source = "#{file}:#{ObjectSpace.allocation_sourceline(obj)}"
+        total.sources[source] += 1
+        bucket.sources[source] += 1
+      end
+      private_class_method :record_source
+
+      ##
+      # Finds or creates the Allocation entry for +obj+. When
+      # +klasses+ are given, matches via +is_a?+ into +allocated+
+      # or files into +ignored+.
+
+      def self.bucket_for(obj, klasses, allocated, ignored)
+        return allocated[obj.class] ||= new_allocation if klasses.empty?
+
+        klass = klasses.find { |k| obj.is_a?(k) }
+        return allocated[klass] ||= new_allocation if klass
+
+        ignored[obj.class] ||= new_allocation
+      end
+      private_class_method :bucket_for
+
+      ##
+      # Creates a new zeroed Allocation with a default-value sources hash.
+
+      def self.new_allocation
+        Allocation.new(0, 0, Hash.new(0))
       end
+      private_class_method :new_allocation
     end
 
     ##
-    # Fails if any class in +limits+ exceeds its allocation count
-    # within a block. +limits+ is a Hash mapping classes to maximum
-    # allowed allocations. Eg:
+    # Fails if any class in +limits+ does not match its allocation
+    # limit within a block. +limits+ is a Hash mapping classes to
+    # an Integer (exact count), a Range (required range), or a Hash
+    # with +:count+ and/or +:size+ keys (each an Integer or Range).
+    #
+    # Objects are matched to classes via +is_a?+, so specifying
+    # +Numeric+ captures +Integer+, +Float+, etc.
+    #
+    # Use the +:count+ and +:size+ symbol keys to set global limits
+    # across all classes. When no global limit is set, allocations
+    # of unspecified classes cause a failure (strict mode).
     #
     #   assert_allocations(String => 1) { "hello" }
+    #   assert_allocations(String => 2..5) { "hello" }
+    #   assert_allocations(String => {size: 1024}) { "hello" }
+    #   assert_allocations(count: 10) { "hello" }
+    #   assert_allocations(String => 1, count: 10) { "hello" }
 
     def assert_allocations(limits, &)
-      actual = AllocationCounter.count(&)
+      klasses = limits.keys.select { |k| k.is_a?(Module) }
+      has_total_limit = limits.key?(:count) || limits.key?(:size)
+      result = AllocationCounter.count(klasses, &)
+
+      check_limits(limits, result)
+
+      return if has_total_limit
+
+      result.ignored.each do |klass, alloc|
+        msg = "Allocated #{alloc.count} #{klass} instances, #{alloc.size} bytes, " \
+              "but it was not specified#{format_sources(alloc.sources)}"
+        flunk msg
+      end
+    end
+
+    ##
+    # Fails if any class in +limits+ exceeds its retention limit
+    # within a block. Works like +assert_allocations+ but only
+    # counts objects that survive garbage collection.
+    #
+    # *Warning:* Garbage collection is disabled while the block
+    # executes. Avoid long-running or memory-intensive code inside
+    # the block.
+    #
+    #   assert_retentions(String => 0) { "hello" }
+    #   assert_retentions(String => {count: 1, size: 1024}) { "hello" }
+
+    def assert_retentions(limits, &)
+      klasses = limits.keys.select { |k| k.is_a?(Module) }
+      result = AllocationCounter.count_retained(klasses, &)
+
+      check_limits(limits, result, metric: "retentions", size_metric: "retained bytes")
+    end
+
+    ##
+    # Fails if any of the given +classes+ are allocated within a
+    # block.
+    #
+    #   refute_allocations(String, Array) { 1 + 1 }
+
+    def refute_allocations(*classes, &)
+      check_zero(AllocationCounter.count(classes, &), classes)
+    end
+
+    ##
+    # Fails if any of the given +classes+ are retained within a
+    # block.
+    #
+    #   refute_retentions(String, Array) { 1 + 1 }
+
+    def refute_retentions(*classes, &)
+      check_zero(AllocationCounter.count_retained(classes, &), classes, metric: "retentions")
+    end
+
+    ##
+    # Includes +Expectations+ into +Minitest::Expectation+ when
+    # +minitest/spec+ is loaded, enabling the +must_*+ / +wont_*+
+    # expectation syntax.
+
+    def self.included(base) # :nodoc:
+      super
+      # :nocov:
+      Minitest::Expectation.include(Expectations) if defined?(Minitest::Expectation)
+      # :nocov:
+    end
+
+    ##
+    # Minitest::Spec expectations for memory allocation assertions.
+    # These methods are added to +Minitest::Expectation+ when
+    # +minitest/spec+ is loaded.
+    module Expectations
+      ##
+      # See Minitest::Memory#assert_allocations.
+      #
+      #   _ { code }.must_limit_allocations(String => {count: 10})
+
+      def must_limit_allocations(limits)
+        ctx.assert_allocations(limits, &target)
+      end
+
+      ##
+      # See Minitest::Memory#assert_retentions.
+      #
+      #   _ { code }.must_limit_retentions(String => 1)
+
+      def must_limit_retentions(limits)
+        ctx.assert_retentions(limits, &target)
+      end
+
+      ##
+      # See Minitest::Memory#refute_allocations.
+      #
+      #   _ { code }.wont_allocate(String, Array)
+
+      def wont_allocate(*classes)
+        ctx.refute_allocations(*classes, &target)
+      end
+
+      ##
+      # See Minitest::Memory#refute_retentions.
+      #
+      #   _ { code }.wont_retain(String, Array)
+
+      def wont_retain(*classes)
+        ctx.refute_retentions(*classes, &target)
+      end
+    end
+
+    private
+
+    ##
+    # Checks all +limits+ entries against +result+. Routes +:count+
+    # and +:size+ to total-limit checks, and Module keys to
+    # per-class checks.
 
-      limits.each do |klass, max_count|
-        count = actual[klass]
-        msg = "Expected at most #{max_count} #{klass} allocations, got #{count}"
-        assert_operator max_count, :>=, count, msg
+    def check_limits(limits, result, metric: "allocations", size_metric: "allocation bytes")
+      limits.each do |klass, limit|
+        check_limit_entry(klass, limit, result, metric: metric, size_metric: size_metric)
       end
     end
+
+    ##
+    # Dispatches a single +limit+ entry for the given +klass+
+    # against the +result+. Routes symbols to total-limit checks
+    # and Module keys to per-class checks.
+
+    def check_limit_entry(klass, limit, result, metric:, size_metric:)
+      case klass
+      when :count, :size
+        total_limit = limit #: Integer | Range[Integer]
+        check_total_limit(klass, total_limit, result.total, size_metric: size_metric)
+      when Module
+        alloc = result.allocated[klass] || AllocationCounter::EMPTY
+        check_class_limit(klass, alloc, limit, metric: metric, size_metric: size_metric)
+      end
+    end
+
+    ##
+    # Checks a total +:count+ or +:size+ limit against the
+    # aggregate +total+ allocation.
+
+    def check_total_limit(klass, limit, total, size_metric:)
+      if klass == :count
+        check_limit("total", limit, total.count, sources: total.sources)
+      else
+        check_limit("total", limit, total.size, metric: size_metric, sources: total.sources)
+      end
+    end
+
+    ##
+    # Checks per-class +limit+ against +allocation+ for the given
+    # +klass+. +limit+ may be an Integer, Range, or Hash with
+    # +:count+ and/or +:size+ keys.
+
+    def check_class_limit(klass, allocation, limit, metric:, size_metric:)
+      srcs = allocation.sources
+      if limit.is_a?(Hash)
+        check_limit(klass, limit.fetch(:count), allocation.count, metric: metric, sources: srcs) if limit.key?(:count)
+        check_limit(klass, limit.fetch(:size), allocation.size, metric: size_metric, sources: srcs) if limit.key?(:size)
+      else
+        check_limit(klass, limit, allocation.count, metric: metric, sources: srcs)
+      end
+    end
+
+    ##
+    # Asserts that +actual+ matches +limit+ for the given +klass+
+    # and +metric+. +limit+ may be an Integer (exact match) or a
+    # Range (inclusion check).
+
+    def check_limit(klass, limit, actual, sources:, metric: "allocations")
+      if limit.is_a?(Range)
+        msg = "Expected within #{limit} #{klass} #{metric}, got #{actual}#{format_sources(sources)}"
+        assert_includes limit, actual, msg
+      else
+        desc = limit.zero? ? "no" : "exactly #{limit}"
+        msg = "Expected #{desc} #{klass} #{metric}, got #{actual}#{format_sources(sources)}"
+        assert_equal limit, actual, msg
+      end
+    end
+
+    ##
+    # Asserts zero allocations for each class in +classes+.
+
+    def check_zero(result, classes, metric: "allocations")
+      classes.each do |klass|
+        alloc = result.allocated[klass] || AllocationCounter::EMPTY
+        check_limit(klass, 0, alloc.count, metric: metric, sources: alloc.sources)
+      end
+    end
+
+    ##
+    # Formats allocation +sources+ as a newline-separated list
+    # of source locations with counts, sorted by frequency.
+
+    def format_sources(sources)
+      return "" if sources.empty?
+
+      entries = sources.sort_by { |_, count| -count }.map do |source, count|
+        "  #{count}× at #{source}"
+      end
+
+      "\n#{entries.join("\n")}"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minitest-memory
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Erik Berlin