Rails × RSpec ベストプラクティス

group :development, :test do
  gem "rspec-rails"
  gem "factory_bot_rails"
  gem "faker"
end
 
group :test do
  gem "shoulda-matchers"   # バリデーション・関連のワンライナー検証
  gem "capybara"                   # System Spec の DSL
  gem "capybara-playwright-driver" # ブラウザドライバー（selenium-webdriver / cuprite も可）
  gem "webmock"            # 外部HTTPの遮断・スタブ
  gem "vcr"                # 外部APIレスポンスの記録・再生（必要に応じて）
  gem "simplecov", require: false
end
 
group :development do
  gem "rubocop-rspec", require: false
  gem "rubocop-factory_bot", require: false
  gem "rubocop-rspec_rails", require: false
end

bin/rails generate rspec:install

require "spec_helper"
ENV["RAILS_ENV"] ||= "test"
require_relative "../config/environment"
abort("The Rails environment is running in production mode!") if Rails.env.production?
require "rspec/rails"
 
# spec/support 配下を読み込む
Rails.root.glob("spec/support/**/*.rb").sort.each { |f| require f }
 
# 保留中のマイグレーションがあれば落とす
begin
  ActiveRecord::Migration.maintain_test_schema!
rescue ActiveRecord::PendingMigrationError => e
  abort e.to_s.strip
end
 
RSpec.configure do |config|
  config.fixture_paths = [Rails.root.join("spec/fixtures")]
  config.use_transactional_fixtures = true
  config.infer_spec_type_from_file_location!
  config.filter_rails_from_backtrace!
 
  config.include FactoryBot::Syntax::Methods
  config.include ActiveSupport::Testing::TimeHelpers
end
 
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

RSpec.configure do |config|
  config.expect_with :rspec do |expectations|
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end
 
  config.mock_with :rspec do |mocks|
    # 存在しないメソッドのスタブを禁止（verifying doubles）
    mocks.verify_partial_doubles = true
  end
 
  config.shared_context_metadata_behavior = :apply_to_host_groups
  config.filter_run_when_matching :focus          # fit / fdescribe で絞り込み
  config.example_status_persistence_file_path = "spec/examples.txt" # --only-failures 用
  config.disable_monkey_patching!                 # `RSpec.describe` を強制
  config.order = :random                          # テスト順序依存の検出
  Kernel.srand config.seed
  config.profile_examples = 10 if ENV["PROFILE"]  # 遅いテストの可視化
end

RSpec.describe User, type: :model do
  describe "#full_name" do
    context "when middle name is present" do
      it "returns first, middle and last name" do
        user = build(:user, first_name: "Taro", middle_name: "J", last_name: "Yamada")
        expect(user.full_name).to eq "Taro J Yamada"
      end
    end
 
    context "when middle name is blank" do
      it "returns first and last name" do
        user = build(:user, first_name: "Taro", middle_name: nil, last_name: "Yamada")
        expect(user.full_name).to eq "Taro Yamada"
      end
    end
  end
 
  describe ".active" do
    it "returns only active users" do
      active = create(:user, :active)
      create(:user, :inactive)
 
      expect(User.active).to contain_exactly(active)
    end
  end
end

describe "#full_name" do
  context "ミドルネームがある場合" do
    it "ミドルネームを含むフルネームを返す" do
      # ...
    end
  end
end

let(:user) { create(:user) }

# 「参照されないが、DB に存在している必要がある」データに使う
let!(:archived_post) { create(:post, :archived) }
 
it "does not include archived posts" do
  expect(Post.published).not_to include(archived_post)
end

describe "#call" do
  subject(:result) { described_class.new(order).call }
 
  let(:order) { create(:order, :pending) }
 
  it "marks the order as paid" do
    expect { result }.to change { order.reload.status }.from("pending").to("paid")
  end
end

it { is_expected.to validate_presence_of(:email) }

before do
  sign_in user
end

# ❌ 何が 1000 円の根拠なのか分からない
it "returns total price" do
  expect(order.total_price).to eq 1000
end
 
# ✅ 前提が見える
it "returns the sum of line item prices" do
  order = create(:order)
  create(:line_item, order:, price: 300)
  create(:line_item, order:, price: 700)
 
  expect(order.total_price).to eq 1000
