minitest-memory 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ebf51378aad65a92a5563045128674d105040e0c8c6a923d8f94aea5a47099c
-  data.tar.gz: 4c3ac6868a00e6b00e47e4ccd96bb0d69ad275e3aa7d7287fdd0036c7d4c6f8d
+  metadata.gz: 1e0dd689600ea1bb57af6388a94015c3bf9ec9dcfc737aa26967a822e005cde0
+  data.tar.gz: 1d9059075cd6a38d425cb32adcdac88528dcfa3dcfb4421b21776c94910feee9
 SHA512:
-  metadata.gz: 23abb466ddad6de511d47c7d77a84a61c60f362cb815115a711f120ae59ba2920129644beee0d29fc4943ec55170aa152335a796444d4bd18f203c2ab95a4ed6
-  data.tar.gz: dda3dd7ebefb5aafe8f1225ea9760a194fb4cd951921c0566a0d32ef6c5acb65ee2372d2de4a388cc624da22c3eaf503aa40fd35dbfa0b916faa3c51e24ee26a
+  metadata.gz: cce664e89b49ec5493d47254b07cdae98eb0496f86fb8795c9eb800ed04953e63455619ed63c5ffdb106985b9915c7851a91b41732038afbf692d21340dc2194
+  data.tar.gz: 74af65dfaf4c69b13c5e10122c497755d3af225e24440192254a0422379f6e9a21666d048675c183e911a3a6ddc738d1051d7e4d5de5ac971b42745770d4e40b

data/CHANGELOG.md

@@ -2,12 +2,40 @@
 
 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/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.1.1] - 2026-10-20
+
+### Fixed
+
+- The gem now includes its RBS type signatures (`sig/minitest-memory.rbs`), which were left out of the package
+- Loading on JRuby, whose `objspace` has no `ObjectSpace.memsize_of` (the gem raised `NoMethodError` as it loaded)
+- Where allocations can't be traced (JRuby, TruffleRuby), assertions now run their block (they used to skip it) and then skip the test, instead of failing limits that expect allocations or passing without checking anything
+
+## [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
 
 - `Minitest::Memory::AllocationCounter.count` — counts object allocations by class within a block
 - `assert_allocations` — fails if any class exceeds its allocation limit within a block
+
+[Unreleased]: https://github.com/sferik/minitest-memory/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/sferik/minitest-memory/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/sferik/minitest-memory/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/sferik/minitest-memory/releases/tag/v1.0.0

data/README.md

