refactor(test): improve readability and maintainability

by extracting setup data into lets, enhancing context and example descriptions, and removing duplication

Author: patrickgramatowski

spec/doc_guard/assess_documentation_relevance/process_spec.rb

@@ -3,21 +3,24 @@
 require "spec_helper"
 
 RSpec.describe DocGuard::AssessDocumentationRelevance::Process do
-  subject(:process) { described_class.new(config: config) }
+  describe ".run" do
+    subject(:run_process) { described_class.run(config: config) }
 
-  let(:config) { instance_double(DocGuard::Config) }
+    let(:config) { instance_double(DocGuard::Config) }
+    let(:process_instance) { instance_double(described_class) }
 
-  describe ".run" do
     it "instantiates and calls #call" do
-      instance = instance_double(described_class)
-      expect(described_class).to receive(:new).with(config: config).and_return(instance)
-      expect(instance).to receive(:call)
+      expect(described_class).to receive(:new).with(config: config).and_return(process_instance)
+      expect(process_instance).to receive(:call)
 
-      described_class.run(config: config)
+      run_process
     end
   end
 
   describe "#call" do
+    subject(:process) { described_class.new(config: config) }
+
+    let(:config) { instance_double(DocGuard::Config) }
     let(:tracked_files) { { "docs/a.md" => ["lib/a.rb", "lib/b.rb"] } }
     let(:stored_digests) { { "docs/a.md" => { "lib/a.rb" => "digest1", "lib/b.rb" => "digest2" } } }
     let(:current_digests) { { "docs/a.md" => { "lib/a.rb" => "digest1", "lib/b.rb" => "digest_changed" } } }

spec/doc_guard/assess_documentation_relevance/subprocesses/assess_relevance_spec.rb

@@ -15,7 +15,7 @@
   context "when no source files have changed" do
     let(:mismatches) { [] }
 
-    it "returns relevant: false and empty mismatches" do
+    it "returns `relevant: false` and empty mismatches" do
       expect(assessment[:relevant]).to be false
       expect(assessment[:mismatches]).to be_empty
     end
@@ -24,7 +24,7 @@
   context "when some source files have changed" do
     let(:mismatches) { ["app/models/user.rb"] }
 
-    it "returns relevant: true" do
+    it "returns `relevant: true`" do
       expect(assessment[:relevant]).to be true
     end
 

spec/doc_guard/assess_documentation_relevance/subprocesses/compare_digests_spec.rb

@@ -4,19 +4,19 @@
 
 RSpec.describe DocGuard::AssessDocumentationRelevance::Subprocesses::CompareDigests do
   describe ".run" do
-    subject(:result) { described_class.run(stored_digests: stored, current_digests: current) }
+    subject(:result) { described_class.run(stored_digests: stored_digests, current_digests: current_digests) }
 
     context "when there are no tracked files" do
-      let(:stored) { {} }
-      let(:current) { {} }
+      let(:stored_digests) { {} }
+      let(:current_digests) { {} }
 
       it "returns an empty list" do
         expect(result).to eq([])
       end
     end
 
     context "when stored and current digests are identical" do
-      let(:stored) do
+      let(:stored_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123",
@@ -25,7 +25,7 @@
         }
       end
 