end

FactoryBot.define do
  factory :user do
    sequence(:email) { |n| "user#{n}@example.com" }
    name { "Test User" }
    password { "password" }
 
    # バリエーションは trait で表現する
    trait :admin do
      role { :admin }
    end
 
    trait :with_posts do
      transient do
        posts_count { 3 }
      end
 
      after(:create) do |user, evaluator|
        create_list(:post, evaluator.posts_count, user:)
      end
    end
  end
end

factory :post do
  user  # association :user と同じ
  title { "Title" }
end

# spec/factories_spec.rb
RSpec.describe "FactoryBot" do
  it "has valid factories" do
    FactoryBot.lint traits: true
  end
end

RSpec.describe User, type: :model do
  describe "validations" do
    subject { build(:user) }
 
    it { is_expected.to validate_presence_of(:email) }
    it { is_expected.to validate_uniqueness_of(:email).case_insensitive }
    it { is_expected.to validate_length_of(:name).is_at_most(50) }
  end
 
  describe "associations" do
    it { is_expected.to have_many(:posts).dependent(:destroy) }
    it { is_expected.to belong_to(:organization).optional }
  end
 
  describe "#deactivate!" do
    let(:user) { create(:user, :active) }
 
    it "sets deactivated_at" do
      freeze_time do
        user.deactivate!
        expect(user.deactivated_at).to eq Time.current
      end
    end
  end
end

RSpec.describe "Posts API", type: :request do
  let(:user) { create(:user) }
  let(:headers) { { "Authorization" => "Bearer #{token_for(user)}" } }
 
  describe "POST /api/posts" do
    let(:params) { { post: { title: "Hello", body: "World" } } }
 
    context "with valid params" do
      it "creates a post" do
        expect {
          post "/api/posts", params:, headers:, as: :json
        }.to change(Post, :count).by(1)
      end
 
      it "returns 201 with the created post" do
        post "/api/posts", params:, headers:, as: :json
 
        expect(response).to have_http_status(:created)
        expect(response.parsed_body).to include("title" => "Hello")
      end
    end
 
    context "with invalid params" do
      let(:params) { { post: { title: "" } } }
 
      it "returns 422" do
        post "/api/posts", params:, headers:, as: :json
        expect(response).to have_http_status(:unprocessable_entity)
      end
    end
 
    context "when unauthenticated" do
      it "returns 401" do
        post "/api/posts", params:, as: :json
        expect(response).to have_http_status(:unauthorized)
      end
    end
  end
end

bundle add capybara-playwright-driver --group test
npm install --save-dev playwright   # gem が対応するバージョンに合わせる
npx playwright install chromium

# spec/support/system_spec.rb
RSpec.configure do |config|
  config.before(:each, type: :system) do
    driven_by :rack_test
  end
 
  config.before(:each, type: :system, js: true) do
    driven_by :playwright, options: { browser_type: :chromium, headless: true }
  end
end

RSpec.describe "User signs up", type: :system do
  it "allows a visitor to sign up" do
    visit new_user_registration_path
 
    fill_in "メールアドレス", with: "new@example.com"
    fill_in "パスワード", with: "password"
    click_button "登録する"
 
    expect(page).to have_content "登録が完了しました"
  end
 
  context "with JavaScript", js: true do
    it "shows validation errors without page reload" do
      # Playwright で実行される
    end
  end
end

RSpec.describe Orders::Checkout do
  describe "#call" do
    subject(:result) { described_class.new(order:, payment_gateway:).call }
 
    let(:order) { create(:order, :with_items) }
    let(:payment_gateway) { instance_double(PaymentGateway, charge: charge_result) }
 
    context "when payment succeeds" do
      let(:charge_result) { PaymentGateway::Result.new(success: true) }
 
      it { is_expected.to be_success }
 
      it "marks the order as paid" do
        expect { result }.to change { order.reload.status }.to("paid")
      end
    end
 
    context "when payment fails" do
      let(:charge_result) { PaymentGateway::Result.new(success: false, error: "declined") }
 
      it { is_expected.to be_failure }
 
      it "does not change the order status" do
        expect { result }.not_to change { order.reload.status }
      end
    end
  end
