minitest-markdown

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:

bundle add minitest-markdown

If bundler is not being used to manage dependencies, install the gem by executing:

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:

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 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:

# 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:

[1, 'true', true].sample
# => truthy

For convenience, the assertion assert_includes has also been aliased so that it operates either way around:

[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:

22/7.0
# => in_delta Math::PI, 0.01

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'

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.

# setup

@instance_var = 42

The instance var set is now available to all test blocks (tests) in the Markdown file.

@instance_var
# => 42

The hook methods defined in the minitest-hooks 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 would complain otherwise ;-)

Configuration

No configuation is required if you use Bundler. If not, set your project_root path using the setter method:

@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.

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.