Merge pull request mongodb#2082 from jonhyman/feature/update_findandm…

…odify_docs_for_upsert

Updating comments for find_and_modify to say that :upsert is a valid option; adding specs.

lib/mongoid/contextual/find_and_modify.rb

@@ -16,6 +16,7 @@ class FindAndModify
       #
       # @option options [ true, false ] :new Return the updated document.
       # @option options [ true, false ] :remove Delete the first document.
+      # @option options [ true, false ] :upsert Create the document if it doesn't exist.
       #
       # @since 3.0.0
       def initialize(criteria, update, options = {})

lib/mongoid/contextual/mongo.rb

@@ -174,6 +174,7 @@ def explain
       #
       # @option options [ true, false ] :new Return the updated document.
       # @option options [ true, false ] :remove Delete the first document.
+      # @option options [ true, false ] :upsert Create the document if it doesn't exist.
       #
       # @return [ Document ] The result of the command.
       #

spec/mongoid/contextual/find_and_modify_spec.rb

@@ -134,6 +134,37 @@
           }.to raise_error(Mongoid::Errors::DocumentNotFound)
         end
       end
+
+      context "when upserting" do
+
+        let(:criteria) do
+          Band.where(name: "The Mars Volta")
+        end
+
+        let(:context) do
+          described_class.new(criteria, { "$inc" => { likes: 1 }}, upsert: true)
+        end
+
+        let(:result) do
+          context.result
+        end
+
+        it "creates the document if it does not exist" do
+          expect {
+            result
+          }.to change{Band.where(name: "The Mars Volta").count}.from(0).to(1)
+        end
+
+        it "updates the document in the database if it does exist" do
+          the_mars_volta = Band.create(name: "The Mars Volta")
+
+          expect {
+            result
+          }.to_not change{Band.where(name: "The Mars Volta").count}
+
+          the_mars_volta.reload.likes.should eq(1)
+        end
+      end
     end
 
     context "when the selector does not match" do