end

RSpec.describe ReportGenerationJob, type: :job do
  include ActiveJob::TestHelper
 
  it "enqueues the job" do
    expect {
      described_class.perform_later(report.id)
    }.to have_enqueued_job(described_class).with(report.id).on_queue("default")
  end
 
  it "generates the report" do
    report = create(:report, :pending)
    described_class.perform_now(report.id)
    expect(report.reload).to be_completed
  end
end

RSpec.describe UserMailer, type: :mailer do
  describe "#welcome" do
    let(:user) { build_stubbed(:user, email: "taro@example.com", name: "Taro") }
    let(:mail) { described_class.welcome(user) }
 
    it "renders the headers" do
      expect(mail.to).to eq ["taro@example.com"]
      expect(mail.subject).to eq "ようこそ"
    end
 
    it "includes the user name in the body" do
      expect(mail.body.encoded).to include "Taro"
    end
  end
end

# ❌ 存在しないメソッドでもスタブできてしまう
gateway = double("PaymentGateway", charge: true)
 
# ✅ PaymentGateway に charge が存在しない・引数が合わない場合にエラー
gateway = instance_double(PaymentGateway, charge: true)

# スタブ（戻り値を決めたいだけ）
allow(gateway).to receive(:charge).and_return(result)
 
# メッセージ送信そのものが検証対象
expect(notifier).to receive(:notify).with(user)
 
# 呼び出し後に検証したい場合（Arrange-Act-Assert の順序を保てる）
notifier = instance_double(Notifier, notify: nil)
service.call
expect(notifier).to have_received(:notify).with(user)

# ❌ 影響範囲が広く、設計の問題を隠す
allow_any_instance_of(User).to receive(:premium?).and_return(true)
 
# ✅ 状態を作る or 依存を注入する
user = build(:user, :premium)

it "expires after 30 days" do
  token = create(:token)
 
  travel_to 31.days.from_now do
    expect(token).to be_expired
  end
end
 
it "records the current time" do
  freeze_time do
    record.touch_processed!
    expect(record.processed_at).to eq Time.current
  end
end

# spec/support/webmock.rb
require "webmock/rspec"
WebMock.disable_net_connect!(allow_localhost: true)

before do
  stub_request(:get, "https://api.example.com/users/1")
    .to_return(status: 200, body: { name: "Taro" }.to_json,
               headers: { "Content-Type" => "application/json" })
end

# 呼び出し側：ジョブが積まれることだけを検証
expect { service.call }.to have_enqueued_job(NotifyJob).with(user.id)
 
# 実行までまとめて検証したい場合
perform_enqueued_jobs do
  service.call
end

# spec/support/shared_examples/requires_authentication.rb
RSpec.shared_examples "requires authentication" do
  context "when unauthenticated" do
    let(:headers) { {} }
 
    it "returns 401" do
      request
      expect(response).to have_http_status(:unauthorized)
    end
  end
end
 
# 使用側
describe "GET /api/posts" do
  subject(:request) { get "/api/posts", headers: }
 
  it_behaves_like "requires authentication"
end

RSpec.shared_context "with logged in admin" do
  let(:admin) { create(:user, :admin) }
  before { sign_in admin }
end

# spec/support/request_helpers.rb
module RequestHelpers
  def json
    response.parsed_body
  end
end
 
RSpec.configure do |config|
  config.include RequestHelpers, type: :request
end

it "returns the expected response", :aggregate_failures do
  get "/api/posts/#{post.id}"
 
  expect(response).to have_http_status(:ok)
  expect(json["title"]).to eq post.title
  expect(json["author"]["name"]).to eq post.user.name
end

# .rubocop.yml
plugins:
  - rubocop-rspec
  - rubocop-rspec_rails
  - rubocop-factory_bot
 
RSpec/ExampleLength:
  Max: 15
RSpec/MultipleExpectations:
  Max: 5
RSpec/NestedGroups:
  Max: 4

# spec/spec_helper.rb の先頭
require "simplecov"
SimpleCov.start "rails" do
  enable_coverage :branch
  add_filter "/spec/"
end