Apply suggestions from code review

Commit grammar improvements

Co-authored-by: Jon Rowe <mail@jonrowe.co.uk>

Author: skatkov

features/matchers/README.md

@@ -28,6 +28,6 @@ expect(assigns(:widget)).to be_a_new(Widget)
 ### error reporting
 
 ```ruby
-# passes if Rails.error.report was called with specific error instance and message
+# passes when `Rails.error.report` is called with specific error instance and message
 expect { Rails.error.report(MyError.new("message")) }.to have_reported_error(MyError.new("message"))
 ```

features/matchers/have_reported_error_matcher.feature

@@ -6,7 +6,7 @@ Feature: `have_reported_error` matcher
 
   The matcher supports several matching strategies:
   * Any error reported
-  * Specific error class
+  * A specific error class
   * Specific error instance with message
   * Error message patterns using regular expressions
   * Error attributes using `.with()`
@@ -18,6 +18,7 @@ Feature: `have_reported_error` matcher
     Given a file named "app/models/user.rb" with:
       """ruby
       class User < ApplicationRecord
+        class ValidationError < StandardError; end
         def self.process_data
           Rails.error.report(StandardError.new("Processing failed"))
         end
@@ -31,19 +32,14 @@ Feature: `have_reported_error` matcher
         end
       end
       """
-    And a file named "app/errors/validation_error.rb" with:
-      """ruby
-      class ValidationError < StandardError
-      end
-      """
 
   Scenario: Checking for any error being reported
     Given a file named "spec/models/user_spec.rb" with:
       """ruby
       require "rails_helper"
 
       RSpec.describe User do
-        it "reports an error during processing" do
+        it "reports errors" do
           expect {
             User.process_data
           }.to have_reported_error
@@ -53,7 +49,7 @@ Feature: `have_reported_error` matcher
     When I run `rspec spec/models/user_spec.rb`
     Then the examples should all pass
 
-  Scenario: Checking for specific error class
+  Scenario: Checking for a specific error class
     Given a file named "spec/models/user_spec.rb" with:
       """ruby
       require "rails_helper"
@@ -97,29 +93,23 @@ Feature: `have_reported_error` matcher
     When I run `rspec spec/models/user_spec.rb`
     Then the examples should all pass
 
-  Scenario: Checking error message patterns with regular expressions
+  Scenario: Checking error messages using regular expressions
     Given a file named "spec/models/user_spec.rb" with:
       """ruby
       require "rails_helper"
 
       RSpec.describe User do
-        it "reports error with message matching pattern" do
+        it "reports errors with a message matching a pattern" do
           expect {
             User.process_data
           }.to have_reported_error(/Processing/)
         end
-
-        it "reports error with message containing 'failed'" do
-          expect {
-            User.process_data
-          }.to have_reported_error(/failed$/)
-        end
       end
       """
     When I run `rspec spec/models/user_spec.rb`
     Then the examples should all pass
 
-  Scenario: Checking error attributes using `with`
+  Scenario: Constraining error matches to their attributes using `with`
     Given a file named "spec/models/user_spec.rb" with:
       """ruby
       require "rails_helper"

lib/rspec/rails/matchers/have_reported_error.rb

@@ -3,7 +3,7 @@
 module RSpec
   module Rails
     module Matchers
-      # @private
+      # @api private
       class ErrorSubscriber
         attr_reader :events
 
@@ -20,7 +20,7 @@ def report(error, **attrs)
 
       # Matcher class for `have_reported_error`. Should not be instantiated directly.
       #
-      # @private
+      # @api private
       # @see RSpec::Rails::Matchers#have_reported_error
       class HaveReportedError < RSpec::Rails::Matchers::BaseMatcher
         def initialize(expected_error = nil)

spec/rspec/rails/matchers/have_reported_error_spec.rb

@@ -4,38 +4,38 @@
   class TestError < StandardError; end
   class AnotherTestError < StandardError; end
 
-  it "has an reports_error alias" do
+  it "is aliased as reports_error" do
     expect {Rails.error.report(StandardError.new("test error"))}.to reports_error
   end
 
-  it "warns that passing value expectation doesn't work" do
+  it "warns when used as a value expectation" do
     expect {
       expect(Rails.error.report(StandardError.new("test error"))).to have_reported_error
     }.to raise_error(ArgumentError, "this matcher doesn’t work with value expectations")
   end
 
-  describe "basic functionality" do
+  context "without constraint" do
     it "passes when an error is reported" do
       expect {Rails.error.report(StandardError.new("test error"))}.to have_reported_error
     end
 
-    it "fails when no error is reported" do
+    it "fails when no errors are reported" do
       expect {
         expect { "no error" }.to have_reported_error
       }.to fail_with(/Expected the block to report an error, but none was reported./)
     end
 
-    it "passes when negated and no error is reported" do
+    it "passes when negated and no errors are reported" do
       expect { "no error" }.not_to have_reported_error
     end
   end
 
-  describe "error class matching" do
-    it "passes when correct error class is reported" do
+  context "constrained to a specific error class" do
+    it "passes when an error with the correct class is reported" do
       expect { Rails.error.report(TestError.new("test error")) }.to have_reported_error(TestError)
     end
 
-    it "fails when wrong error class is reported" do
+    it "fails when an error with the wrong class is reported" do
       expect {
         expect {
           Rails.error.report(AnotherTestError.new("wrong error"))
@@ -44,20 +44,20 @@ class AnotherTestError < StandardError; end
     end
   end
 
-  describe "error instance matching" do
-    it "passes when error instance matches exactly" do
+  context "constrained to a matching error (class and message)" do
+    it "passes with an error that matches exactly" do
       expect {
         Rails.error.report(TestError.new("exact message"))
       }.to have_reported_error(TestError.new("exact message"))
     end
 
-    it "passes when error instance has empty expected message" do
+    it "passes any error of the same class if the expected message is empty" do
       expect {
         Rails.error.report(TestError.new("any message"))
       }.to have_reported_error(TestError.new(""))
     end
 
-    it "fails when error instance has different message" do
+    it "fails when the error has different message to the expected" do
       expect {
         expect {
           Rails.error.report(TestError.new("actual message"))
@@ -66,14 +66,14 @@ class AnotherTestError < StandardError; end
     end
   end
 
-  describe "regex pattern matching" do
-    it "passes when error message matches pattern" do
+  context "constrained by regex pattern matching" do
+    it "passes when an error message matches the pattern" do
       expect {
         Rails.error.report(StandardError.new("error with pattern"))
       }.to have_reported_error(/with pattern/)
     end
 
-    it "fails when error message does not match pattern" do
+    it "fails when no error messages match the pattern" do
       expect {
         expect {
           Rails.error.report(StandardError.new("error without match"))
@@ -82,8 +82,8 @@ class AnotherTestError < StandardError; end
     end
   end
 
-  describe "failure messages for attribute mismatches" do
-    it "provides detailed failure message when attributes don't match" do
+  describe "#failure_message" do
+    it "provides details about mismatched attributes" do
       expect {
         expect {
           Rails.error.report(StandardError.new("test"), context: { user_id: 123, context: "actual" })
@@ -116,7 +116,7 @@ class AnotherTestError < StandardError; end
     end
   end
 
-  describe "attribute matching with .with chain" do
+  describe "#with" do
     it "passes when attributes match exactly" do
       expect {
         Rails.error.report(StandardError.new("test"), context: { user_id: 123, context: "test" })