RSpec and Test Doubles

# frozen_string_literal: true

source "https://rubygems.org"

gemspec

group :development, :test do
  gem "rspec", "~> 3.13"
  gem "rubocop", "~> 1.92", require: false
end

bundle install
bundle exec rspec --init

--require spec_helper
--format documentation
--color

shelf/
├── lib/shelf/...
├── spec/
│   ├── spec_helper.rb
│   ├── support/
│   │   ├── book_helpers.rb
│   │   └── store_examples.rb
│   └── shelf/
│       ├── isbn_spec.rb
│       ├── catalog_spec.rb
│       └── store_spec.rb
├── .rspec
└── .rubocop.yml

# frozen_string_literal: true

require "shelf"

Dir[File.join(__dir__, "support", "*_helpers.rb")].each { |f| require f }

RSpec.configure do |config|
  config.disable_monkey_patching!
  config.order = :random
  Kernel.srand config.seed

  config.expect_with :rspec do |expectations|
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end

  config.mock_with :rspec do |mocks|
    mocks.verify_partial_doubles = true
    mocks.verify_doubled_constant_names = true
  end

  config.filter_run_excluding :slow unless ENV["SLOW"]
  config.example_status_persistence_file_path = ".rspec_status"
  config.shared_context_metadata_behavior = :apply_to_host_groups
end

inherit_from: ../shelf/.rubocop.yml

Metrics/BlockLength:
  Exclude:
    - "spec/**/*"

# frozen_string_literal: true

module BookHelpers
  def build_book(title = "Ruby Basics", isbn: "978-0-306-40615-7")
    Shelf::Book.new(Shelf::Isbn.new(isbn), title, Shelf::Author.new("A. Writer"))
  end
end

RSpec.configure { |config| config.include BookHelpers }

# frozen_string_literal: true

RSpec.describe Shelf::Isbn do
  subject(:isbn) { described_class.new(raw) }

  let(:raw) { "978-0-306-40615-7" }

  describe ".new" do
    context "with a valid ISBN-13" do
      it "strips the hyphens" do
        expect(isbn.digits).to eq("9780306406157")
      end

      it { is_expected.to be_a(Data) }
      it { is_expected.to have_attributes(digits: a_string_matching(/\A\d{13}\z/)) }
    end

    context "with a bad check digit" do
      let(:raw) { "978-0-306-40615-8" }

      it "raises ArgumentError naming the input" do
        expect { isbn }.to raise_error(ArgumentError, /invalid ISBN: 978-0-306-40615-8/)
      end
    end
  end

  describe "#to_s" do
    it "returns the bare digits" do
      expect(isbn.to_s).to eq("9780306406157")
    end
  end

  describe "#==" do
    it "treats the same digits as equal" do
      expect(isbn).to eq(described_class.new("9780306406157"))
    end
  end
end

Shelf::Isbn
  .new
    with a valid ISBN-13
      strips the hyphens
      is expected to be a kind of Data
      is expected to have attributes {digits: (a string matching /\A\d{13}\z/)}
    with a bad check digit
      raises ArgumentError naming the input
  #to_s
    returns the bare digits
  #==
    treats the same digits as equal

# frozen_string_literal: true

RSpec.describe "hooks and let" do
  let(:log) { [] }
  let(:lazy) { log << "let evaluated" and :lazy }
  let!(:eager) { log << "let! evaluated" and :eager }

  before(:context) { $stdout.puts "before(:context)" }
  before { log << "before" }
  after { $stdout.puts "after sees #{log.inspect}" }
  around do |example|
    $stdout.puts "around start"
    example.run
    $stdout.puts "around end"
  end

  it "runs hooks in order and memoizes let" do
    lazy
    lazy
    expect(log).to eq(["let! evaluated", "before", "let evaluated"])
    expect(eager).to eq(:eager)
  end

  it "builds fresh state for every example" do
    expect(log).to eq(["let! evaluated", "before"])
  end
end

before(:context)
around start
after sees ["let! evaluated", "before", "let evaluated"]
around end
.around start
after sees ["let! evaluated", "before"]
around end
.

Finished in 0.00056 seconds (files took 0.04343 seconds to load)
2 examples, 0 failures