@@ -11,6 +11,16 @@ Add to your Gemfile:
 gem "minitest-memory"
 ```
 
+## Supported Rubies
+
+minitest-memory requires Ruby 3.2 or later. Counting allocations relies on
+CRuby's `ObjectSpace` allocation tracing, so it works only on CRuby.
+
+On JRuby and TruffleRuby, allocations can't be counted. The assertions and
+expectations still run their block, then skip the test, so the test run
+shows that nothing was checked instead of passing. Because a skip ends the
+test, any assertions after it in the same test don't run on those Rubies.
+
 ## Usage
 
 Include `Minitest::Memory` in your test class, then use `assert_allocations`
@@ -37,7 +47,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 +158,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.1".freeze
   end
 end

data/lib/minitest/memory.rb

@@ -1,4 +1,10 @@
-require "objspace"
+# :nocov:
+begin
+  require "objspace"
+rescue LoadError
+  # objspace is not available on JRuby
+end
+# :nocov:
 require "minitest/strict"
 require_relative "memory/version"
 
@@ -14,47 +20,403 @@ 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.
+      # :nocov:
+      SLOT_SIZE =
+        if ObjectSpace.respond_to?(:memsize_of)
+          ObjectSpace.memsize_of(Object.new)
+        else
+          0
+        end
+      # :nocov:
+
+      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?
+        return false if RUBY_ENGINE == "truffleruby" # simplecov:disable
+
+        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, &)
+        return untraced(&) unless supported?
+
         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+.
+      # Runs the block where allocations can't be traced, returning an
+      # empty Result.
 
-      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.untraced
+        yield # steep:ignore InsufficientPositionalArguments
+        Result.new({}, {}, EMPTY)
       end
+      private_class_method :untraced
+
+      ##
+      # Tallies one object's count and byte size into both the
+      # +total+ and per-class +bucket+ entries.
+
+      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)
+        return unless file # simplecov:disable
+
+        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(&)
+      skip_untraced(&) unless AllocationCounter.supported?
+
+      klasses = limits.keys.grep(Module)
+      has_total_limit = limits.key?(:count) || limits.key?(:size)
+      result = AllocationCounter.count(klasses, &)
+
+      check_limits(limits, result)
+      check_unspecified(result) unless has_total_limit
+    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, &)
+      skip_untraced(&) unless AllocationCounter.supported?
+
+      klasses = limits.keys.grep(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, &)
+      skip_untraced(&) unless AllocationCounter.supported?
+
+      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, &)
+      skip_untraced(&) unless AllocationCounter.supported?
 
-      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
+      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
+      Minitest::Expectation.include(Expectations) if defined?(Minitest::Expectation) # simplecov:disable
+    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
+
+    ##
+    # Runs the block where allocations can't be traced (JRuby,
+    # TruffleRuby), then skips the test: nothing was checked, so it
+    # shouldn't pass.
+
+    def skip_untraced
+      yield # steep:ignore InsufficientPositionalArguments
+      skip "Allocations can't be traced on #{RUBY_ENGINE}"
+    end
+
+    ##
+    # Fails for allocations of classes +limits+ didn't name (when it set
+    # no total limit).
+
+    def check_unspecified(result)
+      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
+
+    ##
+    # Checks all +limits+ entries against +result+. Routes +:count+
+    # and +:size+ to total-limit checks, and Module keys to
+    # per-class checks.
+
+    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

data/sig/minitest-memory.rbs

@@ -0,0 +1,128 @@
+module Minitest
+  module Memory
+    VERSION: String
+
+    class AllocationCounter
+      class Allocation < ::Struct[Integer]
+        attr_accessor count: Integer
+        attr_accessor size: Integer
+        attr_accessor sources: Hash[String, Integer]
+
+        def self.new: (Integer count, Integer size, Hash[String, Integer] sources) -> instance
+      end
+
+      class Result < ::Struct[untyped]
+        attr_accessor allocated: Hash[untyped, Allocation]
+        attr_accessor ignored: Hash[untyped, Allocation]
+        attr_accessor total: Allocation
+
+        def self.new: (Hash[untyped, Allocation] allocated, Hash[untyped, Allocation] ignored, Allocation total) -> instance
+      end
+
+      SLOT_SIZE: Integer
+      EMPTY: Allocation
+
+      # Returns false on TruffleRuby, true otherwise.
+      def self.supported?: () -> bool
+
+      # Counts allocations by class within a block.
+      def self.count: (?Array[Module] klasses) { (untyped) -> untyped } -> Result
+
+      # Counts retained allocations by class within a block.
+      def self.count_retained: (?Array[Module] klasses) { (untyped) -> untyped } -> Result
+
+      # Returns a Result of allocations from a given generation.
+      def self.count_allocations: (Integer generation, ?Array[Module] klasses) -> Result
+
+      private
+
+      # Traces object allocations within a block.
+      def self.trace: (Array[Module] klasses, ?retain: bool) { (untyped) -> untyped } -> Result
+
+      # Runs the block where allocations can't be traced; returns an empty Result.
+      def self.untraced: () { (untyped) -> untyped } -> Result
+
+      # Tallies one object's count and byte size into total and bucket.
+      def self.tally: (untyped obj, Allocation total, Allocation bucket) -> void
+
+      # Records the source location of obj into total and bucket source hashes.
+      def self.record_source: (untyped obj, Allocation total, Allocation bucket) -> void
+
+      # Finds or creates the Allocation entry for obj.
+      def self.bucket_for: (untyped obj, Array[Module] klasses, Hash[untyped, Allocation] allocated, Hash[untyped, Allocation] ignored) -> Allocation
+
+      # Creates a new zeroed Allocation with a default-value sources hash.
+      def self.new_allocation: () -> Allocation
+    end
+
+    include Minitest::Assertions
+
+    type allocation_count_limit = Integer | Range[Integer]
+    type allocation_limit = allocation_count_limit | Hash[Symbol, allocation_count_limit]
+
+    # Includes Expectations into Minitest::Expectation when minitest/spec is loaded.
+    def self.included: (Module base) -> void
+
+    # Fails if any class in limits exceeds its allocation limit.
+    def assert_allocations: (Hash[untyped, allocation_limit] limits) { (untyped) -> untyped } -> void
+
+    # Fails if any class in limits exceeds its retention limit.
+    def assert_retentions: (Hash[untyped, allocation_limit] limits) { (untyped) -> untyped } -> void
+
+    # Fails if any of the given classes are allocated within a block.
+    def refute_allocations: (*Class classes) { (untyped) -> untyped } -> void
+
+    # Fails if any of the given classes are retained within a block.
+    def refute_retentions: (*Class classes) { (untyped) -> untyped } -> void
+
+    # Minitest::Spec expectations for memory allocation assertions.
+    module Expectations
+      # The test context from Minitest::Expectation.
+      def ctx: () -> untyped
+
+      # The target value or block from Minitest::Expectation.
+      def target: () -> untyped
+
+      # See Minitest::Memory#assert_allocations.
+      def must_limit_allocations: (Hash[untyped, allocation_limit] limits) -> void
+
+      # See Minitest::Memory#assert_retentions.
+      def must_limit_retentions: (Hash[untyped, allocation_limit] limits) -> void
+
+      # See Minitest::Memory#refute_allocations.
+      def wont_allocate: (*Class classes) -> void
+
+      # See Minitest::Memory#refute_retentions.
+      def wont_retain: (*Class classes) -> void
+    end
+
+    private
+
+    # Runs the block where allocations can't be traced, then skips the test.
+    def skip_untraced: () { (untyped) -> untyped } -> bot
+
+    # Fails for allocations of classes the limits didn't name.
+    def check_unspecified: (AllocationCounter::Result result) -> void
+
+    # Checks all limits entries against result.
+    def check_limits: (Hash[untyped, allocation_limit] limits, AllocationCounter::Result result, ?metric: String, ?size_metric: String) -> void
+
+    # Dispatches a single limit entry for the given klass against the result.
+    def check_limit_entry: (untyped klass, allocation_limit limit, AllocationCounter::Result result, metric: String, size_metric: String) -> void
+
+    # Checks a total :count or :size limit against the aggregate total allocation.
+    def check_total_limit: (:count | :size klass, allocation_count_limit limit, AllocationCounter::Allocation total, size_metric: String) -> void
+
+    # Checks per-class limit against allocation for the given klass.
+    def check_class_limit: (untyped klass, AllocationCounter::Allocation allocation, allocation_limit limit, metric: String, size_metric: String) -> void
+
+    # Asserts that actual falls within limit for the given klass and metric.
+    def check_limit: (untyped klass, allocation_count_limit limit, Integer actual, ?metric: String, sources: Hash[String, Integer]) -> void
+
+    # Asserts zero allocations for each class in classes.
+    def check_zero: (AllocationCounter::Result result, Array[Class] classes, ?metric: String) -> void
+
+    # Formats allocation sources as a newline-separated list of source locations.
+    def format_sources: (Hash[String, Integer] sources) -> String
+  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.1
 platform: ruby
 authors:
 - Erik Berlin
@@ -43,8 +43,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Provides assert_allocations to verify object allocation counts within
-  a block.
+description: Assertions and expectations that limit the objects a block allocates
+  or retains, by count and size, with the source location of each allocation in failure
+  messages.
 email:
 - sferik@gmail.com
 executables: []
@@ -56,6 +57,7 @@ files:
 - README.md
 - lib/minitest/memory.rb
 - lib/minitest/memory/version.rb
+- sig/minitest-memory.rbs
 homepage: https://sferik.github.io/minitest-memory
 licenses:
 - MIT
@@ -79,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Memory allocation assertions for Minitest
 test_files: []