minitest-markdown 0.0.0.pre → 0.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d1ee2803d0dd9c5009efdbfb7510395c875617f325d9f506b3e6f5dcf011565
-  data.tar.gz: 39534d84dbfdef4d58e1c55e9e5479e3b9d697637cd04dd82a75b3e2892b57c2
+  metadata.gz: 9d404e86afc3911d3c33f3c6db07e8895fcba5dca70490ceebe23d7e419f18fd
+  data.tar.gz: 6943203dde54269f4c4b4932d0aca354fc6a90b9531ca587956cdc6f90bb4686
 SHA512:
-  metadata.gz: 1703b4fe13cd34c08c999dfc5dbbe8a5cd85a439e9411b3c645575424d0df365798c85745707c275dd59e750ff34eb1ee67ec30724d4f45700d78f66c297a59e
-  data.tar.gz: fc492517b52b8c6542d444dba33f2b5c0f532c156b19d6d2c336a0f11e3bf6ee717aab2652334b7a2f37ecce1cbb6cbfbbe56a9affa25e06339cffa60213edb3
+  metadata.gz: 8975c4e35527de62d85c8e92298fe67789ae74e1dcec8b39f2d3edf0527d78ea40ab995b8a08c6e5c303acb2b9bcb2957986a24d225a0f6003e438efdee46671
+  data.tar.gz: 92578fe079a4cf4d90e5b74a3dc629b0517dbae6bdd0a08c236d9ce0f2b6ddb7fa36f380a315165006e2a3e5637b3d8bca5604d52124b0a2275c44bc26880695

data/.rubocop.yml

@@ -1,5 +1,5 @@
 ---
-require:
+plugins:
   - rubocop-minitest
   - rubocop-performance
   - rubocop-rake
@@ -7,6 +7,9 @@ require:
 AllCops:
   TargetRubyVersion: 3.1
   NewCops: enable
+  Exclude:
+    - 'vendor/**/*'  # GitLab caching..
+    - test/fixtures/klass.rb
 
 Lint/InterpolationCheck:
   Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Unreleased]
 
+## [0.0.0] - 2025-05-10
+
+- Fix bug in TestCodeBlock error message
+- Add binding to Kernel.eval fixes #1
+- pass kwargs to stub methods in StubProc
+
+## [0.2.2.pre] - 2025-05-08
+
+- Improve magic comment & hook comment parsing
+- Fix bug with empty sting after magic comment
+- Fix bug in config if Bundler undefined
+
+## [0.2.1.pre] - 2025-05-07
+
+- Fix issue with require in eval
+- Fix bug in StubChain where instance was mutated after #call
+
+## [0.2.0.pre] - 2025-05-06
+
+- Add ability to pass any number of stubs to a test code block
+
+### Breaking changes
+- StubChain class replaces Stubb module see https://gitlab.com/matzfan/minitest-markdown#stubbing
+
+## [0.1.0.pre] - 2025-05-01
+
+- Add ability to pass stubs to test class
+- Add dependency; minitest-stub_any_instance 
+
+## [0.0.1.pre] - 2025-04-24
+
+- Bump minitest dep to >= 5.25.2
+- Fix 'method redefined' warning in tests
+- Fix undefined method 'assert' for module 'Minitest::Assertions' in AssertionExtensions
+- Fix bug with expected value strings with multiple spaces
+
 ## [0.0.0.pre] - 2024-09-26
 
 - Initial release

data/README.md

