[Fix rubocop#1337] Update the cop to raise error for insufficient des…

…criptions.

CHANGELOG.md

@@ -11,6 +11,7 @@
 * Fix a false positive for `RSpec/Capybara/SpecificMatcher`. ([@ydah][])
 * Fix a false negative for `RSpec/Capybara/SpecificMatcher` for `have_field`. ([@ydah][])
 * Fix a false positive for `RSpec/Capybara/SpecificMatcher` when may not have a `href` by `have_link`. ([@ydah][])
+* Update `RSpec/ExampleWording` cop to raise error for insufficient descriptions. ([@akrox58][])
 
 ## 2.12.1 (2022-07-03)
 
@@ -623,6 +624,7 @@ Compatibility release so users can upgrade RuboCop to 0.51.0. No new features.
 [@abrom]: https://github.com/abrom
 [@ahukkanen]: https://github.com/ahukkanen
 [@akiomik]: https://github.com/akiomik
+[@akrox58]: https://github.com/akrox58
 [@AlexWayfer]: https://github.com/AlexWayfer
 [@andrykonchin]: https://github.com/andrykonchin
 [@andyw8]: https://github.com/andyw8

config/default.yml

@@ -368,8 +368,10 @@ RSpec/ExampleWording:
     have: has
     HAVE: HAS
   IgnoredWords: []
+  DisallowedExamples:
+    - works
   VersionAdded: '1.0'
-  VersionChanged: '1.2'
+  VersionChanged: '2.13'
   StyleGuide: https://rspec.rubystyle.guide/#should-in-example-docstrings
   Reference: https://www.rubydoc.info/gems/rubocop-rspec/RuboCop/Cop/RSpec/ExampleWording
 

docs/modules/ROOT/pages/cops_rspec.adoc

@@ -1407,16 +1407,21 @@ end
 | Yes
 | Yes
 | 1.0
-| 1.2
+| 2.13
 |===
 
 Checks for common mistakes in example descriptions.
 
 This cop will correct docstrings that begin with 'should' and 'it'.
+This cop will also look for insufficient examples and call them out.
 
 The autocorrect is experimental - use with care! It can be configured
 with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
 
+Use the DisallowedExamples setting to prevent unclear or insufficient
+descriptions. Please note that this config will not be treated as
+case sensitive.
+
 === Examples
 
 [source,ruby]
@@ -1441,6 +1446,19 @@ it 'does things' do
 end
 ----
 
+==== `DisallowedExamples: ['works']` (default)
+
+[source,ruby]
+----
+# bad
+it 'works' do
+end
+
+# good
+it 'marks the task as done' do
+end
+----
+
 === Configurable attributes
 
 |===
@@ -1453,6 +1471,10 @@ end
 | IgnoredWords
 | `[]`
 | Array
+
+| DisallowedExamples
+| `works`
+| Array
 |===
 
 === References

lib/rubocop/cop/rspec/example_wording.rb

@@ -6,12 +6,17 @@ module RSpec
       # Checks for common mistakes in example descriptions.
       #
       # This cop will correct docstrings that begin with 'should' and 'it'.
+      # This cop will also look for insufficient examples and call them out.
       #
       # @see http://betterspecs.org/#should
       #
       # The autocorrect is experimental - use with care! It can be configured
       # with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
       #
+      # Use the DisallowedExamples setting to prevent unclear or insufficient
+      # descriptions. Please note that this config will not be treated as
+      # case sensitive.
+      #
       # @example
       #   # bad
       #   it 'should find nothing' do
@@ -29,11 +34,21 @@ module RSpec
       #   # good
       #   it 'does things' do
       #   end
+      #
+      # @example `DisallowedExamples: ['works']` (default)
+      #   # bad
+      #   it 'works' do
+      #   end
+      #
+      #   # good
+      #   it 'marks the task as done' do
+      #   end
       class ExampleWording < Base
         extend AutoCorrector
 
         MSG_SHOULD = 'Do not use should when describing your tests.'
         MSG_IT     = "Do not repeat 'it' when describing your tests."
+        MSG_INSUFFICIENT_DESCRIPTION = 'Your test should be more descriptive.'
 
         SHOULD_PREFIX = /\Ashould(?:n't)?\b/i.freeze
         IT_PREFIX     = /\Ait /i.freeze
@@ -52,6 +67,9 @@ def on_block(node)
               add_wording_offense(description_node, MSG_SHOULD)
             elsif message.match?(IT_PREFIX)
               add_wording_offense(description_node, MSG_IT)
+            elsif insufficient_examples.include?(preprocess(message))
+              add_wording_offense(description_node,
+                                  MSG_INSUFFICIENT_DESCRIPTION)
             end
           end
         end
@@ -112,6 +130,15 @@ def custom_transform
         def ignored_words
           cop_config.fetch('IgnoredWords', [])
         end
+
+        def insufficient_examples
+          examples = cop_config.fetch('DisallowedExamples', [])
+          examples.map! { |example| preprocess(example) }
+        end
+
+        def preprocess(message)
+          message.strip.squeeze(' ').downcase
+        end
       end
     end
   end

spec/rubocop/cop/rspec/example_wording_spec.rb

@@ -187,4 +187,62 @@
       end
     RUBY
   end
+
+  it 'flags an unclear description' do
+    expect_offense(<<-'RUBY')
+      it "works" \
+          ^^^^^^^^ Your test should be more descriptive.
+        "with #{object}" do
+      end
+    RUBY
+  end
+
+  it 'flags an unclear description despite extra spaces' do
+    expect_offense(<<-'RUBY')
+      it "  works    " \
+          ^^^^^^^^^^^^^^ Your test should be more descriptive.
+        "with #{object}" do
+      end
+    RUBY
+  end
+
+  it 'flags an unclear description despite uppercase and lowercase strings' do
+    expect_offense(<<-'RUBY')
+      it "WOrKs " \
+          ^^^^^^^^^ Your test should be more descriptive.
+        "with #{object}" do
+      end
+    RUBY
+  end
+
+  context 'when `DisallowedExamples: Workz`' do
+    let(:cop_config) { { 'DisallowedExamples' => ['Workz'] } }
+
+    it 'flags an unclear description' do
+      expect_offense(<<-'RUBY')
+        it "workz" \
+            ^^^^^^^^ Your test should be more descriptive.
+          "with #{object}" do
+        end
+      RUBY
+    end
+
+    it 'flags an unclear description despite extra spaces' do
+      expect_offense(<<-'RUBY')
+        it "  workz    " \
+            ^^^^^^^^^^^^^^ Your test should be more descriptive.
+          "with #{object}" do
+        end
+      RUBY
+    end
+
+    it 'flags an unclear description despite uppercase and lowercase strings' do
+      expect_offense(<<-'RUBY')
+        it "WOrKz " \
+            ^^^^^^^^^ Your test should be more descriptive.
+          "with #{object}" do
+        end
+      RUBY
+    end
+  end
 end