自戒です。
先日自分が書いた gem を自分で使おうとして README をコピペしたら間違っていて残念な気持ちになったので、README のサンプルをテストコードの中で実行する gem 作りました。
README のサンプル間違ってると大変萎えるのでご活用下さい。
インストール
rubygems からインストールします
gem install readme_spec
使い方
まず RSpec.configure に README のファイルパスを渡してあげて下さい。
spec_helper.rb
RSpec.configure do |c|
c.readme_file_path = File.dirname(__FILE__) + '/../README.md'
end
次にいい感じの README を書きましょう。
Your awesome description.
Your sample code.
```ruby
class YourClass
def do_something
true
end
end
your_class = YourClass.new
expect(your_class.do_something).to be_true
```
README の中に ruby で囲まれたサンプルコードがあります。以下の様な呼び出しをテストコードから行うと、README に埋め込んだサンプルコードを rspec とかで実行できるようになります。
expect { ReadmeSpec.evaluate(binding) }.not_to raise_error
失敗した場合のメッセージは例外そのままです。つまり今回の例だと普通に rspec を実行した時のエラーメッセージを得ることができるのでわかりづらいということはないと思います。
Failure/Error: it { expect { ReadmeSpec.evaluate(binding) }.not_to raise_error }
expected no Exception, got #<RSpec::Expectations::ExpectationNotMetError:
expected #<Fixnum:3> => 1
got #<Fixnum:7> => 3
注意点とか
内部実装見ていただけるとわかるのですが普通にサンプルコードを eval してるだけなのでお気をつけ下さい。rspec の DSL をそのまま README に書いてその正しさも保証できるのでそこそこ便利かと思います。
また、テスト対象のコードですが github が qiita のような markdown 書き方（ruby:hogeってかけるやつ）をサポートしてくれていれば良いのですが、そうではないので雑に ruby で囲まれたところは一括で実行するようになっています。
github が以下の書き方サポートしてない
```ruby:spec1
expect(true).to be true
```
```ruby:spec2
expect(1).to be 1
```
気が向いたら一行目のコメントみるとかそういう実装入れます。