update operator matcher feature

features/built_in_matchers/operators.feature

@@ -1,25 +1,27 @@
 Feature: operator matchers
 
   RSpec provides a number of matchers that are based on Ruby's built-in
-  operators. These pretty much work like you expect. For example, each of these
+  operators. These pretty much work like you expect except that they require
+  the `be` matcher when using the `expect` syntax. For example, each of these
   pass:
 
     ```ruby
-    expect(7).to == 7
-    expect([1, 2, 3]).to == [1, 2, 3]
-    expect("this is a string").to =~ /^this/
-    expect("this is a string").not_to =~ /^that/
-    expect(String).to === "this is a string"
+    expect(7).to be == 7
+    expect([1, 2, 3]).to be == [1, 2, 3]
+    expect("this is a string").to be =~ /^this/
+    expect("this is a string").not_to be =~ /^that/
+    expect(String).to be === "this is a string"
     ```
 
-  You can also use comparison operators combined with the "be" matcher like
-  this:
+  You can also use comparison operators without the "be" matcher when using
+  the `should` syntax:
 
     ```ruby
-    expect(37).to be < 100
-    expect(37).to be <= 38
-    expect(37).to be >= 2
-    expect(37).to be > 7
+    7.should == 7
+    [1, 2, 3].should == [1, 2, 3]
+    "this is a string".should =~ /^this/
+    "this is a string".should_not =~ /^that/
+    String.should === "this is a string"
     ```
 
   RSpec also provides a `=~` matcher for arrays that disregards differences in
@@ -38,151 +40,135 @@ Feature: operator matchers
   Scenario: numeric operator matchers
     Given a file named "numeric_operator_matchers_spec.rb" with:
       """ruby
-      describe 18 do
-        it { should == 18 }
-        it { should be < 20 }
-        it { should be > 15 }
-        it { should be <= 19 }
-        it { should be >= 17 }
+      describe do
+        example { expect(18).to be == 18 }
+        example { expect(18).to be < 20 }
+        example { expect(18).to be > 15 }
+        example { expect(18).to be <= 19 }
+        example { expect(18).to be >= 17 }
 
-        it { should_not == 28 }
+        example { expect(18).to_not be == 28 }
 
         # deliberate failures
-        it { should == 28 }
-        it { should be < 15 }
-        it { should be > 20 }
-        it { should be <= 17 }
-        it { should be >= 19 }
+        example { expect(18).to be == 28 }
+        example { expect(18).to be < 15 }
+        example { expect(18).to be > 20 }
+        example { expect(18).to be <= 17 }
+        example { expect(18).to be >= 19 }
 
-        it { should_not == 18 }
       end
       """
      When I run `rspec numeric_operator_matchers_spec.rb`
-     Then the output should contain "12 examples, 6 failures"
+     Then the output should contain "11 examples, 5 failures"
       And the output should contain:
       """
-           Failure/Error: it { should == 28 }
-             expected: 28
-                  got: 18 (using ==)
+           Failure/Error: example { expect(18).to be == 28 }
+             expected: == 28
+                  got:    18
       """
       And the output should contain:
       """
-           Failure/Error: it { should be < 15 }
+           Failure/Error: example { expect(18).to be < 15 }
              expected: < 15
                   got:   18
       """
       And the output should contain:
       """
-           Failure/Error: it { should be > 20 }
+           Failure/Error: example { expect(18).to be > 20 }
              expected: > 20
                   got:   18
       """
       And the output should contain:
       """
-           Failure/Error: it { should be <= 17 }
+           Failure/Error: example { expect(18).to be <= 17 }
              expected: <= 17
                   got:    18
       """
       And the output should contain:
       """
-           Failure/Error: it { should be >= 19 }
+           Failure/Error: example { expect(18).to be >= 19 }
              expected: >= 19
                   got:    18
       """