# frozen_string_literal: true

RSpec::Matchers.define :be_on_the_shelf do
  match { |loan| loan.state == :available }
  failure_message { |loan| "expected #{loan.book.title} to be on the shelf, but it is #{loan.state}" }
end

RSpec.describe Shelf::Loan do
  let(:book) { build_book }

  describe "#describe" do
    {
      available: "Ruby Basics is on the shelf",
      lent: "Ruby Basics is lent",
      overdue: "Ruby Basics is overdue",
      returned: "Ruby Basics came back"
    }.each do |state, sentence|
      it "describes the #{state} state" do
        expect(described_class.new(book, state:).describe).to eq(sentence)
      end
    end
  end

  describe "matchers" do
    it "supports a custom matcher" do
      expect(described_class.new(book)).to be_on_the_shelf
    end

    it "checks several things at once" do
      loan = described_class.new(book, state: :lent)

      aggregate_failures do
        expect(loan.state).to eq(:lent)
        expect(loan.book).to have_attributes(title: "Ruby Basics")
        expect(described_class::STATES).to include(:lent, :overdue).and all(be_a(Symbol))
      end
    end

    it "rejects an unknown state" do
      expect { described_class.new(book, state: :lost) }
        .to raise_error(ArgumentError, "unknown state: lost")
    end
  end
end

RSpec.describe Shelf::Catalog do
  let(:catalog) { described_class.new(store: Shelf::Store::Memory.new) }

  it "grows by one with each add" do
    expect { catalog.add(build_book) }.to change { catalog.count }.from(0).to(1)
  end

  it "yields every book to the block" do
    book = build_book
    catalog.add(book)

    expect { |probe| catalog.each(&probe) }.to yield_with_args(book)
  end
end

Shelf::Loan
  #describe
    describes the available state
    describes the lent state
    describes the overdue state
    describes the returned state
  matchers
    supports a custom matcher
    checks several things at once
    rejects an unknown state

Shelf::Catalog
  grows by one with each add
  yields every book to the block

  1) fail custom message
     Failure/Error: expect(Shelf::Loan.new(build_book, state: :lent)).to be_on_the_shelf
       expected Ruby Basics to be on the shelf, but it is lent

  2) fail aggregate
     Got 2 failures from failure aggregation block.

     2.1) Failure/Error: expect(1).to eq(2)

            expected: 2
                 got: 1

            (compared using ==)

     2.2) Failure/Error: expect("a").to eq("b")

            expected: "b"
                 got: "a"

            (compared using ==)

# frozen_string_literal: true

# Sends a message to a borrower. In production this would talk to an SMTP server.
class Mailer
  def deliver(to:, subject:)
    raise NotImplementedError, "#{self.class} talks to a real mail server"
  end
end

# frozen_string_literal: true

require "shelf"
require_relative "mailer"

# Lends books from a catalog and tells the borrower about it.
class Lender
  def initialize(catalog:, mailer: Mailer.new)
    @catalog = catalog
    @mailer = mailer
  end

  def lend(isbn, to:)
    book = @catalog.find { |candidate| candidate.isbn == isbn }
    return nil unless book

    loan = Shelf::Loan.new(book, state: :lent)
    @mailer.deliver(to:, subject: "You borrowed #{book.title}")
    loan
  end
end

# frozen_string_literal: true

require "lender"

RSpec.describe Lender do
  subject(:lender) { described_class.new(catalog:, mailer:) }

  let(:book) { build_book }
  let(:catalog) { Shelf::Catalog.new(store: Shelf::Store::Memory.new).add(book) }
  let(:mailer) { instance_double(Mailer, deliver: true) }

  describe "#lend" do
    context "when the book is in the catalog" do
      it "returns a lent loan" do
        loan = lender.lend(book.isbn, to: "reader@example.com")

        expect(loan).to have_attributes(book:, state: :lent)
      end

      it "mails the borrower exactly once" do
        lender.lend(book.isbn, to: "reader@example.com")

        expect(mailer).to have_received(:deliver)
          .with(to: "reader@example.com", subject: a_string_including("Ruby Basics"))
          .once
      end
    end

    context "when the book is unknown" do
      let(:unknown) { Shelf::Isbn.new("978-1-86197-876-9") }

      it "returns nil and sends nothing" do
        expect(lender.lend(unknown, to: "reader@example.com")).to be_nil
        expect(mailer).not_to have_received(:deliver)
      end
    end

    context "when mail delivery fails" do
      before { allow(mailer).to receive(:deliver).and_raise(IOError, "SMTP down") }

      it "lets the error reach the caller" do
        expect { lender.lend(book.isbn, to: "reader@example.com") }
          .to raise_error(IOError, "SMTP down")
      end
    end
  end

  describe "with the expect-to-receive style" do
    it "states the expectation before acting" do
      expect(mailer).to receive(:deliver).with(to: "a@example.com", subject: /borrowed/)

      lender.lend(book.isbn, to: "a@example.com")
    end
  end