-      let(:current) do
+      let(:current_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123",
@@ -40,7 +40,7 @@
     end
 
     context "when there is a mismatch in digests for a tracked file" do
-      let(:stored) do
+      let(:stored_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123",
@@ -49,7 +49,7 @@
         }
       end
 
-      let(:current) do
+      let(:current_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123",
@@ -64,15 +64,15 @@
     end
 
     context "when a source file is missing in current digests" do
-      let(:stored) do
+      let(:stored_digests) do
         {
           "docs/admin.md" => {
             "app/models/admin.rb" => "abc123"
           }
         }
       end
 
-      let(:current) do
+      let(:current_digests) do
         {
           "docs/admin.md" => {
             # missing app/models/admin.rb
@@ -86,15 +86,15 @@
     end
 
     context "when new documentation files are introduced in current digests" do
-      let(:stored) do
+      let(:stored_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123"
           }
         }
       end
 
-      let(:current) do
+      let(:current_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123"
@@ -111,15 +111,15 @@
     end
 
     context "when stored digests have a doc file that current digests do not" do
-      let(:stored) do
+      let(:stored_digests) do
         {
           "docs/old.md" => {
             "app/old/file.rb" => "old_digest"
           }
         }
       end
 
-      let(:current) do
+      let(:current_digests) do
         {
           # docs/old.md missing entirely
         }
@@ -131,7 +131,7 @@
     end
 
     context "when multiple doc files have mismatches" do
-      let(:stored) do
+      let(:stored_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "abc123",
@@ -143,7 +143,7 @@
         }
       end
 
-      let(:current) do
+      let(:current_digests) do
         {
           "docs/user.md" => {
             "app/models/user.rb" => "changed_digest",

spec/doc_guard/assess_documentation_relevance/subprocesses/report_assessment_spec.rb

@@ -17,22 +17,23 @@
         }
       end
 
-      it "warns the user and exits with code 1" do
-        expect { report }.to output(/‼️ Documentation may be outdated!/).to_stderr.and raise_error(SystemExit) do |error|
+      it "warns the user with a message on stderr" do
+        expect { expect { report }.to raise_error(SystemExit) }
+          .to output(/‼️ Documentation may be outdated!/).to_stderr
+      end
+
+      it "exits with code 1" do
+        expect { report }.to raise_error(SystemExit) do |error|
           expect(error.status).to eq(1)
         end
       end
 
-      # rubocop:disable Layout/LineLength
       it "lists affected files in stderr" do
-        expect { report }
+        expect { expect { report }.to raise_error(SystemExit) }
           .to output(
-            /‼️ Documentation may be outdated!\n\n📄 docs\/user.md\n- app\/models\/user.rb\n- app\/services\/authenticator.rb\n\n📄 docs\/admin.md\n- app\/models\/admin.rb\n/
-          )
-          .to_stderr
-          .and raise_error(SystemExit) { |error| expect(error.status).to eq(1) }
+            /📄 docs\/user.md\n- app\/models\/user.rb\n- app\/services\/authenticator.rb\n\n📄 docs\/admin.md\n- app\/models\/admin.rb\n/
+          ).to_stderr
       end
-      # rubocop:enable Layout/LineLength
     end
 
     context "when documentation is up to date" do

spec/doc_guard/cli_spec.rb

@@ -6,7 +6,6 @@
   subject(:cli) { described_class.new }
 
   describe "assess command" do
-    let(:process_instance) { instance_double(DocGuard::AssessDocumentationRelevance::Process) }
     let(:config_instance) { instance_double(DocGuard::Config) }
 
     before do
@@ -27,10 +26,15 @@
       end
     end
 
-    context "When the assessment process found code changes relevant to the documentation" do
+    context "when the assessment process found code changes relevant to the documentation" do
       let(:relevant) { true }
 
-      it "exits with SystemExit" do
+      it "warns the user with a message on stderr" do
+        expect { expect { cli.invoke(:assess) }.to raise_error(SystemExit) }
+          .to output(/‼️ Documentation may be outdated!/).to_stderr
+      end
+
+      it "exits with code 1" do
         expect { cli.invoke(:assess) }.to raise_error(SystemExit) do |error|
           expect(error.status).to eq(1)
         end
@@ -40,13 +44,15 @@
     context "when process raises an unexpected error" do
       before { allow(DocGuard::AssessDocumentationRelevance::Process).to receive(:run).and_raise(StandardError.new("unexpected error")) }
 
-      it "prints error message to stderr and exits with status 2" do
-        expect { cli.invoke(:assess) }
-          .to output(/‼️ Error: unexpected error/)
-          .to_stderr
-          .and raise_error(SystemExit) do |error|
-            expect(error.status).to eq(2)
-          end
+      it "warns the user with a message on stderr" do
+        expect { expect { cli.invoke(:assess) }.to raise_error(SystemExit) }
+          .to output(/‼️ Error: unexpected error/).to_stderr
+      end
+
+      it "exits with code 2" do
+        expect { cli.invoke(:assess) }.to raise_error(SystemExit) do |error|
+          expect(error.status).to eq(2)
+        end
       end
     end
   end
@@ -83,11 +89,15 @@
         end
       end
 
-      it "prints failure message and exits with status 1" do
-        expect { cli.invoke(:record) }
-          .to output(/‼️ Failed to record documentation state: file write failed/)
-          .to_stderr
-          .and raise_error(SystemExit) { |e| expect(e.status).to eq(1) }
+      it "warns the user with a message on stderr" do
+        expect { expect { cli.invoke(:record) }.to raise_error(SystemExit) }
+          .to output(/‼️ Failed to record documentation state: file write failed/).to_stderr
+      end
+
+      it "exits with code 1" do
+        expect { cli.invoke(:record) }.to raise_error(SystemExit) do |error|
+          expect(error.status).to eq(1)
+        end
       end
     end
 
@@ -96,11 +106,15 @@
         allow(DocGuard::RecordDocumentationRelevance::Process).to receive(:run).and_raise(StandardError.new("unexpected failure"))
       end
 
-      it "prints error message and exits with status 2" do
-        expect { cli.invoke(:record) }
-          .to output(/‼️ Error: unexpected failure/)
-          .to_stderr
-          .and raise_error(SystemExit) { |e| expect(e.status).to eq(2) }
+      it "warns the user with a message on stderr" do
+        expect { expect { cli.invoke(:record) }.to raise_error(SystemExit) }
+          .to output(/‼️ Error: unexpected failure/).to_stderr
+      end
+
+      it "exits with code 2" do
+        expect { cli.invoke(:record) }.to raise_error(SystemExit) do |error|
+          expect(error.status).to eq(2)
+        end
       end
     end
   end

spec/doc_guard/config_spec.rb

@@ -146,9 +146,7 @@
 
         around do |example|
           ENV["DOC_GUARD_CONFIG_FILE_PATH"] = yaml_path.path
-
           example.run
-
           ENV.delete("DOC_GUARD_CONFIG_FILE_PATH")
         end
 

spec/doc_guard/record_documentation_relevance/process_spec.rb

@@ -4,28 +4,28 @@
 
 RSpec.describe DocGuard::RecordDocumentationRelevance::Process do
   describe ".run" do
-    let(:process) { instance_double(described_class) }
+    subject(:run_process) { described_class.run(config: config) }
+
     let(:config) { instance_double(DocGuard::Config) }
+    let(:process_instance) { instance_double(described_class) }
 
     it "instantiates and calls the process" do
-      expect(described_class).to receive(:new).with(config: config).and_return(process)
-      expect(process).to receive(:call)
+      expect(described_class).to receive(:new).with(config: config).and_return(process_instance)
+      expect(process_instance).to receive(:call)
 
-      described_class.run(config: config)
+      run_process
     end
   end
 
   describe "#call" do
     subject(:process) { described_class.new(config: config) }
 
     let(:config) { instance_double(DocGuard::Config) }
-
     let(:tracked_files) do
       {
         "docs/README.md" => ["lib/foo.rb", "lib/bar.rb"]
       }
     end
-
     let(:current_digests) do
       {
         "docs/README.md" => {
@@ -34,7 +34,6 @@
         }
       }
     end
-
     let(:recording) { { status: :ok } }
 
     before do

spec/doc_guard/record_documentation_relevance/subprocesses/record_digests_spec.rb

@@ -19,13 +19,12 @@
 
     context "when writing to file succeeds" do
       let(:config) { DocGuard::Config.new(digests_store_file_path: tmp_file_path) }
+      let(:stored_digests_content) { JSON.parse(File.read(tmp_file_path)) }
 
       it "writes the digests as JSON and returns `ok` status" do
         expect(recording[:status]).to eq(:ok)
         expect(File).to exist(tmp_file_path)
-
-        json = JSON.parse(File.read(tmp_file_path))
-        expect(json).to eq(digests.transform_keys(&:to_s))
+        expect(stored_digests_content).to eq(digests.transform_keys(&:to_s))
       end
     end
 

spec/doc_guard/record_documentation_relevance/subprocesses/report_recording_spec.rb

@@ -6,20 +6,25 @@
   describe ".run" do
     subject(:report) { described_class.run(recording: recording) }
 
-    context "when recording status is :ok" do
+    context "when recording status is `ok`" do
       let(:recording) { { status: :ok } }
 
       it "prints success message to stdout" do
         expect { report }.to output("✅ Documentation state recorded successfully.\n").to_stdout
       end
     end
 
-    context "when recording status is :error" do
+    context "when recording status is `error`" do
       let(:recording) { { status: :error, error: error } }
       let(:error) { StandardError.new("something went wrong") }
 
-      it "warns the user and exits with code 1" do
-        expect { report }.to output(/‼️ Failed to record documentation state: something went wrong/).to_stderr.and raise_error(SystemExit) do |error|
+      it "warns the user with a message on stderr" do
+        expect { expect { report }.to raise_error(SystemExit) }
+          .to output(/‼️ Failed to record documentation state: something went wrong/).to_stderr
+      end
+
+      it "exits with code 1" do
+        expect { report }.to raise_error(SystemExit) do |error|
           expect(error.status).to eq(1)
         end
       end