✨

Serverspecのレポート形式を切り替える

に公開
インフラ
IaC
インフラエンジニア
serverspec
tech

はじめに

ServerspecはRSpecをベースにしており、
フォーマッタ（formatter）を指定することで出力形式を自由に切り替えられる。

この記事では、実際に使っているRakefileをもとに、
Serverspecのレポート形式を切り替える方法を整理する。

選択できるレポート形式（一覧）

形式 内容 主な用途
documentation 標準的なテキスト形式（読みやすい） ローカル確認
html HTMLレポートを生成 可視化・共有
json 構造化データで出力 集計や外部連携
RspecJunitFormatter JUnit互換XML形式 GitLab・Jenkins等のCI向け

Rakefileの設定

自分の環境ではRakefileは以下のようになっていた。

# 実際に使用していたRakefileの抜粋
Serverspec::RakeTask.new do |t|
  t.pattern = 'spec/*_spec.rb'
  t.rspec_opts = '--color --format documentation'
end

ここを環境変数経由で柔軟に指定できるよう、次のように修正する。

# 修正版：環境変数からフォーマット指定を受け取る
Serverspec::RakeTask.new do |t|
  t.pattern = 'spec/*_spec.rb'
  t.rspec_opts = ENV['RSPEC_OPTS'] || '--color --format documentation'
end

これで、実行時に RSPEC_OPTS を渡すだけで出力形式を切り替えられる。

各フォーマットの実行例と出力イメージ

documentation形式

RSPEC_OPTS="--format documentation" rake spec

出力例：

  Package "openssh-server"
    is expected to be installed
  Command "hostname"
    stdout
      is expected to match /.+/
  File "/etc/passwd"
    is expected to exist
    is expected to be file

html形式

RSPEC_OPTS="--format html --out result.html" rake spec

result.html が生成され、ブラウザで開くとカラー付きでテスト結果を確認できる。

「Passed」や「Failed」の選択も可能

json形式

RSPEC_OPTS="--format json --out result.json" rake spec

result.json にテスト結果を構造化データで出力。
スクリプトでの集計や自動化に活用できる。

出力例（抜粋）：

{
    "version": "3.13.6",
    "examples": [
        {
            "id": "./spec/apache/apache_spec.rb[1:1:1]",
            "description": "is expected to be installed",
            "full_description": "Apache service Package \"apache2\" is expected to be installed",
            "status": "failed",
            "file_path": "./spec/apache/apache_spec.rb",
            "line_number": 5,
            "run_time": 1.924394349,
            "pending_message": null,
            "exception": {
                "class": "RSpec::Expectations::ExpectationNotMetError",
                "message": "expected Package \"apache2\" to be installed",
                "backtrace": [
                    "./spec/apache/apache_spec.rb:5:in `block (3 levels) in <top (required)>'"
                ]
            }

JUnit形式（RspecJunitFormatter）

JUnit形式で出力するには、事前に rspec_junit_formatter のインストールが必要。

gem install rspec_junit_formatter

RSPEC_OPTS="--format RspecJunitFormatter --out result.xml" rake spec

出力例（抜粋）：

<testsuite name="rspec" tests="9" skipped="0" failures="5" errors="0" time="1.47" timestamp="2025-10-26T01:47:29+00:00" hostname="container_id_hidden">
  <properties>
    <property name="seed" value="34380"/>
  </properties>
  <testcase classname="spec.apache.apache_spec" 
            name="Apache service Package &quot;apache2&quot; is expected to be installed" 
            file="./spec/apache/apache_spec.rb" 
            time="0.940538">
    <failure message="expected Package &quot;apache2&quot; to be installed" 
             type="RSpec::Expectations::ExpectationNotMetError">
      On host `172.21.0.3`
      Failure/Error: it { should be_installed }
      expected Package "apache2" to be installed
      /bin/sh -c dpkg-query -f '${Status}' -W apache2 | grep -E '^(install|hold) ok installed$'
      ./spec/apache/apache_spec.rb:5:in `block (3 levels) in &lt;top (required)&gt;'
    </failure>
  </testcase>
</testsuite>

フォーマットを固定する場合

Rakefileを固定で指定する場合は以下のように変更する。

t.rspec_opts = '--color --format RspecJunitFormatter --out reports/result.xml'

常にJUnit形式のレポートが出力されるようになる。

おわりに

Serverspecの出力は、単なるテキストからレポート形式へ変えることで
「見る・残す・共有する」が格段にやりやすくなる。

JUnit形式の活用方法は別記事で。。。

参考リンク

Discussion