end

Lender
  #lend
    when the book is in the catalog
      returns a lent loan
      mails the borrower exactly once
    when the book is unknown
      returns nil and sends nothing
    when mail delivery fails
      lets the error reach the caller
  with the expect-to-receive style
    states the expectation before acting

# frozen_string_literal: true

RSpec.shared_examples "a book store" do
  let(:book) { build_book }

  it "starts empty" do
    expect(store.all).to be_empty
  end

  it "returns itself from #add so calls can chain" do
    expect(store.add(book)).to equal(store)
  end

  it "keeps what was added" do
    store.add(book)
    expect(store.all).to contain_exactly(book)
  end

  it "hands out a copy that cannot corrupt the store" do
    store.add(book)
    store.all.clear
    expect(store.all.size).to eq(1)
  end
end

# frozen_string_literal: true

require_relative "../support/store_examples"

RSpec.describe Shelf::Store::Memory do
  it_behaves_like "a book store" do
    let(:store) { described_class.new }
  end
end

Shelf::Store::Memory
  behaves like a book store
    starts empty
    returns itself from #add so calls can chain
    keeps what was added
    hands out a copy that cannot corrupt the store

# frozen_string_literal: true

RSpec.describe "Catalog at scale" do
  it "scans a large catalog", :slow do
    store = Shelf::Store::Memory.new
    5_000.times { |i| store.add(build_book("Book #{i}")) }

    expect(Shelf::Catalog.new(store:).count).to eq(5_000)
  end

  it "stays quick for a small catalog" do
    expect(Shelf::Catalog.new(store: Shelf::Store::Memory.new).count).to eq(0)
  end
end

Run options: exclude {slow: true}
...
  stays quick for a small catalog

Run options: include {slow: true}
...
  scans a large catalog

# frozen_string_literal: true

require "rspec/core/rake_task"

RSpec::Core::RakeTask.new(:spec) do |task|
  task.rspec_opts = "-I ../shelf/lib --format progress"
end

task default: :spec

# frozen_string_literal: true

require "late_fee"

RSpec.describe LateFee do
  describe ".for" do
    it "is free on or before the due date" do
      expect(described_class.for(days_late: 0)).to eq(0)
    end

    it "charges 25 cents a day after the due date" do
      expect(described_class.for(days_late: 3)).to eq(75)
    end

    it "never exceeds the 1000 cent cap" do
      expect(described_class.for(days_late: 400)).to eq(1000)
    end
  end
end

# frozen_string_literal: true

# Late fees in cents.
module LateFee
  def self.for(days_late:) = 0
end

.FF

Failures:

  1) LateFee.for charges 25 cents a day after the due date
     Failure/Error: expect(described_class.for(days_late: 3)).to eq(75)

       expected: 75
            got: 0

       (compared using ==)

  2) LateFee.for never exceeds the 1000 cent cap
     Failure/Error: expect(described_class.for(days_late: 400)).to eq(1000)

       expected: 1000
            got: 0

       (compared using ==)

Finished in 0.00247 seconds (files took 0.03658 seconds to load)
3 examples, 2 failures

# frozen_string_literal: true

# Late fees in cents.
module LateFee
  RATE = 25
  CAP = 1000

  def self.for(days_late:) = [days_late * RATE, CAP].min
end

...

Finished in 0.00176 seconds (files took 0.04496 seconds to load)
3 examples, 0 failures