はじめに

自動テストを書いていると、

仕様変更があった場合に変更しないといけない箇所が増える
一部だけ変更がされていて、どっちが正しいのかわからない

という悩みが付いて回ってくるのではないかと思います。

今回は、上記の問題を解決するために、

「RSpecから仕様書の雛形をつくる」

という方法について記載します。

事前準備

RSpecを書きます

事前準備はこれだけです。
では、実際にRSpecから仕様書の出力をしていきましょう。

前提知識

今回は、RSpecの--dry-runオプションと--formatオプションを利用します。

--dry-run
- テストを実行せず出力だけ得る
--format
- 出力する際のフォーマッターを指定する
- 標準で用意されているフォーマッターでは、少し物足りないので、今回はカスタムフォーマッターを作成して利用します。

カスタムフォーマッターの作成

出力したい内容にあうように、カスタムフォーマッターを利用します。
documentation_formatterが一番近かったので、今回はこちらを継承しました。

下記を、適当なところに置きます。
（今回は、spec/support/custom_formatter.rbとして保存）

require 'rspec/core/formatters/documentation_formatter'

class CustomFormatter  < RSpec::Core::Formatters::DocumentationFormatter
  RSpec::Core::Formatters.register self, :example_group_started

  def initialize(output)
    super
  end

  # 今回はインデント部分のみを調整した
  def current_indentation
    if @group_level == 0
      '## '
    else
      ' ' * ( @group_level - 1 ) * 4 + '- '
    end
  end
end

テストケースを出力する

全てのテストケースを出力したい場合

bundle exec rspec --dry-run --require spec/support/custom_formatter.rb --format CustomFormatter

特定のファイルのテストケースのみを出力したい場合

bundle exec rspec --dry-run --require spec/support/custom_formatter.rb --format CustomFormatter spec/models/hoge_spec.rb

実際に出力した結果

specファイル

spec/models/hoge_spec.rb

RSpec.describe Hoge do
  describe "testの検査" do
    it "testが成功するべき" do
     :
    end
  end 
end

実行コマンド

bundle exec rspec --dry-run --require spec/support/custom_formatter.rb --format CustomFormatter spec/models/hoge_spec.rb

実行結果

## Hoge
- testの検査
    - testが成功するべき

おわりに

RSpecはテスト仕様書として非常に有用な資産になると思っています。
今回は、その資産を他の部分でも有効活用できればと、仕様書として利用する方法を考えてみました。

品質を保つ
リファクタリングをしやすくする

という部分以外で、誰もが面倒だと思っている

仕様書を書く

という部分にたいしても有効である状況を作れれば、プロジェクトとしてより積極的にRSpecの導入が進んでいくのではないかと考えてます。

カスタムフォーマッターの書き方次第で、いろんなドキュメントの形式にあわせることができると思うので、一度お試しください。