fix: make error messages consistent

Change 1:

Error messages should consistently use the "expected ... but it ..." format.

Reviewed all error messages in the project.

Change 2:
Changed all tests that have error message expectations from:

```
expect { subject }.to raise_error(ArgumentError, expected_message)
```

to:

```
expect { subject }.to raise_error(ArgumentError) do |error|
  expect(error.message).to match(expected_message)
end
```

so that error messages are diff'd when they don't match.

Author: jcouball

README.md

@@ -287,8 +287,8 @@ expect('config').to(
 ```text
 'config' was not as expected:
   - database.xml
-      expected owner to be "db_user", but was "root"
-      expected mode to be "0600", but was "0644"
+      expected owner to be "db_user", but it was "root"
+      expected mode to be "0600", but it was "0644"
 ```
 
 ## Development

lib/rspec/path_matchers/matchers/directory_matcher.rb

@@ -164,7 +164,7 @@ def check_for_unexpected_entries
         end
 
         def build_unexpected_entries_message(unexpected_entries)
-          "contained unexpected entries #{unexpected_entries.sort.inspect}"
+          "expected no other entries, but found #{unexpected_entries.sort.inspect}"
         end
       end
     end

lib/rspec/path_matchers/options/base.rb

@@ -102,7 +102,7 @@ def self.validate_expected(expected, errors)
 
           types = ['Matcher', *valid_expected_types.map(&:name)].to_sentence(conjunction: 'or')
 
-          errors << "expected `#{key}:` to be a #{types}, but was #{expected.inspect}"
+          errors << "expected `#{key}:` to be a #{types}, but it was #{expected.inspect}"
         end
 
         protected
@@ -189,6 +189,36 @@ def self.validate_expected(expected, errors)
         #
         private_class_method def self.literal_match?(actual, expected) = actual == expected
 
+        # Add to `failures` if actual value matches the normalized expected value
+        #
+        # This is called when expected is not an RSpec matcher.
+        #
+        # Option subclasses should override this method to provide custom matching
+        # logic or custom failure messages.
+        #
+        # @param actual [Object] the actual value fetched from the file system
+        #
+        # @param expected [Object] the expected literal value to match against
+        #
+        # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
+        # failure objects to (if any)
+        #
+        # @return [void]
+        #
+        # @api protected
+        #
+        private_class_method def self.match_literal(actual, expected, failures)
+          expected = normalize_expected_literal(expected)
+
+          return if literal_match?(actual, expected)
+
+          add_failure(literal_failure_message(actual, expected), failures)
+        end
+
+        private_class_method def self.add_failure(message, failures)
+          failures << RSpec::PathMatchers::Failure.new('.', message)
+        end
+
         # Generates a failure message for a literal match failure
         #
         # This is used when the actual value does not match the expected value.
@@ -201,9 +231,9 @@ def self.validate_expected(expected, errors)
         # @example generate a failure message for a literal match failure
         #  def self.literal_failure_message(actual, expected)
         #    if expected.is_a?(Regexp)
-        #      "expected #{key} to match #{expected.inspect}, but was #{actual.inspect}"
+        #      "expected #{key} to match #{expected.inspect}, but it was #{actual.inspect}"
         #    else
-        #      "expected #{key} to be #{expected.inspect}, but was #{actual.inspect}"
+        #      "expected #{key} to be #{expected.inspect}, but it was #{actual.inspect}"
         #    end
         #  end
         #
@@ -216,19 +246,19 @@ def self.validate_expected(expected, errors)
         # @api protected
         #
         private_class_method def self.literal_failure_message(actual, expected)
-          "expected #{key} to be #{expected.inspect}, but was #{actual.inspect}"
+          "expected #{key} to be #{expected.inspect}, but it was #{actual.inspect}"
         end
 
         # Add to `failures` if actual value matches the normalized expected value
         #
-        # This is called when expected is not an RSpec matcher.
+        # This is called when expected is an RSpec matcher.
         #
         # Option subclasses should override this method to provide custom matching
         # logic or custom failure messages.
         #
         # @param actual [Object] the actual value fetched from the file system
         #
-        # @param expected [Object] the expected literal value to match against
+        # @param expected [RSpec::Matchers::Matcher] the expected matcher to match against
         #
         # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
         # failure objects to (if any)
@@ -237,42 +267,31 @@ def self.validate_expected(expected, errors)
         #
         # @api protected
         #
-        private_class_method def self.match_literal(actual, expected, failures)
-          expected = normalize_expected_literal(expected)
-
-          return if literal_match?(actual, expected)
-
-          message = literal_failure_message(actual, expected)
-          add_failure(message, failures)
-        end
+        private_class_method def self.match_matcher(actual, expected, failures)
+          return if expected.matches?(actual)
 
-        private_class_method def self.add_failure(message, failures)
-          failures << RSpec::PathMatchers::Failure.new('.', message)
+          add_failure(matcher_failure_message(actual, expected), failures)
         end
 
-        # Add to `failures` if actual value matches the normalized expected value
+        # Generates a failure message for a matcher match failure
         #
-        # This is called when expected is an RSpec matcher.
+        # This is used when the actual value does not match the expected value.
+        # It provides a clear message indicating what was expected and what was
+        # actually found.
         #
-        # Option subclasses should override this method to provide custom matching
-        # logic or custom failure messages.
+        # Option subclasses should override this method to provide custom failure
+        # messages for specific types of options.
         #
         # @param actual [Object] the actual value fetched from the file system
         #
-        # @param expected [RSpec::Matchers::Matcher] the expected matcher to match against
-        #
-        # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
-        # failure objects to (if any)
+        # @param expected [Object] the expected literal value to match against
         #
-        # @return [void]
+        # @return [String] the failure message
         #
         # @api protected
         #
-        private_class_method def self.match_matcher(actual, expected, failures)
-          return if expected.matches?(actual)
-
-          message = "expected #{key} to #{expected.description}, but was #{actual.inspect}"
-          add_failure(message, failures)
+        private_class_method def self.matcher_failure_message(actual, expected)
+          "expected #{key} to #{expected.description}, but it was #{actual.inspect}"
         end
 
         # Warning message for unsupported expectations

lib/rspec/path_matchers/options/content.rb

@@ -11,18 +11,28 @@ def self.key = :content
         def self.fetch_actual(path, _failures) = File.read(path)
         def self.valid_expected_types = [String, Regexp]
 
+        # Override to provide custom matching logic for regexp literals
         def self.literal_match?(actual, expected)
-          return expected.match?(actual) if expected.is_a?(Regexp)
+          expected.is_a?(Regexp) ? expected.match?(actual) : super
+        end
 
-          super
+        # Handles failures when a matcher is used (e.g., content: include('...'))
+        def self.matcher_failure_message(actual, expected)
+          actual_summary = actual.length > 100 ? 'did not' : "was #{actual.inspect}"
+          "expected content to #{expected.description}, but it #{actual_summary}"
         end
 
         def self.literal_failure_message(actual, expected)
-          if expected.is_a?(Regexp)
-            "expected content to match #{expected.inspect}, but got #{actual.inspect}"
-          else
-            super
-          end
+          verb = expected.is_a?(Regexp) ? 'match' : 'be'
+
+          actual_summary =
+            if actual.length > 100
+              verb == 'match' ? 'did not' : 'was not'
+            else
+              "was #{actual.inspect}"
+            end
+
+          "expected content to #{verb} #{expected.inspect}, but it #{actual_summary}"
         end
       end
     end

lib/rspec/path_matchers/options/parsed_content_base.rb

@@ -29,17 +29,16 @@ def self.fetch_actual(path, failures)
         # This is the `xxxx_content: true` case. A successful fetch_actual is sufficient
         def self.match_literal(_actual, _expected, _failures); end
 
-        # Compares the parsed content against the given RSpec matcher.
+        # Failure message for when a matcher is used (e.g., `json_content: include(...)`)
         #
         # @param (see RSpec::PathMatchers::Options::Base.match_matcher)
         #
         # @return [void]
         #
-        def self.match_matcher(actual, expected, failures)
-          return if expected.matches?(actual)
+        def self.matcher_failure_message(actual, expected)
+          actual_summary = actual.inspect.length > 100 ? 'it did not' : "was #{actual.inspect}"
 
-          message = "expected #{content_type} content to #{expected.description}"
-          add_failure(message, failures)
+          "expected #{content_type} content to #{expected.description}, but #{actual_summary}"
         end
 
         # Provides a human-readable description for the option

spec/rspec/path_matchers/be_dir_exact_spec.rb

@@ -119,7 +119,7 @@
             expected_message = <<~MESSAGE.chomp
               #{tmpdir} was not as expected:
                 - #{entry_name}
-                    contained unexpected entries ["file1.txt"]
+                    expected no other entries, but found ["file1.txt"]
             MESSAGE
 
             expect { subject }.to raise_error(expectation_not_met_error) do |error|
@@ -195,7 +195,9 @@
           it 'should fail with the `no_file` failure message' do
             # This ensures the `no_file` check runs and its failure message is prioritized.
             expected_message = /expected file 'file2.txt' not to be found at '.*', but it exists/
-            expect { subject }.to raise_error(expectation_not_met_error, expected_message)
+            expect { subject }.to raise_error(expectation_not_met_error) do |error|
+              expect(error.message).to match(expected_message)
+            end
           end
         end
 
@@ -266,7 +268,7 @@
             expected_message = <<~MESSAGE.chomp
               #{tmpdir} was not as expected:
                 - dir/nested_dir
-                    contained unexpected entries ["unexpected_file1.txt", "unexpected_file2.txt"]
+                    expected no other entries, but found ["unexpected_file1.txt", "unexpected_file2.txt"]
             MESSAGE
             expect { subject }.to raise_error(expectation_not_met_error) do |error|
               expect(error.message).to eq(expected_message)