@@ -1,11 +1,15 @@
+[![Gem Version](https://badge.fury.io/rb/minitest-markdown.svg)](https://badge.fury.io/rb/minitest-markdown)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+
 # Minitest extension for testing Ruby code blocks in your README and other Markdown files
 
 ## \_why?
 
-Document your Gem's usage, examples etc. with fully testable code! Better still, use your README as a BDD aid and specify functionaility in your README/wiki code blocks *before* you write your code!!
+Document your Gem's usage, examples etc. with fully testable code! Better still, use your README as a BDD aid and specify functionality in your README/wiki code blocks *before* you write your code!!
 
 ## Installation
 
+
 Add the gem to the application's Gemfile:
 
 ```bash
@@ -18,6 +22,17 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install minitest-markdown
 ```
 
+## Configuration
+
+No configuration is required if you use Bundler. If not, set your `project_root` path using the setter method:
+```ruby
+@config = Minitest::Markdown.config
+# => instance_of Configuration
+
+Configuration.instance_methods(false)
+# => includes :project_root=
+```
+
 ## Usage
 
 ### In your test class
@@ -27,36 +42,42 @@ To test the Ruby blocks in your README file, create file `test_readme.rb` (for e
 require 'minitest/autorun' # or in your test_helper
 require 'minitest/markdown' # ditto
 
-class ReadmeTest < MyTest # your own subclass of Minitest::Test
+class ReadmeTest < Minitest::Test # or your own subclass of Minitest::Test
   Markdown.generate_markdown_tests(self)
 end
-# => nil
+# => truthy
 ```
 To test Ruby blocks in another Markdown file, create another test file and pass the path to your Markdown file using the `:path` keyword arg i.e. `Markdown.generate_markdown_tests(self, path: '/path/to/your/markdown/file.md')`
 
 ### In your Markdown - magic comments become assertions
 
-Each Markdown file is represented by a single test class and each Ruby block in a file becomes a test method with zero or more assertions. The syntax used is `# => ` followed by an assertion keyword. Keywords may be one of the [Minitest "assert_" assertions](https://docs.seattlerb.org/minitest/Minitest/Assertions.html) less the "assert_" prefix (refutations are not implemented at this time). If the keyword is omitted, the default assertion; `assert_equal` is used. The actual value passed to the assertion is the result of the evaluation of the Ruby code above each magic comment. The following block (a single test) includes 3 assertions:
+Each Markdown file is represented by a single test class and each Ruby block* in a file becomes a test method with zero or more assertions. Test methods are named according to their index; `test_block0`, `test_block1` etc.
+
+\*Any 'state' blocks are excluded from indexing - see State section below
+
+The syntax used for assertions is `# => ` followed by an assertion keyword. Keywords may be any one of the [Minitest "assert_" assertions](https://docs.seattlerb.org/minitest/Minitest/Assertions.html) less the "assert_" prefix (refutations are not implemented at this time). If the keyword is omitted, the default assertion; `assert_equal` is used. The actual value passed to the assertion is the result of the evaluation of the Ruby code above each magic comment. The following block (a single test) includes 6 assertions:
 ```ruby
-# the code will of course be in your lib's, but for demonstration purposes:
-class Foo
-  def bar
-    'Hello Markdown!'
-  end
-end
+File.read 'test/fixtures/klass.rb'
+# => "class Klass\n  def hello\n    'Hello Markdown!'\n  end\nend"
+
+require 'test/fixtures/klass' # a demonstration 
+# => true
 
 # ordinary comments are ignored.
 
-foo = Foo.new # inline comments are also ignored
+Klass.new # inline comments are also ignored
 # The assertion and expected value are:-
-# => instance_of Foo
+# => instance_of Klass
 
-# No keywword here, so the default assertion is used (assert_equal)
-Foo.new.bar
+# No keyword here, so the default assertion is used (assert_equal)
+Klass.new.hello
 # => 'Hello Markdown!'
 
-Foo.bar
+Klass.hello
 # => raises NoMethodError
+
+self
+# => instance_of Markdown::TestClass
 ```
 Plain old `assert` has been aliased as `assert_truthy`, so when expecting a truthy value you should do this:
 ```ruby
@@ -70,7 +91,7 @@ For convenience, the assertion `assert_includes` has also been aliased so that i
 2
 # => included_in [1, 2, 3]
 ```
-Everything on the magic comment line after the keyword, or `# => `, if one is omitted, is evaluated as Ruby code. Note: **inline comments are NOT ALLOWED on magic comment lines**. Where an assertion takes multiple positional args, these are simply separated by commas. Note that the assertion keyword itself is **not an argument**. The syntax is as follows:
+Everything on the magic comment line after the assertion keyword, or `# => ` if one is omitted, is evaluated as Ruby code. Note: **inline comments are NOT ALLOWED on magic comment lines**. Where an assertion takes multiple positional args, these are simply separated by commas. Note that the assertion keyword itself is **not an argument**. The syntax is as follows:
 ```ruby
 22/7.0
 # => in_delta Math::PI, 0.01
@@ -80,36 +101,96 @@ To skip a test, use `skip`, as you would in a regular test:
 "some code which you don't want to test yet"
 # => skip 'give a reason for the skip here'
 ```
+Test failures will look like this - note the method name `test_block10` in this example:
+```
+Minitest::Markdown::ReadmeTest#test_block10 [lib/minitest/markdown/test_class.rb:118]:
+Expected: 42
+  Actual: 0
+```
 
 ### State
 
-Minitest's `setup` and `teardown` methods are generated by using the appropriate comment on the first line of a code block. Magic comments are ignored in such blocks, as these are not tests. E.g.
+Instance vars are shared across test methods within a class, but as Minitest's default is to run tests in random order you may want to use a setup block in order to ensure a stored value is available to all test blocks (tests) in the Markdown file test class (see below):
+```ruby
+@instance_var
+# => 7
+```
+Minitest's `setup` and `teardown` methods are generated by using the appropriate comment on the first line of a code block. Assertion magic comments are ignored in such blocks, as these are not tests. E.g.
+
 ```ruby
 # setup
 
-@instance_var = 42
+# do some setup task - or:-
+@instance_var = 7 # now available in all test method blocks, including the one above
+# => ignored
 ```
-The instance var set is now available to all test blocks (tests) in the Markdown file.
 ```ruby
-@instance_var
-# => 42
+# teardown
+
+# do some teardown task
 ```
 The hook methods defined in the [minitest-hooks](https://github.com/jeremyevans/minitest-hooks?tab=readme-ov-file#in-tests-minitesttest-) extension (`before_all`, `after_all`, `around` & `around_all`)are also available in this way if `minitest-hooks` is installed and `Minitest::Hooks` is included in your test class.
 
 
-Everything in the code blocks above runs as test code. [minitest-proveit](https://github.com/seattlerb/minitest-proveit) would complain otherwise ;-)
+Everything in the Ruby code blocks above and below here runs as test code. [minitest-proveit](https://github.com/seattlerb/minitest-proveit) would complain otherwise ;-)
 
-## Configuration
+### Mocks
 
-No configuation is required if you use Bundler. If not, set your `project_root` path using the setter method:
+Mocks use the "mock" keyword for [assert_mock](https://docs.seattlerb.org/minitest/Minitest/Assertions.html#method-i-assert_mock) in place of the equivalent `mock.verify`:
 ```ruby
-@config = Markdown.config
-# => instance_of Configuration
+@mymock = Minitest::Mock.new
+@mymock.expect(:puts, nil, ['Hello World!'])
 
-Configuration.instance_methods(false)
-# => includes :project_root=
+@mymock.puts 'Hello World!'
+# => mock @mymock
+```
+
+### Stubbing
+
+It is possible to pass stubs to the generated tests. This is done using the stubs keyword. Hash keys represent the index of the test code block. **Important: any 'state' blocks are ignored for test code block indexing**. The hash value must be an instance of `Minitest::StubChain` which holds a proc for each stub in the chain. For convenience `StubChain.stubproc` returns a suitable stub proc object which is called around the relevant test code. Zero or more of these reusable procs can be used to instantiate a StubChain object:
+```ruby
+class MarkdownTest < Minitest::Test
+  set_stubs_new = Minitest::StubChain.stubproc(Set, :new, []) # returns a proc which stubs Set.new to return an empty array
+  array_stubs_size = Minitest::StubChain.stubproc(Array, :size, 42, any_instance: true) # uses the bundled minitest-stub_any_instance gem
+
+  stub_chain = Minitest::StubChain.new([set_stubs_new]) # initialized with zero or more stub procs
+  stub_chain.stubs << array_stubs_size # add another like this if need be
+
+  stubs = {}
+  stubs[10] = stub_chain
+  stubs[11] = stub_chain # StubChain instances themselves may be reused
+
+  Markdown.generate_markdown_tests(self, stubs: stubs)
+end
+# => truthy
+```
+The 2 stubs in the `StubChain` instance above are demonstrated in the following example:
+```ruby
+# This is test_block10
+Set.new([1, 'c', :s]).size
+# => 42
+
+# Because we added `stubs[10] = stub_chain` above, this is exactly equivalent to:
+#
+# def test_block10
+#   Set.stub(:new, []) do
+#     Array.stub_any_instance(:size, 42) do
+#       assert_equal 42, Set.new([1, 'c', :s]).size
+#     end
+#   end
+# end
+```
+Example showing the reuse of a StubChain:
+```ruby
+# This is test_block11
+Set.new.size
+# => 42
 ```
 
+### Errors
+
+All errors subclass `Markdown::Error`
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -118,7 +199,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/minitest-markdown. Please checkout a suitably named branch before submitting a PR.
+Bug reports and pull requests are welcome on GitLab at https://gitlab.com/matzfan/minitest-markdown. Please checkout a suitably named branch before submitting a PR.
 
 ## License
 

data/lib/minitest/assertions_extensions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'minitest/assertions'
+
 module Minitest
   # patch
   module Assertions
@@ -7,11 +9,11 @@ module Minitest
     alias assert_included_in assert_includes
 
     # extensions
-    module AssertionExtensions
+    module AssertionsExtensions
       WITH_BLOCK_EVAL = %i[assert_output assert_pattern assert_raises assert_silent assert_throws refute_pattern].freeze
       EXPECTED_ACTUAL_REVERSED = %i[assert_includes assert_operator assert_predicate assert_respond_to].freeze
     end
 
-    Assertions.prepend AssertionExtensions
+    Assertions.prepend AssertionsExtensions
   end
 end

data/lib/minitest/markdown/configuration.rb

@@ -2,29 +2,32 @@
 
 require 'pathname'
 
-require_relative 'error'
+require_relative 'errors'
 
 module Minitest
   module Markdown
     # configuration for gem
     class Configuration
-      attr_accessor :project_root, :prove_it
+      PROJECT_ROOT_UNDETERMINED = "Project root can't be determined, set with 'Markdown.config.project_root = /path'"
+
+      attr_writer :project_root
+      attr_accessor :prove_it
 
       def initialize
-        @project_root = determine_project_root
+        @project_root = self.class.determine_project_root
         @prove_it = true
       end
 
-      def readme_path
-        project_root.join 'README.md'
+      def self.determine_project_root
+        Bundler.root if defined? Bundler
       end
 
-      private
-
-      def determine_project_root
-        return Bundler.root if defined? Bundler
+      def project_root
+        @project_root || (raise Error, PROJECT_ROOT_UNDETERMINED)
+      end
 
-        raise Error::MarkdownError, "Project root can't be determined, set with 'Config.project_root = /root/path'"
+      def readme_path
+        project_root.join 'README.md'
       end
     end
   end

data/lib/minitest/markdown/{error.rb → errors.rb}

@@ -2,8 +2,6 @@
 
 module Minitest
   module Markdown
-    module Error
-      class MarkdownError < StandardError; end
-    end
+    class Error < StandardError; end
   end
 end

data/lib/minitest/markdown/ruby_code_block.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'minifyrb'
+
+require_relative '../assertions_extensions' # for assert_truthy
+require_relative '../markdown/errors'
+
+module Minitest
+  module Markdown
+    # A Ruby code block representing test code, with 0 or more assertions or a 'state' block
+    class RubyCodeBlock
+      ASSERT_ = 'assert_'
+      ASSERT_REGEXP = /\A#{ASSERT_}/
+      SKIP = { skip: :skip }.freeze
+      DEFAULT_ASSERTION = :assert_equal
+
+      ASSERTION_KEYS = %i[ruby assertion test_args].freeze
+
+      HOOK_METHODS      = %i[before_all after_all around around_all].freeze # minitest-hooks extension
+      STATE_METHODS     = %i[setup teardown].freeze
+      STATE_BLOCK_TYPES = Minitest.const_defined?(:Hooks) ? STATE_METHODS + HOOK_METHODS : STATE_METHODS
+
+      MAGIC_COMMENT_REGEXP      = /^\s*#\s*=>.*$/
+      MAGIC_COMMENT_SCAN_REGEXP = /^\s*#\s*=>\s*(.*)$/ # strips delimiter prefix
+
+      MISSING_ASSERTION_OR_VALUE = "Magic comment missing assertion or value. Something must follow '# =>'"
+
+      attr_reader :fenced_block_str
+
+      def self.asserts
+        @asserts ||= Assertions.instance_methods.grep(ASSERT_REGEXP) - [:assert_send] # deprecated
+      end
+
+      def self.assertions_map
+        @assertions_map ||= asserts.inject(SKIP) { |memo, m| memo.merge(m.to_s.split(ASSERT_)[1..].join.to_sym => m) }
+      end
+
+      def initialize(fenced_block_str)
+        @fenced_block_str = fenced_block_str
+      end
+
+      def type
+        STATE_BLOCK_TYPES.each { |type| return type if fenced_block_str.lines.first&.match?(/^\s*#\s*#{type}\s*\n$/) }
+
+        :test
+      end
+
+      def assertions
+        assertions_arr.map { |arr| Hash[*ASSERTION_KEYS.zip(arr).flatten] }
+      end
+
+      private
+
+      def assertions_arr
+        code_strings.zip(magic_comments.map { |s| parse(s) }).map(&:flatten)
+      end
+
+      def parse(magic_comment_string)
+        raise ArgumentError, MISSING_ASSERTION_OR_VALUE if magic_comment_string.strip.empty?
+
+        assertion = parse_assertion(magic_comment_string)
+        return [DEFAULT_ASSERTION, "[#{magic_comment_string}]"] if assertion.nil?
+        return [assertion, '[]'] if magic_comment_string.split.size == 1
+
+        [assertion, "[#{magic_comment_string.sub(/#{assertion.to_s.sub(ASSERT_, '')}\s+/, '')}]"]
+      end
+
+      def parse_assertion(str)
+        self.class.assertions_map[str.split.first.to_sym] # 'nil' => :assert_nil, but 'nil?' => nil
+      end
+
+      def magic_comments
+        @fenced_block_str.scan(MAGIC_COMMENT_SCAN_REGEXP).flatten
+      end
+
+      def code_strings
+        @fenced_block_str.split(MAGIC_COMMENT_REGEXP).map do |str|
+          Minifyrb::Minifier.new(str).minify.strip
+        rescue SyntaxError
+          raise Error, "Syntax error in:\n\n#{str}"
+        end
+      end
+    end
+  end
+end

data/lib/minitest/markdown/test_class.rb

@@ -1,75 +1,88 @@
 # frozen_string_literal: true
 
 require_relative '../assertions_extensions'
-require_relative 'test_code_block'
+require_relative 'ruby_code_block'
+
+$LOAD_PATH << '.' # fix #2
 
 module Minitest
   module Markdown
-    # knows how to build a markdown test
+    # knows how to build a markdown test class, test methods and 'state' methods
     class TestClass
-      FENCED_BLOCK_REGEXP = /^```ruby\n(.*?)\n```/m # TODO: use Lexer/RDoc::Parser? which can deal with md comments
-      HOOK_METHODS = %i[before_all after_all around around_all].freeze # minitest-hooks extension
-      NON_TEST_METHODS = %i[setup teardown].freeze
+      FENCED_BLOCK_REGEXP = /^```ruby\n(.*?)\n```/m
+
+      BAD_KLASS = 'TestClass must be instantiated with Minitest::Test or subclass thereof'
+      BAD_PATH  = 'Path does not exist, is not readable or is not a Markdown file:'
+      MD        = '.md'
+
+      HOOK_METHODS_BEFORE = %i[before_all].freeze
+      HOOK_METHODS_AFTER  = %i[after_all around around_all].freeze
 
       attr_reader :klass, :path
 
       def initialize(klass, path: nil)
-        @klass = klass
-        @config = Markdown.config
-        @path = path || @config.readme_path
-        @ruby_blocks = parse_ruby_blocks
+        @klass = validate_class klass
+        @path = validate_path path
+        @state_methods_defined = []
       end
 
-      def define_methods
-        define_non_test_methods
-        @ruby_blocks.each_with_index { |block, i| define_test_method(block, i) }
-        nil
+      def define_methods(stubs: {})
+        i = 0
+        parse_ruby_blocks.each do |block|
+          next define_non_test_method(block) unless block.type == :test
+
+          define_test_method(block, i, stub_chain: stubs[i])
+          i += 1
+        end
       end
 
       private
 
-      def parse_ruby_blocks
-        File.new(path).read.scan(FENCED_BLOCK_REGEXP).flatten.map { |str| TestCodeBlock.new(str) }
+      def validate_class(klass)
+        raise ArgumentError, BAD_KLASS unless klass.respond_to?(:ancestors) && klass.ancestors.include?(Minitest::Test)
+
+        klass
       end
 
-      def define_non_test_methods
-        recognized_non_test_methods.each { |name| define_non_test_method(name, parse_non_test_method_block(name)) }
+      def validate_path(pth)
+        return Markdown.config.readme_path if pth.nil?
+        raise ArgumentError, "#{BAD_PATH} #{pth}" unless File.exist?(pth) && File.file?(pth) && File.extname(pth) == MD
+
+        pth
       end
 
-      def recognized_non_test_methods
-        Minitest.const_defined?(:Hooks) ? NON_TEST_METHODS + HOOK_METHODS : NON_TEST_METHODS
+      def parse_ruby_blocks
+        File.new(path).read.scan(FENCED_BLOCK_REGEXP).flatten.map { |str| RubyCodeBlock.new(str) }
       end
 
-      def define_non_test_method(type, block)
-        return unless block
+      def define_non_test_method(block)
+        type = block.type
+        raise Error, "State method: #{type} is already defined" if @state_methods_defined.include? type
 
         bind = binding
         klass.define_method(type) do
-          super() if type == :before_all
-          bind.eval(block)
-          super() if %i[after_all around around_all].include? type
+          super() if HOOK_METHODS_BEFORE.include? type
+          bind.eval(block.fenced_block_str)
+          super() if HOOK_METHODS_AFTER.include? type
         end
+        @state_methods_defined << type
       end
 
-      def parse_non_test_method_block(type)
-        blocks = @ruby_blocks.map.select { |blk| blk.fenced_block_str.lines.first == "# #{type}\n" }
-        return if blocks.empty?
-        raise Error::MarkdownError, "Multiple #{type} blocks are not allowed" if blocks.size > 1
-
-        @ruby_blocks.delete(blocks.first).fenced_block_str # hook method blocks can't be test methods
-      end
-
-      def define_test_method(block, meth_index)
+      def define_test_method(block, meth_index, stub_chain:)
+        stub_chain ||= StubChain.new
         instance = self # scope
         klass.define_method(:"test_block#{meth_index}") do
-          block.assertions.each { |assertion_hash| instance.send(:evaluation_assertions, assertion_hash, binding) }
+          test_code_proc = proc do
+            block.assertions.each { |assertion_hash| instance.send(:evaluation_assertions, assertion_hash, binding) }
+          end
+          stub_chain.call(test_code_proc)
         end
       end
 
       def evaluation_assertions(assertion_hash, bind)
-        ruby, assertion, args = TestCodeBlock::ASSERTION_KEYS.map { |key| assertion_hash[key] } # order dep
+        ruby, assertion, args = RubyCodeBlock::ASSERTION_KEYS.map { |key| assertion_hash[key] } # order dep
 
-        lmbda = -> { eval(ruby) } # rubocop:disable Security/Eval # TODO: assign a binding
+        lmbda = -> { kernel_eval(ruby) }
         return unless assertion
         return eval_with_block(bind, assertion, lmbda, args) if Assertions::WITH_BLOCK_EVAL.include? assertion
 
@@ -79,20 +92,27 @@ module Minitest
       def eval_with_block(bind, assertion, actual, args)
         return bind.receiver.send(assertion, &actual) if args.empty?
 
-        bind.receiver.send(assertion, *eval(args), &actual) # rubocop:disable Security/Eval
+        bind.receiver.send(assertion, *kernel_eval(args), &actual)
       end
 
       def eval_without_block(bind, assertion, lmbda, args)
         actual = lmbda.call
         return bind.receiver.send(assertion, actual) if args == '[]'
 
-        expected, *rest = eval(args) # rubocop:disable Security/Eval
+        expected, *rest = kernel_eval(args)
         expected, actual = actual, expected if Assertions::EXPECTED_ACTUAL_REVERSED.include? assertion
         kwargs = rest.last.is_a?(Hash) ? rest.last : nil
         return bind.receiver.send(assertion, expected, actual, *rest) unless kwargs
 
         bind.receiver.send(assertion, expected, actual, *rest, **kwargs) # assert_respond_to takes a kwarg..
       end
+
+      def kernel_eval(str)
+        bind = binding
+        bind.eval str
+      rescue SyntaxError
+        raise ArgumentError, "Invalid test code, failed to parse #{str}"
+      end
     end
   end
 end

data/lib/minitest/markdown/version.rb

@@ -2,6 +2,6 @@
 
 module Minitest
   module Markdown
-    VERSION = '0.0.0.pre'
+    VERSION = '0.0.0'
   end
 end

data/lib/minitest/markdown.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
+require 'minitest/stub_any_instance'
+
+require_relative 'stub_chain'
 require_relative 'markdown/configuration'
-require_relative 'markdown/error'
+require_relative 'markdown/errors'
 require_relative 'markdown/version'
 require_relative 'markdown/test_class'
 
 module Minitest
   # namespace
   module Markdown
+    ARG_ERR = 'stubs keyword takes a hash. Keys are integers and values are StubChain instances'
+
     class << self
       def config
         @config ||= Configuration.new
@@ -17,8 +22,12 @@ module Minitest
         yield config
       end
 
-      def generate_markdown_tests(klass, path: nil)
-        TestClass.new(klass, path: path).define_methods
+      def generate_markdown_tests(klass, path: nil, stubs: {})
+        raise ArgumentError, ARG_ERR unless stubs.is_a? Hash
+        raise ArgumentError, ARG_ERR unless stubs.keys.all? { |o| o.instance_of? Integer }
+        raise ArgumentError, ARG_ERR unless stubs.values.all? { |o| o.instance_of? StubChain }
+
+        TestClass.new(klass, path: path).define_methods(stubs: stubs)
       end
     end
   end

data/lib/minitest/stub_chain.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Minitest
+  # respresentaion of zero or more stub blocks around one or more test assertions
+  class StubChain
+    NOT_CALLABLE_ERR = 'StubChain#call takes a callable argument'
+    MUST_NOT_CALL_A_BLOCK_ERR = 'StubChain#call takes a callable argument which must not call a block'
+
+    attr_reader :stubs
+
+    def initialize(stubs = [])
+      @stubs = *stubs
+    end
+
+    def self.stubproc(klass, *args, any_instance: false, **kwargs)
+      return proc { |&blk| klass.stub(*args, **kwargs) { blk.call } } unless any_instance
+
+      proc { |&blk| klass.stub_any_instance(*args, **kwargs) { blk.call } }
+    end
+
+    def call(test_code_proc)
+      validate(test_code_proc)
+      call_recursive [*stubs, test_code_proc]
+    end
+
+    private
+
+    def validate(test_code_proc)
+      raise ArgumentError, NOT_CALLABLE_ERR unless test_code_proc.respond_to?(:call)
+
+      test_code_proc
+    end
+
+    def call_recursive(call_chain)
+      prok = call_chain.shift
+      return prok.call if call_chain.empty?
+
+      prok.call { call_recursive(call_chain) }
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: minitest-markdown
 version: !ruby/object:Gem::Version
-  version: 0.0.0.pre
+  version: 0.0.0
 platform: ruby
 authors:
 - MatzFan
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minifyrb
@@ -37,6 +36,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.25'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.25.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -44,8 +46,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.25'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.25.2
+- !ruby/object:Gem::Dependency
+  name: minitest-stub_any_instance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Generates tests for Ruby code blocks in any Markdown file.
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -59,10 +77,11 @@ files:
 - lib/minitest/assertions_extensions.rb
 - lib/minitest/markdown.rb
 - lib/minitest/markdown/configuration.rb
-- lib/minitest/markdown/error.rb
+- lib/minitest/markdown/errors.rb
+- lib/minitest/markdown/ruby_code_block.rb
 - lib/minitest/markdown/test_class.rb
-- lib/minitest/markdown/test_code_block.rb
 - lib/minitest/markdown/version.rb
+- lib/minitest/stub_chain.rb
 - sig/minitest/markdown.rbs
 homepage: https://gitlab.com/matzfan/minitest-markdown
 licenses:
@@ -71,7 +90,6 @@ metadata:
   source_code_uri: https://gitlab.com/matzfan/minitest-markdown
   changelog_uri: https://gitlab.com/matzfan/minitest-markdown/-/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -86,8 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.19
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Turn your README.md Ruby code blocks into testable code.
 test_files: []

data/lib/minitest/markdown/test_code_block.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-require 'minifyrb' # DEP
-
-require_relative '../assertions_extensions' # for assert_truthy
-require_relative '../markdown/error'
-
-module Minitest
-  module Markdown
-    # A Ruby code block reprenting test code, with 0 or more assertions
-    class TestCodeBlock
-      ASSERT_ = 'assert_'
-      ASSERT_REGEXP = /\A#{ASSERT_}/
-      SKIP = { skip: :skip }.freeze
-      DEFAULT_ASSERTION = :assert_equal
-
-      ASSERTION_KEYS = %i[ruby assertion test_args].freeze
-
-      MAGIC_COMMENT_DELIMITER = '# => '
-      MAGIC_COMMENT_REGEXP = /^#{MAGIC_COMMENT_DELIMITER}.*$/
-      MAGIC_COMMENT_SCAN_REGEXP = /^#{MAGIC_COMMENT_DELIMITER}(.*)$/ # strips delimiter prefix
-
-      attr_reader :fenced_block_str
-
-      def self.asserts
-        Assertions.instance_methods.grep(ASSERT_REGEXP) - [:assert_send] # deprecated
-      end
-
-      def self.assertions_map
-        asserts.inject({}) { |memo, m| memo.merge(m.to_s.split(ASSERT_)[1..].join.to_sym => m) }.merge(SKIP)
-      end
-
-      def initialize(fenced_block_str)
-        @fenced_block_str = fenced_block_str
-      end
-
-      def assertions
-        assertions_arr.map { |arr| Hash[*ASSERTION_KEYS.zip(arr).flatten] }
-      end
-
-      private
-
-      def assertions_arr
-        code_strings.zip(magic_comments.map { |s| parse(s) }).map(&:flatten)
-      end
-
-      def parse(magic_comment_string)
-        arr = magic_comment_string.split
-        assertion = self.class.assertions_map[arr.first.to_sym]
-        assertion ? [assertion, "[#{arr[1..].join(' ')}]"] : [DEFAULT_ASSERTION, "[#{arr.join(' ')}]"] # args in []
-      end
-
-      def magic_comments
-        @fenced_block_str.scan(MAGIC_COMMENT_SCAN_REGEXP).flatten
-      end
-
-      def code_strings
-        @fenced_block_str.split(MAGIC_COMMENT_REGEXP).map do |str|
-          Minifyrb::Minifier.new(str).minify.strip
-        rescue SyntaxError
-          raise Error::MarkdownError, "Syntax error in:\n\n#{str}"
-        end
-      end
-    end
-  end
-end