-      And the output should contain:
-      """
-           Failure/Error: it { should_not == 18 }
-             expected not: == 18
-                      got:    18
-      """
 
   Scenario: string operator matchers
     Given a file named "string_operator_matchers_spec.rb" with:
       """ruby
-      describe "Strawberry" do
-        it { should == "Strawberry" }
-        it { should be < "Tomato" }
-        it { should be > "Apple" }
-        it { should be <= "Turnip" }
-        it { should be >= "Banana" }
-        it { should =~ /berry/ }
+      describe do
+        example { expect("Strawberry").to be == "Strawberry" }
+        example { expect("Strawberry").to be < "Tomato" }
+        example { expect("Strawberry").to be > "Apple" }
+        example { expect("Strawberry").to be <= "Turnip" }
+        example { expect("Strawberry").to be >= "Banana" }
+        example { expect("Strawberry").to be =~ /berry/ }
 
-        it { should_not == "Peach" }
-        it { should_not =~ /apple/ }
+        example { expect("Strawberry").to_not be == "Peach" }
+        example { expect("Strawberry").to_not be =~ /apple/ }
 
         it "reports that it is a string using ===" do
           expect(String).to be === subject
         end
 
         # deliberate failures
-        it { should == "Peach" }
-        it { should be < "Cranberry" }
-        it { should be > "Zuchini" }
-        it { should be <= "Potato" }
-        it { should be >= "Tomato" }
-        it { should =~ /apple/ }
+        example { expect("Strawberry").to be == "Peach" }
+        example { expect("Strawberry").to be < "Cranberry" }
+        example { expect("Strawberry").to be > "Zuchini" }
+        example { expect("Strawberry").to be <= "Potato" }
+        example { expect("Strawberry").to be >= "Tomato" }
+        example { expect("Strawberry").to be =~ /apple/ }
 
-        it { should_not == "Strawberry" }
-        it { should_not =~ /berry/ }
+        example { expect("Strawberry").to_not be =~ /berry/ }
 
         it "fails a spec asserting that it is a symbol" do
-          expect(Symbol).to be === subject
+          expect(Symbol).to be === "Strawberry"
         end
       end
       """
      When I run `rspec string_operator_matchers_spec.rb`
-     Then the output should contain "18 examples, 9 failures"
+     Then the output should contain "17 examples, 8 failures"
       And the output should contain:
       """
-           Failure/Error: it { should == "Peach" }
-             expected: "Peach"
-                  got: "Strawberry" (using ==)
+           Failure/Error: example { expect("Strawberry").to be == "Peach" }
+             expected: == "Peach"
+                  got:    "Strawberry"
       """
       And the output should contain:
       """
-           Failure/Error: it { should be < "Cranberry" }
+           Failure/Error: example { expect("Strawberry").to be < "Cranberry" }
              expected: < "Cranberry"
                   got:   "Strawberry"
       """
       And the output should contain:
       """
-           Failure/Error: it { should be > "Zuchini" }
+           Failure/Error: example { expect("Strawberry").to be > "Zuchini" }
              expected: > "Zuchini"
                   got:   "Strawberry"
       """
       And the output should contain:
       """
-           Failure/Error: it { should be <= "Potato" }
+           Failure/Error: example { expect("Strawberry").to be <= "Potato" }
              expected: <= "Potato"
                   got:    "Strawberry"
       """
       And the output should contain:
       """
-           Failure/Error: it { should be >= "Tomato" }
+           Failure/Error: example { expect("Strawberry").to be >= "Tomato" }
              expected: >= "Tomato"
                   got:    "Strawberry"
       """
       And the output should contain:
       """
-           Failure/Error: it { should =~ /apple/ }
-             expected: /apple/
-                  got: "Strawberry" (using =~)
-      """
-      And the output should contain:
-      """
-           Failure/Error: it { should_not == "Strawberry" }
-             expected not: == "Strawberry"
-                      got:    "Strawberry"
+           Failure/Error: example { expect("Strawberry").to be =~ /apple/ }
+             expected: =~ /apple/
+                  got:    "Strawberry"
       """
       And the output should contain:
       """
-           Failure/Error: it { should_not =~ /berry/ }
-             expected not: =~ /berry/
-                      got:    "Strawberry"
+           Failure/Error: example { expect("Strawberry").to_not be =~ /berry/ }
       """
       And the output should contain:
       """
-           Failure/Error: expect(Symbol).to be === subject
+           Failure/Error: expect(Symbol).to be === "Strawberry"
              expected: === "Strawberry"
                   got:     Symbol
       """