minitest-markdown 0.0.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d1ee2803d0dd9c5009efdbfb7510395c875617f325d9f506b3e6f5dcf011565
+  data.tar.gz: 39534d84dbfdef4d58e1c55e9e5479e3b9d697637cd04dd82a75b3e2892b57c2
+SHA512:
+  metadata.gz: 1703b4fe13cd34c08c999dfc5dbbe8a5cd85a439e9411b3c645575424d0df365798c85745707c275dd59e750ff34eb1ee67ec30724d4f45700d78f66c297a59e
+  data.tar.gz: fc492517b52b8c6542d444dba33f2b5c0f532c156b19d6d2c336a0f11e3bf6ee717aab2652334b7a2f37ecce1cbb6cbfbbe56a9affa25e06339cffa60213edb3

data/.rubocop.yml

@@ -0,0 +1,21 @@
+---
+require:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Lint/InterpolationCheck:
+  Enabled: false
+
+Minitest/TestMethodName:
+  Enabled: true
+
+Minitest/AssertTruthy:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false  # yuk

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.0.0.pre] - 2024-09-26
+
+- Initial release

data/Guardfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+guard :minitest do
+  watch(%r{^test/(.*)/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})          { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch('README.md')                          { 'test/minitest/test_readme.rb' }
+  watch('test/fixtures/my_markdown_file.md')  { 'test/minitest/test_my_markdown_file.rb' }
+  watch('test/fixtures/my_markdown_file.md')  { 'test/minitest/markdown/test_test_class.rb' }
+  watch(%r{^test/test_helper\.rb$})           { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 MatzFan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# 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!!
+
+## Installation
+
+Add the gem to the application's Gemfile:
+
+```bash
+bundle add minitest-markdown
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install minitest-markdown
+```
+
+## Usage
+
+### In your test class
+
+To test the Ruby blocks in your README file, create file `test_readme.rb` (for example) and add the following:
+```ruby
+require 'minitest/autorun' # or in your test_helper
+require 'minitest/markdown' # ditto
+
+class ReadmeTest < MyTest # your own subclass of Minitest::Test
+  Markdown.generate_markdown_tests(self)
+end
+# => nil
+```
+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:
+```ruby
+# the code will of course be in your lib's, but for demonstration purposes:
+class Foo
+  def bar
+    'Hello Markdown!'
+  end
+end
+
+# ordinary comments are ignored.
+
+foo = Foo.new # inline comments are also ignored
+# The assertion and expected value are:-
+# => instance_of Foo
+
+# No keywword here, so the default assertion is used (assert_equal)
+Foo.new.bar
+# => 'Hello Markdown!'
+
+Foo.bar
+# => raises NoMethodError
+```
+Plain old `assert` has been aliased as `assert_truthy`, so when expecting a truthy value you should do this:
+```ruby
+[1, 'true', true].sample
+# => truthy
+```
+For convenience, the assertion `assert_includes` has also been aliased so that it operates either way around:
+```ruby
+[1, 2, 3]
+# => includes 2
+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:
+```ruby
+22/7.0
+# => in_delta Math::PI, 0.01
+```
+To skip a test, use `skip`, as you would in a regular test:
+```ruby
+"some code which you don't want to test yet"
+# => skip 'give a reason for the skip here'
+```
+
+### 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.
+```ruby
+# setup
+
+@instance_var = 42
+```
+The instance var set is now available to all test blocks (tests) in the Markdown file.
+```ruby
+@instance_var
+# => 42
+```
+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 ;-)
+
+## Configuration
+
+No configuation is required if you use Bundler. If not, set your `project_root` path using the setter method:
+```ruby
+@config = Markdown.config
+# => instance_of Configuration
+
+Configuration.instance_methods(false)
+# => includes :project_root=
+```
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## 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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/minitest/assertions_extensions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Minitest
+  # patch
+  module Assertions
+    alias assert_truthy assert
+    alias assert_included_in assert_includes
+
+    # extensions
+    module AssertionExtensions
+      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
+  end
+end

data/lib/minitest/markdown/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require_relative 'error'
+
+module Minitest
+  module Markdown
+    # configuration for gem
+    class Configuration
+      attr_accessor :project_root, :prove_it
+
+      def initialize
+        @project_root = determine_project_root
+        @prove_it = true
+      end
+
+      def readme_path
+        project_root.join 'README.md'
+      end
+
+      private
+
+      def determine_project_root
+        return Bundler.root if defined? Bundler
+
+        raise Error::MarkdownError, "Project root can't be determined, set with 'Config.project_root = /root/path'"
+      end
+    end
+  end
+end

data/lib/minitest/markdown/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Minitest
+  module Markdown
+    module Error
+      class MarkdownError < StandardError; end
+    end
+  end
+end

data/lib/minitest/markdown/test_class.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative '../assertions_extensions'
+require_relative 'test_code_block'
+
+module Minitest
+  module Markdown
+    # knows how to build a markdown test
+    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
+
+      attr_reader :klass, :path
+
+      def initialize(klass, path: nil)
+        @klass = klass
+        @config = Markdown.config
+        @path = path || @config.readme_path
+        @ruby_blocks = parse_ruby_blocks
+      end
+
+      def define_methods
+        define_non_test_methods
+        @ruby_blocks.each_with_index { |block, i| define_test_method(block, i) }
+        nil
+      end
+
+      private
+
+      def parse_ruby_blocks
+        File.new(path).read.scan(FENCED_BLOCK_REGEXP).flatten.map { |str| TestCodeBlock.new(str) }
+      end
+
+      def define_non_test_methods
+        recognized_non_test_methods.each { |name| define_non_test_method(name, parse_non_test_method_block(name)) }
+      end
+
+      def recognized_non_test_methods
+        Minitest.const_defined?(:Hooks) ? NON_TEST_METHODS + HOOK_METHODS : NON_TEST_METHODS
+      end
+
+      def define_non_test_method(type, block)
+        return unless block
+
+        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
+        end
+      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)
+        instance = self # scope
+        klass.define_method(:"test_block#{meth_index}") do
+          block.assertions.each { |assertion_hash| instance.send(:evaluation_assertions, assertion_hash, binding) }
+        end
+      end
+
+      def evaluation_assertions(assertion_hash, bind)
+        ruby, assertion, args = TestCodeBlock::ASSERTION_KEYS.map { |key| assertion_hash[key] } # order dep
+
+        lmbda = -> { eval(ruby) } # rubocop:disable Security/Eval # TODO: assign a binding
+        return unless assertion
+        return eval_with_block(bind, assertion, lmbda, args) if Assertions::WITH_BLOCK_EVAL.include? assertion
+
+        eval_without_block(bind, assertion, lmbda, args)
+      end
+
+      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
+      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, 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
+    end
+  end
+end

data/lib/minitest/markdown/test_code_block.rb

@@ -0,0 +1,66 @@
+# 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

data/lib/minitest/markdown/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Minitest
+  module Markdown
+    VERSION = '0.0.0.pre'
+  end
+end

data/lib/minitest/markdown.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'markdown/configuration'
+require_relative 'markdown/error'
+require_relative 'markdown/version'
+require_relative 'markdown/test_class'
+
+module Minitest
+  # namespace
+  module Markdown
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+      end
+
+      def generate_markdown_tests(klass, path: nil)
+        TestClass.new(klass, path: path).define_methods
+      end
+    end
+  end
+end

data/sig/minitest/markdown.rbs

@@ -0,0 +1,6 @@
+module Minitest
+  module Markdown
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: minitest-markdown
+version: !ruby/object:Gem::Version
+  version: 0.0.0.pre
+platform: ruby
+authors:
+- MatzFan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-09-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minifyrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+description: Generates tests for Ruby code blocks in any Markdown file.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/minitest/assertions_extensions.rb
+- lib/minitest/markdown.rb
+- lib/minitest/markdown/configuration.rb
+- lib/minitest/markdown/error.rb
+- lib/minitest/markdown/test_class.rb
+- lib/minitest/markdown/test_code_block.rb
+- lib/minitest/markdown/version.rb
+- sig/minitest/markdown.rbs
+homepage: https://gitlab.com/matzfan/minitest-markdown
+licenses:
+- MIT
+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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.19
+signing_key:
+specification_version: 4
+summary: Turn your README.md Ruby code blocks into testable code.
+test_files: []