テストの説明には何を書くべきか

テストの説明って会社によっては書くべきことやフォーマットが違っていたりしますよね。しかし、ルールやフォーマットがどうあれ「これは書いておいたほうがいい」という情報があると私は考えています。本記事ではそれを簡単に紹介していこうと思います。ちなみに、私は自然言語はわかりにくいと思っているので、なるべく説明は必要最小限にしたいと思っています。

テスト対象クラスとメソッド

単体テストではテスト対象のクラスに対応するファイルを作成して、その中にテストコードを記述していくことが一般的かと思います。そしてそのクラスのメソッドに対するテスト関数は、他の記事で紹介している4フェーズテストを使えばテスト対象がわからないなんてことはあまりないと思うので本来はテスト対象が何なのかを説明に書く必要はないように思います。しかし、そうだとしてもこれらの情報が記述されていることで嬉しい状況があります。それは特定のテスト関数だけ実行したいときです。
単純にテストを回したい場合は全部実行したりファイル単位で実行したりするものですが、場合よっては特定のメソッドだけ実行したいなんてときがあります。そのときに実行する単位をコントロールしやすくする目的でクラスやメソッドの情報を説明に書いておくと何かと便利だったりします。（rspecはネストの行番号で実行したい範囲をコントロールできて便利ですね）

分かりづらい仕様の説明

シンプルな処理のテストの場合は4フェーズテストで言うところのexerciseフェーズでテスト対象の関数名ややverifyフェーズの検証項目と期待値を見ればどんな結果を期待しているのか、つまりテスト対象がどんな仕様なのかはすぐに理解できます。しかし、少々複雑なテスト対象になってくると簡単には読み取れないことも少なくないです。
そんなときのために複雑なテスト対象を扱う場合は「どんな結果になることを期待しているのか」をテストの説明で補足しておくと良いでしょう。例えば以下のようなイメージです。

describe 'タスクの作成' do
  it '成功するとタスクの一覧ページに遷移し、作成したタスクが一覧に表示されること' do
    create_user(name: 'hoge', email: '[e-mail]', password: 'password')
    visit_login_page()
    set_form('email', '[e-mail]')
    set_form('password', 'password')
    click_button('ログイン')

    visit_task_creation_page()
    set_form('name', 'task名')
    click_button('送信')

    expect(get_elements('name')[0]).to eq('task名')
  end
end

逆に言うと関数名等で十分に理解できるような仕様の場合はあんまり書かないというのも大事だと思います。理由は冒頭で書きましたが自然言語はわかりにくいので逆に余計な情報になってしまう可能性もあります。

因子

因子というのはプロダクトコードの挙動に影響を与える値になります。多くの場合はデータになりますが、場合によっては何かしらのイベントなどにもなるかもしれません。この因子はテストコードを理解するためには非常に重要な情報になるので極力わかりやすくしておくことが望ましいです。因子がデータであるならそのデータは何かしらの集合に所属する具体的な1つの要素である可能性が高く、それ自体でその因子がどんな集合に所属してるのかがわかりにくいことがあります。
簡単な例としてFizzBuzzのテストを書いてみます。

describe 'fizz_buzz' do
  it do
    result = fizz_buzz(6)
    expect(6).to eq('fizz')
  end
end

この場合6という値は3の倍数に所属していますが、値としては単に6なので何のつもりで入力しているのかがわかりにくいので少々不親切に見えます。なので因子がどんな集合から取り出した値なのかを説明を書いてあげると良いです。

describe 'fizz_buzz' do
  context '3の倍数' do
    it do
      result = fizz_buzz(6)
      expect(6).to eq('fizz')
    end
  end
end

因子って言い回しをしましたが、人によってはテスト観点であるとかテストの条件だと言うかもしれません。いずれにしてもプロダクトコードの挙動に影響を与える重要な要素です。それらを説明で補足することによってテストコードが格段にわかりやすくなるのではなかろうかと思います。

終わりに

どんなフォーマットであったり、どんなルールであろうと書いておいたほうがよい説明について紹介しました。本来自然言語はわかりにくいのものであるため極力利用しないのが望ましいと思いますが、便利であったり足りない情報を補う形であれば、テストの説明としてうまく利用できるのではなかろうかと思います。