mongoid 9.0.11 → 9.1.1

data/spec/mongoid/criteria/includable_spec.rb

@@ -1,28 +1,27 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
-require "spec_helper"
-require_relative "./includable_spec_models.rb"
+require 'spec_helper'
+require_relative 'includable_spec_models'
 
 describe Mongoid::Criteria::Includable do
-
-  describe "#includes" do
-
+  shared_examples_for 'eager loading' do |method_name|
     let!(:person) do
       Person.create!(age: 1)
     end
 
-    context "when providing a name that is not a relation" do
+    context 'when providing a name that is not a relation' do
+      let(:expected_error) do
+        (method_name == :eager_load) ? ArgumentError : Mongoid::Errors::InvalidIncludes
+      end
 
-      it "raises an error" do
-        expect {
-          Person.includes(:members)
-        }.to raise_error(Mongoid::Errors::InvalidIncludes)
+      it 'raises an error' do
+        expect do
+          Person.send(method_name, :members)
+        end.to raise_error(expected_error)
       end
     end
 
-    context "when providing one association" do
-
+    context 'when providing one association' do
       let!(:user) do
         User.create!(posts: [ post1 ])
       end
@@ -32,20 +31,19 @@ describe Mongoid::Criteria::Includable do
       end
 
       let(:result) do
-        User.includes(:posts).first
+        User.send(method_name, :posts).first
       end
 
-      it "executes the query" do
+      it 'executes the query' do
         expect(result).to eq(user)
       end
 
-      it "includes the related objects" do
+      it 'includes the related objects' do
         expect(result.posts).to eq([ post1 ])
       end
     end
 
-    context "when providing a list of associations" do
-
+    context 'when providing a list of associations' do
       let!(:user) do
         User.create!(posts: [ post1 ], descriptions: [ description1 ])
       end
@@ -59,24 +57,26 @@ describe Mongoid::Criteria::Includable do
       end
 
       let(:result) do
-        User.includes(:posts, :descriptions).first
+        User.send(method_name, :posts, :descriptions).first
       end
 
-      it "executes the query" do
+      it 'executes the query' do
         expect(result).to eq(user)
       end
 
-      it "includes the related objects" do
+      it 'includes the related objects' do
         expect(result.posts).to eq([ post1 ])
         expect(result.descriptions).to eq([ description1 ])
       end
     end
 
-    context "when providing a nested association" do
-
+    context 'when providing a nested association' do
       let!(:user) do
         User.create!
       end
+      let(:result) do
+        User.send(method_name, posts: [ :alerts ]).first
+      end
 
       before do
         p = Post.create!(alerts: [ Alert.create! ])
@@ -84,37 +84,31 @@ describe Mongoid::Criteria::Includable do
         user.save!
       end
 
-      let(:result) do
-        User.includes(:posts => [:alerts]).first
-      end
-
-      it "executes the query" do
+      it 'executes the query' do
         expect(result).to eq(user)
       end
 
-      it "includes the related objects" do
+      it 'includes the related objects' do
         expect(result.posts.size).to eq(1)
         expect(result.posts.first.alerts.size).to eq(1)
       end
     end
 
-    context "when providing a deeply nested association" do
-
+    context 'when providing a deeply nested association' do
       let!(:user) do
         User.create!
       end
 
       let(:results) do
-        User.includes(:posts => [{ :alerts => :items }]).to_a
+        User.send(method_name, posts: [ { alerts: :items } ]).to_a
       end
 
-      it "executes the query" do
+      it 'executes the query' do
         expect(results.first).to eq(user)
       end
     end
 
-    context "when the models are inherited" do
-
+    context 'when the models are inherited' do
       before(:all) do
         class A
           include Mongoid::Document
@@ -126,6 +120,7 @@ describe Mongoid::Criteria::Includable do
 
         class C
           include Mongoid::Document
+
           has_one :b
         end
       end
@@ -136,8 +131,7 @@ describe Mongoid::Criteria::Includable do
         Object.send(:remove_const, :C)
       end
 
-      context "when the includes is on the subclass" do
-
+      context 'when the includes is on the subclass' do
         let!(:c_one) do
           C.create!
         end
@@ -151,16 +145,16 @@ describe Mongoid::Criteria::Includable do
         end
 
         let!(:results) do
-          C.includes(:b).to_a.detect do |c|
+          C.send(method_name, :b).to_a.detect do |c|
             c.id == c_two.id
           end
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(results).to eq(c_two)
         end
 
-        it "does not query the db" do
+        it 'does not query the db' do
           expect_query(0) do
             results.b
           end
@@ -168,10 +162,8 @@ describe Mongoid::Criteria::Includable do
       end
     end
 
-    context "when the models are inherited from another one model" do
-
-      context "when the relation is a has_one" do
-
+    context 'when the models are inherited from another one model' do
+      context 'when the relation is a has_one' do
         before(:all) do
           class A
             include Mongoid::Document
@@ -187,6 +179,7 @@ describe Mongoid::Criteria::Includable do
 
           class D
             include Mongoid::Document
+
             has_one :b
             has_one :c
           end
@@ -199,8 +192,7 @@ describe Mongoid::Criteria::Includable do
           Object.send(:remove_const, :D)
         end
 
-        context "when the includes is on the several relations" do
-
+        context 'when the includes is on the several relations' do
           let!(:d_one) do
             D.create!
           end
@@ -218,31 +210,29 @@ describe Mongoid::Criteria::Includable do
           end
 
           let!(:results) do
-            D.includes(:b, :c).entries.detect do |d|
-              d.id == d_two.id
-            end
+            query = -> { D.send(method_name, :b, :c).entries.detect { |d| d.id == d_two.id } }
+            (method_name == :eager_load) ? expect_query(1, &query) : query.call
           end
 
-          it "returns the correct documents" do
+          it 'returns the correct documents' do
             expect(results).to eq(d_two)
           end
 
-          it "does not query the db on b" do
+          it 'does not query the db on b' do
             expect_query(0) do
               results.b
             end
           end
 
-          it "does not query the db on c" do
+          it 'does not query the db on c' do
             expect_query(0) do
-              results.b
+              results.c
             end
           end
         end
       end
 
-      context "when the relation is a has_many" do
-
+      context 'when the relation is a has_many' do
         before(:all) do
           class A
             include Mongoid::Document
@@ -258,6 +248,7 @@ describe Mongoid::Criteria::Includable do
 
           class D
             include Mongoid::Document
+
             has_many :b
             has_many :c
           end
@@ -270,8 +261,7 @@ describe Mongoid::Criteria::Includable do
           Object.send(:remove_const, :D)
         end
 
-        context "when the includes is on the several relations" do
-
+        context 'when the includes is on the several relations' do
           let!(:d_one) do
             D.create!
           end
@@ -289,53 +279,50 @@ describe Mongoid::Criteria::Includable do
           end
 
           let!(:results) do
-            D.includes(:b, :c).entries.detect do |d|
-              d.id == d_two.id
-            end
+            query = -> { D.send(method_name, :b, :c).entries.detect { |d| d.id == d_two.id } }
+            (method_name == :eager_load) ? expect_query(1, &query) : query.call
           end
 
-          it "returns the correct documents" do
+          it 'returns the correct documents' do
             expect(results).to eq(d_two)
           end
 
-          it "does not query the db on b" do
+          it 'does not query the db on b' do
             expect_query(0) do
               results.b
             end
           end
 
-          it "does not query the db on c" do
+          it 'does not query the db on c' do
             expect_query(0) do
-              results.b
+              results.c
             end
           end
         end
       end
     end
 
-    context "when including the same association multiple times" do
-
+    context 'when including the same association multiple times' do
       let(:criteria) do
-        Person.all.includes(:posts, :posts).includes(:posts)
+        Person.all.send(method_name, :posts, :posts).send(method_name, :posts)
       end
 
       let(:association) do
         Person.reflect_on_association(:posts)
       end
 
-      it "does not duplicate the association in the inclusions" do
+      it 'does not duplicate the association in the inclusions' do
         expect(criteria.inclusions).to eq([ association ])
       end
     end
 
-    context "when mapping the results more than once" do
-
+    context 'when mapping the results more than once' do
       let!(:post) do
-        person.posts.create!(title: "one")
+        person.posts.create!(title: 'one')
       end
 
       let(:criteria) do
-        Post.includes(:person)
+        Post.send(method_name, :person)
       end
 
       let!(:results) do
@@ -343,90 +330,86 @@ describe Mongoid::Criteria::Includable do
         criteria.map { |doc| doc }
       end
 
-      it "returns the proper results" do
-        expect(results.first.title).to eq("one")
+      it 'returns the proper results' do
+        expect(results.first.title).to eq('one')
       end
     end
 
-    context "when including a belongs to relation" do
-
-      context "when the criteria is from the root" do
-
+    context 'when including a belongs to relation' do
+      context 'when the criteria is from the root' do
         let!(:person_two) do
           Person.create!(age: 2)
         end
 
         let!(:post_one) do
-          person.posts.create!(title: "one")
+          person.posts.create!(title: 'one')
         end
 
         let!(:post_two) do
-          person_two.posts.create!(title: "two")
+          person_two.posts.create!(title: 'two')
         end
 
-        context "when calling first" do
-
+        context 'when calling first' do
           let(:criteria) do
-            Post.includes(:person)
+            Post.send(method_name, :person)
           end
 
           let!(:document) do
-            criteria.first
+            query = -> { criteria.first }
+            (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
           end
 
-          it "eager loads the first document" do
+          it 'eager loads the first document' do
             expect_query(0) do
               expect(document.person).to eq(person)
             end
           end
 
-          it "returns the first document" do
+          it 'returns the first document' do
             expect(document).to eq(post_one)
           end
         end
 
-        context "when calling last" do
-
+        context 'when calling last' do
           let!(:criteria) do
-            Post.asc(:_id).includes(:person)
+            Post.asc(:_id).send(method_name, :person)
           end
 
           let!(:document) do
             criteria.last
           end
 
-          it "eager loads the last document" do
+          it 'eager loads the last document' do
             expect_query(0) do
               expect(document.person).to eq(person_two)
             end
           end
 
-          it "returns the last document" do
+          it 'returns the last document' do
             expect(document).to eq(post_two)
           end
         end
       end
 
-      context "when the criteria is from an embedded relation" do
-
+      context 'when the criteria is from an embedded relation' do
         let(:peep) do
           Person.create!
         end
 
         let!(:address_one) do
-          peep.addresses.create!(street: "rosenthaler")
+          peep.addresses.create!(street: 'rosenthaler')
         end
 
         let!(:address_two) do
-          peep.addresses.create!(street: "weinmeister")
+          peep.addresses.create!(street: 'weinmeister')
         end
 
         let!(:depeche) do
-          Band.create!(name: "Depeche Mode")
+          Band.create!(name: 'Depeche Mode')
         end
 
         let!(:tool) do
-          Band.create!(name: "Tool")
+          Band.create!(name: 'Tool')
         end
 
         before do
@@ -436,10 +419,9 @@ describe Mongoid::Criteria::Includable do
           address_two.save!
         end
 
-        context "when calling first" do
-
+        context 'when calling first' do
           let(:criteria) do
-            peep.reload.addresses.includes(:band)
+            peep.reload.addresses.send(method_name, :band)
           end
 
           let(:context) do
@@ -447,24 +429,25 @@ describe Mongoid::Criteria::Includable do
           end
 
           let!(:document) do
+            # Since this is called on an embedded criteria, we will be using the includes path
+            # rather than the $lookup path, so we do not need to check queries.
             criteria.first
           end
 
-          it "eager loads the first document" do
+          it 'eager loads the first document' do
             expect_query(0) do
               expect(document.band).to eq(depeche)
             end
           end
 
-          it "returns the document" do
+          it 'returns the document' do
             expect(document).to eq(address_one)
           end
         end
 
-        context "when calling last" do
-
+        context 'when calling last' do
           let(:criteria) do
-            peep.reload.addresses.includes(:band)
+            peep.reload.addresses.send(method_name, :band)
           end
 
           let(:context) do
@@ -472,24 +455,24 @@ describe Mongoid::Criteria::Includable do
           end
 
           let!(:document) do
-            criteria.last
+            query = -> { criteria.last }
+            (method_name == :eager_load) ? expect_query(2, &query) : query.call
           end
 
-          it "eager loads the last document" do
+          it 'eager loads the last document' do
             expect_query(0) do
               expect(document.band).to eq(tool)
             end
           end
 
-          it "returns the document" do
+          it 'returns the document' do
             expect(document).to eq(address_two)
           end
         end
 
-        context "when iterating all documents" do
-
+        context 'when iterating all documents' do
           let(:criteria) do
-            peep.reload.addresses.includes(:band)
+            peep.reload.addresses.send(method_name, :band)
           end
 
           let(:context) do
@@ -497,32 +480,32 @@ describe Mongoid::Criteria::Includable do
           end
 
           let!(:documents) do
-            criteria.to_a
+            query = -> { criteria.to_a }
+            (method_name == :eager_load) ? expect_query(2, &query) : query.call
           end
 
-          it "eager loads the first document" do
+          it 'eager loads the first document' do
             expect_query(0) do
               expect(documents.first.band).to eq(depeche)
             end
           end
 
-          it "eager loads the last document" do
+          it 'eager loads the last document' do
             expect_query(0) do
               expect(documents.last.band).to eq(tool)
             end
           end
 
-          it "returns the documents" do
+          it 'returns the documents' do
             expect(documents).to eq([ address_one, address_two ])
           end
         end
       end
     end
 
-    context "when providing inclusions to the default scope" do
-
+    context 'when providing inclusions to the default scope' do
       before do
-        Person.default_scope(->{ Person.includes(:posts) })
+        Person.default_scope(-> { Person.send(method_name, :posts) })
       end
 
       after do
@@ -530,65 +513,61 @@ describe Mongoid::Criteria::Includable do
       end
 
       let!(:post_one) do
-        person.posts.create!(title: "one")
+        person.posts.create!(title: 'one')
       end
 
       let!(:post_two) do
-        person.posts.create!(title: "two")
+        person.posts.create!(title: 'two')
       end
 
-      context "when the criteria has no options" do
-
+      context 'when the criteria has no options' do
         let!(:criteria) do
           Person.asc(:age).all
         end
 
         let!(:documents) do
-          criteria.entries
+          query = -> { criteria.entries }
+          (method_name == :eager_load) ? expect_less_than_queries(2, &query) : query.call
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ person ])
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(documents.first.posts.first).to eq(post_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(documents.first.posts.last).to eq(post_two)
           end
         end
 
-        context "when executing the query twice" do
-
-          let!(:new_criteria) do
-            Person.where(id: person.id)
-          end
-
-          let!(:new_context) do
-            new_criteria.context
-          end
+        context 'when executing the query twice' do
+          let(:new_criteria) { Person.where(id: person.id) }
+          let(:from_db) { new_criteria.first }
+          let(:new_context) { new_criteria.context }
 
           before do
-            expect(new_context).to receive(:eager_load).with([person]).once.and_call_original
-          end
+            if method_name == :eager_load
+              expect(new_context).to receive(:eager_load_with_lookup).once.and_call_original
+            else
+              expect(new_context).to receive(:eager_load).with([ person ]).once.and_call_original
+            end
 
-          let!(:from_db) do
-            new_criteria.first
+            from_db
           end
 
-          it "does not duplicate documents in the relation" do
+          it 'does not duplicate documents in the relation' do
             expect(person.posts.size).to eq(2)
           end
         end
       end
 
-      context "when calling first on the criteria" do
-
+      context 'when calling first on the criteria' do
         let(:criteria) do
           Person.asc(:age).all
         end
@@ -597,66 +576,62 @@ describe Mongoid::Criteria::Includable do
           criteria.first
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(from_db).to eq(person)
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(from_db.posts.first).to eq(post_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(from_db.posts.last).to eq(post_two)
           end
         end
       end
 
-      context "when calling last on the criteria" do
-
-        let(:criteria) do
-          Person.asc(:age).all
-        end
-
-        let!(:context) do
-          criteria.context
-        end
+      context 'when calling last on the criteria' do
+        let(:criteria) { Person.asc(:age).all }
+        let(:from_db) { criteria.last }
+        let(:context) { criteria.context }
 
         before do
-          expect(context).to receive(:eager_load).with([person]).once.and_call_original
-        end
+          if method_name == :eager_load
+            expect(context).to receive(:eager_load_with_lookup).once.and_call_original
+          else
+            expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+          end
 
-        let!(:from_db) do
-          criteria.last
+          from_db
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(from_db).to eq(person)
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(from_db.posts.first).to eq(post_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(from_db.posts.last).to eq(post_two)
           end
         end
       end
 
-      context "when the criteria has limiting options" do
-
+      context 'when the criteria has limiting options' do
         let!(:person_two) do
           Person.create!
         end
 
         let!(:post_three) do
-          person_two.posts.create!(title: "three")
+          person_two.posts.create!(title: 'three')
         end
 
         let!(:criteria) do
@@ -664,20 +639,21 @@ describe Mongoid::Criteria::Includable do
         end
 
         let!(:documents) do
-          criteria.entries
+          query = -> { criteria.entries }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(criteria).to eq([ person ])
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(documents.first.posts.first).to eq(post_one)
           end
         end
 
-        it "eager loads the second document" do
+        it 'eager loads the second document' do
           expect_query(0) do
             expect(documents.first.posts.last).to eq(post_two)
           end
@@ -685,107 +661,106 @@ describe Mongoid::Criteria::Includable do
       end
     end
 
-    context "when including a has and belongs to many" do
-
+    context 'when including a has and belongs to many' do
       let!(:preference_one) do
-        person.preferences.create!(name: "one")
+        person.preferences.create!(name: 'one')
       end
 
       let!(:preference_two) do
-        person.preferences.create!(name: "two")
+        person.preferences.create!(name: 'two')
       end
 
-      context "when one of the related items is deleted" do
-
+      context 'when one of the related items is deleted' do
         before do
           person.preferences = [ preference_one, preference_two ]
           preference_two.delete
         end
 
         let(:criteria) do
-          Person.where(id: person.id).includes(:preferences)
+          Person.where(id: person.id).send(method_name, :preferences)
         end
 
-        it "only loads the existing related items" do
+        it 'only loads the existing related items' do
           expect(criteria.entries.first.preferences).to eq([ preference_one ])
         end
       end
 
-      context "when the criteria has no options" do
-
+      context 'when the criteria has no options' do
         let!(:criteria) do
-          Person.asc(:age).includes(:preferences)
+          Person.asc(:age).send(method_name, :preferences)
         end
 
         let!(:documents) do
-          criteria.entries
+          query = -> { criteria.entries }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ person ])
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(documents.first.preferences.first).to eq(preference_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(documents.first.preferences.last).to eq(preference_two)
           end
         end
       end
 
-      context "when calling first on the criteria" do
-
+      context 'when calling first on the criteria' do
         let!(:criteria) do
-          Person.asc(:age).includes(:preferences)
+          Person.asc(:age).send(method_name, :preferences)
         end
 
+        # here
         let!(:from_db) do
-          criteria.first
+          query = -> { criteria.first }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(from_db).to eq(person)
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(from_db.preferences.first).to eq(preference_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(from_db.preferences.last).to eq(preference_two)
           end
         end
       end
 
-      context "when calling last on the criteria" do
-
+      context 'when calling last on the criteria' do
         let!(:criteria) do
-          Person.asc(:age).includes(:preferences)
+          Person.asc(:age).send(method_name, :preferences)
         end
 
         let!(:from_db) do
-          criteria.last
+          query = -> { criteria.last }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(from_db).to eq(person)
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(from_db.preferences.first).to eq(preference_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(from_db.preferences.last).to eq(preference_two)
           end
@@ -793,107 +768,105 @@ describe Mongoid::Criteria::Includable do
       end
     end
 
-    context "when including a has many" do
-
+    context 'when including a has many' do
       let!(:post_one) do
-        person.posts.create!(title: "one")
+        person.posts.create!(title: 'one')
       end
 
       let!(:post_two) do
-        person.posts.create!(title: "two")
+        person.posts.create!(title: 'two')
       end
 
-      context "when the criteria has no options" do
-
+      context 'when the criteria has no options' do
         let!(:criteria) do
-          Person.asc(:age).includes(:posts)
+          Person.asc(:age).send(method_name, :posts)
         end
 
         let!(:documents) do
-          criteria.entries
+          query = -> { criteria.entries }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ person ])
         end
 
-        it "eager loads the first document" do
+        it 'eager loads the first document' do
           expect_query(0) do
             expect(documents.first.posts.first).to eq(post_one)
           end
         end
 
-        it "eager loads the last document" do
+        it 'eager loads the last document' do
           expect_query(0) do
             expect(documents.first.posts.last).to eq(post_two)
           end
         end
       end
 
-      context "when calling first on the criteria" do
-
+      context 'when calling first on the criteria' do
         let!(:criteria) do
-          Person.asc(:age).includes(:posts)
+          Person.asc(:age).send(method_name, :posts)
         end
 
         let!(:from_db) do
           criteria.first
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(from_db).to eq(person)
         end
 
-        context "when subsequently getting all documents" do
-
+        context 'when subsequently getting all documents' do
           let!(:documents) do
             criteria.entries
           end
 
-          it "returns the correct documents" do
+          it 'returns the correct documents' do
             expect(documents).to eq([ person ])
           end
         end
       end
 
-      context "when calling last on the criteria" do
-
+      context 'when calling last on the criteria' do
         let!(:criteria) do
-          Person.asc(:age).includes(:posts)
+          Person.asc(:age).send(method_name, :posts)
         end
 
         let!(:from_db) do
           criteria.last
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(from_db).to eq(person)
         end
 
-        context "when subsequently getting all documents" do
-
+        context 'when subsequently getting all documents' do
           let!(:documents) do
             criteria.entries
           end
 
-          it "returns the correct documents" do
+          it 'returns the correct documents' do
             expect(documents).to eq([ person ])
           end
         end
       end
 
-      context "when the criteria has limiting options" do
-
-        let!(:person_two) do
+      context 'when the criteria has limiting options' do
+        let(:person_two) do
           Person.create!
         end
 
-        let!(:post_three) do
-          person_two.posts.create!(title: "three")
+        let(:documents) do
+          criteria.entries
         end
 
-        let!(:criteria) do
-          Person.includes(:posts).asc(:age).limit(1)
+        let(:post_three) do
+          person_two.posts.create!(title: 'three')
+        end
+
+        let(:criteria) do
+          Person.send(method_name, :posts).asc(:age).limit(1)
         end
 
         let(:context) do
@@ -901,33 +874,37 @@ describe Mongoid::Criteria::Includable do
         end
 
         before do
-          expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
-        end
+          post_three
 
-        let!(:documents) do
-          criteria.entries
+          if method_name == :includes
+            expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+          else
+            expect(context).to receive(:eager_load_with_lookup).once.and_call_original
+          end
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ person ])
         end
       end
     end
 
-    context "when including a has one" do
-
+    context 'when including a has one' do
       let!(:game_one) do
-        person.create_game(name: "one")
+        person.create_game(name: 'one')
       end
 
       let!(:game_two) do
-        person.create_game(name: "two")
+        person.create_game(name: 'two')
       end
 
-      context "when the criteria has no options" do
+      context 'when the criteria has no options' do
+        let(:criteria) do
+          Person.asc(:age).send(method_name, :game)
+        end
 
-        let!(:criteria) do
-          Person.asc(:age).includes(:game)
+        let(:documents) do
+          criteria.entries
         end
 
         let(:context) do
@@ -935,30 +912,33 @@ describe Mongoid::Criteria::Includable do
         end
 
         before do
-          expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
-        end
-
-        let!(:documents) do
-          criteria.entries
+          if method_name == :includes
+            expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+          else
+            expect(context).to receive(:eager_load_with_lookup).once.and_call_original
+          end
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ person ])
         end
       end
 
-      context "when the criteria has limiting options" do
-
-        let!(:person_two) do
+      context 'when the criteria has limiting options' do
+        let(:person_two) do
           Person.create!(age: 2)
         end
 
-        let!(:game_three) do
-          person_two.create_game(name: "Skyrim")
+        let(:documents) do
+          criteria.entries
         end
 
-        let!(:criteria) do
-          Person.where(id: person.id).includes(:game).asc(:age).limit(1)
+        let(:game_three) do
+          person_two.create_game(name: 'Skyrim')
+        end
+
+        let(:criteria) do
+          Person.where(id: person.id).send(method_name, :game).asc(:age).limit(1)
         end
 
         let(:context) do
@@ -966,37 +946,42 @@ describe Mongoid::Criteria::Includable do
         end
 
         before do
-          expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
-        end
+          person_two
+          game_three
 
-        let!(:documents) do
-          criteria.entries
+          if method_name == :includes
+            expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+          else
+            expect(context).to receive(:eager_load_with_lookup).once.and_call_original
+          end
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ person ])
         end
       end
     end
 
-    context "when including a belongs to" do
-
+    context 'when including a belongs to' do
       let(:person_two) do
         Person.create!(age: 2)
       end
 
       let!(:game_one) do
-        person.create_game(name: "one")
+        person.create_game(name: 'one')
       end
 
       let!(:game_two) do
-        person_two.create_game(name: "two")
+        person_two.create_game(name: 'two')
       end
 
-      context "when providing no options" do
+      context 'when providing no options' do
+        let(:criteria) do
+          Game.send(method_name, :person)
+        end
 
-        let!(:criteria) do
-          Game.includes(:person)
+        let(:documents) do
+          criteria.entries
         end
 
         let(:context) do
@@ -1004,22 +989,27 @@ describe Mongoid::Criteria::Includable do
         end
 
         before do
-          expect(context).to receive(:preload).twice.and_call_original
-        end
+          if method_name == :includes
+            expect(context).to receive(:preload).twice.and_call_original
+          else
+            expect(context).to receive(:preload_for_lookup).twice.and_call_original
+          end
 
-        let!(:documents) do
-          criteria.entries
+          documents
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(criteria).to eq([ game_one, game_two ])
         end
       end
 
-      context "when the criteria has limiting options" do
+      context 'when the criteria has limiting options' do
+        let(:criteria) do
+          Game.where(id: game_one.id).send(method_name, :person).asc(:_id).limit(1)
+        end
 
-        let!(:criteria) do
-          Game.where(id: game_one.id).includes(:person).asc(:_id).limit(1)
+        let(:documents) do
+          criteria.entries
         end
 
         let(:context) do
@@ -1027,81 +1017,105 @@ describe Mongoid::Criteria::Includable do
         end
 
         before do
-          expect(context).to receive(:eager_load).with([ game_one ]).once.and_call_original
-        end
+          if method_name == :includes
+            expect(context).to receive(:eager_load).with([ game_one ]).once.and_call_original
+          else
+            expect(context).to receive(:eager_load_with_lookup).once.and_call_original
+          end
 
-        let!(:documents) do
-          criteria.entries
+          documents
         end
 
-        it "returns the correct documents" do
+        it 'returns the correct documents' do
           expect(documents).to eq([ game_one ])
         end
       end
     end
 
-    context "when including multiples in the same criteria" do
+    context 'when including multiples in the same criteria' do
+      let(:documents) { criteria.entries }
+      let(:post_one) { person.posts.create!(title: 'one') }
+      let(:post_two) { person.posts.create!(title: 'two') }
+      let(:game_one) { person.create_game(name: 'one') }
+      let(:game_two) { person.create_game(name: 'two') }
+      let(:criteria) { Person.send(method_name, :posts, :game).asc(:age) }
+      let(:context) { criteria.context }
 
-      let!(:post_one) do
-        person.posts.create!(title: "one")
-      end
+      before do
+        post_one
+        post_two
+        game_one
+        game_two
 
-      let!(:post_two) do
-        person.posts.create!(title: "two")
-      end
+        if method_name == :includes
+          expect(context).to receive(:preload).twice.and_call_original
+        else
+          expect(context).to receive(:preload_for_lookup).twice.and_call_original
+        end
 
-      let!(:game_one) do
-        person.create_game(name: "one")
+        documents
       end
 
-      let!(:game_two) do
-        person.create_game(name: "two")
+      it 'returns the correct documents' do
+        expect(criteria).to eq([ person ])
       end
+    end
 
-      let!(:criteria) do
-        Person.includes(:posts, :game).asc(:age)
+    context 'when classes inherit from each other' do
+      let!(:admin) do
+        IncAdmin.create!(admin_level: 2)
       end
 
-      let(:context) do
-        criteria.context
+      let!(:post) do
+        admin.posts.create!
       end
 
-      before do
-        expect(context).to receive(:preload).twice.and_call_original
+      let(:criteria) do
+        IncUser.send(method_name, :posts)
       end
 
       let!(:documents) do
-        criteria.entries
+        query = -> { criteria.entries }
+        (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
       end
 
-      it "returns the correct documents" do
-        expect(criteria).to eq([ person ])
+      it 'returns the correct documents' do
+        expect(documents).to eq([ admin ])
       end
-    end
 
-    context "when including nested referenced associations" do
+      it 'eager loads the posts' do
+        expect_query(0) do
+          expect(documents.first.posts).to eq([ post ])
+        end
+      end
+    end
 
-      context "when using a has_one association" do
+    context 'when including nested referenced associations' do
+      context 'when using a has_one association' do
         before(:all) do
           class A
             include Mongoid::Document
+
             has_one :b
           end
 
           class B
             include Mongoid::Document
+
             belongs_to :a
             has_one :c
           end
 
           class C
             include Mongoid::Document
+
             belongs_to :b
             has_one :d
           end
 
           class D
             include Mongoid::Document
+
             belongs_to :c
           end
         end
@@ -1135,97 +1149,101 @@ describe Mongoid::Criteria::Includable do
           a.b = b
         end
 
-        context "when including the belongs_to assocation" do
+        context 'when including the belongs_to association' do
           let!(:result) do
-            C.includes(b: :a).first
+            C.send(method_name, b: :a).first
           end
 
-          it "finds the right document" do
+          it 'finds the right document' do
             expect(result).to eq(c)
             expect(result.b).to eq(c.b)
             expect(result.b.a).to eq(c.b.a)
           end
 
-          it "does not execute a query" do
-            expect_no_queries do
+          it 'does not execute a query' do
+            expect_query(0) do
               result.b.a
             end
           end
         end
 
-        context "when including a doubly-nested belongs_to assocation" do
+        context 'when including a doubly-nested belongs_to association' do
           let!(:result) do
-            D.includes(c: { b: :a }).first
+            query = -> { D.send(method_name, c: { b: :a }).first }
+            (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
           end
 
-          it "finds the right document" do
+          it 'finds the right document' do
             expect(result).to eq(d)
             expect(result.c).to eq(d.c)
             expect(result.c.b).to eq(d.c.b)
             expect(result.c.b.a).to eq(d.c.b.a)
           end
 
-          it "does not execute a query" do
-            expect_no_queries do
+          it 'does not execute a query' do
+            expect_query(0) do
               result.c.b.a
             end
           end
         end
 
-        context "when including the has_many assocation" do
+        context 'when including the has_many association' do
           let!(:result) do
-            A.includes(b: :c).first
+            query = -> { A.send(method_name, b: :c).first }
+            (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
           end
 
-          it "finds the right document" do
+          it 'finds the right document' do
             expect(result).to eq(a)
             expect(result.b).to eq(a.b)
             expect(result.b.c).to eq(a.b.c)
           end
 
-          it "does not executes a query" do
-            expect_no_queries do
+          it 'does not executes a query' do
+            expect_query(0) do
               result.b.c
             end
           end
         end
 
-        context "when including a doubly-nested has_many assocation" do
+        context 'when including a doubly-nested has_many association' do
           let!(:result) do
-            A.includes(b: { c: :d }).first
+            query = -> { A.send(method_name, b: { c: :d }).first }
+            (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
           end
 
-          it "finds the right document" do
+          it 'finds the right document' do
             expect(result).to eq(a)
             expect(result.b).to eq(a.b)
             expect(result.b.c).to eq(a.b.c)
             expect(result.b.c.d).to eq(a.b.c.d)
           end
 
-          it "does not execute a query" do
-            expect_no_queries do
+          it 'does not execute a query' do
+            expect_query(0) do
               result.b.c.d
             end
           end
         end
 
-        context "when there are multiple documents" do
+        context 'when there are multiple documents' do
           let!(:as) do
-            res = 9.times.map do |i|
+            res = 9.times.map do |_i|
               A.create!.tap do |a|
                 a.b = B.create!.tap do |b|
                   b.c = C.create!
                 end
               end
             end
-            [a, *res]
+            [ a, *res ]
           end
 
           let!(:results) do
-            A.includes(b: :c).entries.sort
+            query = -> { A.send(method_name, b: :c).entries.sort }
+            (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
           end
 
-          it "finds the right document" do
+          it 'finds the right document' do
             as.length.times do |i|
               expect(as[i]).to eq(results[i])
               expect(as[i].b).to eq(results[i].b)
@@ -1233,8 +1251,8 @@ describe Mongoid::Criteria::Includable do
             end
           end
 
-          it "does not execute a query" do
-            expect_no_queries do
+          it 'does not execute a query' do
+            expect_query(0) do
               results.each do |a|
                 a.b.c
               end
@@ -1242,7 +1260,7 @@ describe Mongoid::Criteria::Includable do
           end
         end
 
-        context "when there are multiple associations" do
+        context 'when there are multiple associations' do
           before(:all) do
             class A
               has_one :c
@@ -1256,16 +1274,18 @@ describe Mongoid::Criteria::Includable do
           let(:c2) { C.create! }
           let(:d2) { D.create! }
 
+          let(:results) do
+            query = -> { A.send(method_name, b: { c: :d }, c: :d).first }
+            (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
+          end
+
           before do
             a.c = c2
             a.c.d = d2
+            results
           end
 
-          let!(:results) do
-            A.includes(b: { c: :d }, c: :d).first
-          end
-
-          it "finds the right document" do
+          it 'finds the right document' do
             expect(results).to eq(a)
             expect(results.b).to eq(a.b)
             expect(results.b.c).to eq(a.b.c)
@@ -1274,8 +1294,8 @@ describe Mongoid::Criteria::Includable do
             expect(results.c.d).to eq(a.c.d)
           end
 
-          it "does not execute a query" do
-            expect_no_queries do
+          it 'does not execute a query' do
+            expect_query(0) do
               results.c.d
               results.b.c.d
             end
@@ -1284,8 +1304,28 @@ describe Mongoid::Criteria::Includable do
       end
     end
 
-    context "when using a has_many association" do
+    context 'when using a has_many association with an empty association' do
+      let!(:user) do
+        IncUser.create!
+      end
+
+      let!(:result) do
+        IncUser.send(method_name, :posts, :comments).where(id: user.id).first
+      end
+
+      it 'executes the query' do
+        expect(result).to eq(user)
+      end
+
+      it 'does not issue extra queries' do
+        expect_query(0) do
+          result.posts.to_a
+          result.comments.to_a
+        end
+      end
+    end
 
+    context 'when using a has_many association' do
       let!(:user) do
         IncUser.create!(posts: posts, comments: user_comments)
       end
@@ -1295,19 +1335,20 @@ describe Mongoid::Criteria::Includable do
       end
 
       let!(:user_comments) do
-        2.times.map{ IncComment.create! }
+        2.times.map { IncComment.create! }
       end
 
       let!(:post_comments) do
-        2.times.map{ IncComment.create! }
+        2.times.map { IncComment.create! }
       end
 
-      context "when including the same class twice" do
+      context 'when including the same class twice' do
         let!(:results) do
-          IncPost.includes({ user: :comments }, :comments).entries.sort
+          query = -> { IncPost.send(method_name, { user: :comments }, :comments).entries.sort }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "finds the right documents" do
+        it 'finds the right documents' do
           posts.length.times do |i|
             expect(posts[i]).to eq(results[i])
             expect(posts[i].user).to eq(results[i].user)
@@ -1316,8 +1357,8 @@ describe Mongoid::Criteria::Includable do
           end
         end
 
-        it "does not execute a query" do
-          expect_no_queries do
+        it 'does not execute a query' do
+          expect_query(0) do
             results.each do |res|
               res.user
               res.user.comments.to_a
@@ -1327,14 +1368,15 @@ describe Mongoid::Criteria::Includable do
         end
       end
 
-      context "when the association chain has a class name twice" do
+      context 'when the association chain has a class name twice' do
         let!(:thread) { IncThread.create!(comments: user_comments) }
 
         let!(:result) do
-          IncThread.includes(comments: { user: { posts: :comments } }).first
+          query = -> { IncThread.send(method_name, comments: { user: { posts: :comments } }).first }
+          (method_name == :eager_load) ? expect_less_than_queries(3, &query) : query.call
         end
 
-        it "finds the right document" do
+        it 'finds the right document' do
           expect(result).to eq(thread)
           result.comments.length.times do |i|
             c1 = result.comments[i]
@@ -1351,8 +1393,8 @@ describe Mongoid::Criteria::Includable do
           end
         end
 
-        it "does not execute a query" do
-          expect_no_queries do
+        it 'does not execute a query' do
+          expect_query(0) do
             result.comments.each do |comment|
               comment.user.posts.each do |post|
                 post.comments.to_a
@@ -1364,112 +1406,994 @@ describe Mongoid::Criteria::Includable do
     end
   end
 
-  describe "#inclusions" do
-
-    let(:criteria) do
-      Band.includes(:records)
-    end
-
-    let(:association) do
-      Band.relations["records"]
-    end
-
-    it "returns the inclusions" do
-      expect(criteria.inclusions).to eq([ association ])
-    end
+  describe '#includes' do
+    it_behaves_like 'eager loading', :includes
   end
 
-  describe "#inclusions=" do
+  describe '#eager_load' do
+    # 4.4 lookup does not support the lookup pipeline as it is currently written
+    min_server_version '5.0'
+    it_behaves_like 'eager loading', :eager_load
 
-    let(:criteria) do
-      Band.all
-    end
+    context 'when the inclusion list is empty' do
+      let!(:band) { Band.create! }
 
-    let(:association) do
-      Band.relations["records"]
+      it 'returns the documents without eager loading' do
+        expect(Band.eager_load([]).first).to eq(band)
+      end
     end
 
-    before do
-      criteria.inclusions = [ association ]
-    end
+    context 'when the association is defined on a subclass of the queried class' do
+      before(:all) do
+        class Machine
+          include Mongoid::Document
+        end
 
-    it "sets the inclusions" do
-      expect(criteria.inclusions).to eq([ association ])
-    end
-  end
+        class Peripheral
+          include Mongoid::Document
+        end
 
-  context "When multiple associations reference the same class" do
-    before do
-      IncBlog.create(
-        posts: [
-          IncBlogPost.create(author: IncAuthor.create),
-          IncBlogPost.create(author: IncAuthor.create),
-          IncBlogPost.create(author: IncAuthor.create),
-        ],
-        highlighted_post: IncBlogPost.create(author: IncAuthor.create)
-      )
-    end
+        class Webcam < Peripheral
+        end
 
-    let!(:result) do
-      IncBlog.includes(:posts, highlighted_post: :author).first
-    end
+        class Mouse < Peripheral
+          belongs_to :machine
+        end
+      end
 
-    it "does not execute a query" do
-      expect_no_queries do
-        result.posts.to_a
-        result.highlighted_post
+      after(:all) do
+        Object.send(:remove_const, :Mouse)
+        Object.send(:remove_const, :Webcam)
+        Object.send(:remove_const, :Peripheral)
+        Object.send(:remove_const, :Machine)
       end
-    end
 
-    it "executes a query for the non-retrieved elements" do
-      expect_query(3) do
-        result.posts.each do |post|
-          post.author
+      let!(:machine) { Machine.create! }
+      let!(:webcam) { Webcam.create! }
+      let!(:mouse) { Mouse.create!(machine: machine) }
+
+      it 'eager-loads it through the queried superclass' do
+        expect_query(1) do
+          loaded = Peripheral.eager_load(:machine).detect { |doc| doc.is_a?(Mouse) }
+          expect(loaded.machine).to eq(machine)
         end
       end
     end
-  end
 
-  context "When multiple parent_inclusions for the same association" do
-    before do
-      IncBlog.create(
-        posts: [
-          IncBlogPost.create(author: IncAuthor.create),
-          IncBlogPost.create(author: IncAuthor.create),
-          IncBlogPost.create(author: IncAuthor.create),
-        ],
-        highlighted_post: IncBlogPost.create(author: IncAuthor.create),
-        pinned_post: IncBlogPost.create(author: IncAuthor.create)
-      )
-    end
+    context 'when the association is defined on a subclass of an associated class' do
+      before(:all) do
+        class Brand
+          include Mongoid::Document
+        end
 
-    let!(:result) do
-      IncBlog.includes(:posts, highlighted_post: :author, pinned_post: :author).first
-    end
+        class Machine
+          include Mongoid::Document
+        end
 
-    it "does not execute a query" do
-      expect_no_queries do
-        result.posts.to_a
-        result.highlighted_post
-        result.pinned_post
-      end
-    end
+        class Laptop < Machine
+          belongs_to :brand
+        end
 
-    it "executes a query for the non-retrieved elements" do
-      expect_query(3) do
-        result.posts.each do |post|
-          post.author
+        class Peripheral
+          include Mongoid::Document
         end
-      end
-    end
 
-    context "when including an association and using each twice on a criteria" do
+        class Mouse < Peripheral
+          belongs_to :machine
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Mouse)
+        Object.send(:remove_const, :Peripheral)
+        Object.send(:remove_const, :Laptop)
+        Object.send(:remove_const, :Machine)
+        Object.send(:remove_const, :Brand)
+      end
+
+      let!(:brand) { Brand.create! }
+      let!(:laptop) { Laptop.create!(brand: brand) }
+      let!(:mouse) { Mouse.create!(machine: laptop) }
+
+      it 'eager-loads it through the parent association' do
+        expect_query(1) do
+          loaded = Peripheral.eager_load(machine: :brand).first
+          expect(loaded.machine).to eq(laptop)
+          expect(loaded.machine.brand).to eq(brand)
+        end
+      end
+    end
+
+    context 'when a has_many is defined only on a subclass' do
+      before(:all) do
+        class Gadget
+          include Mongoid::Document
+        end
+
+        class Speaker < Gadget
+          has_many :cables
+        end
+
+        class Cable
+          include Mongoid::Document
+
+          belongs_to :speaker
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Cable)
+        Object.send(:remove_const, :Speaker)
+        Object.send(:remove_const, :Gadget)
+      end
+
+      let!(:speaker) { Speaker.create! }
+      let!(:cable) { Cable.create!(speaker: speaker) }
+
+      it 'eager-loads it through the queried superclass' do
+        expect_query(1) do
+          loaded = Gadget.eager_load(:cables).first
+          expect(loaded.cables).to eq([ cable ])
+        end
+      end
+    end
+
+    context 'when a has_one is defined only on a subclass' do
+      before(:all) do
+        class Gadget
+          include Mongoid::Document
+        end
+
+        class Speaker < Gadget
+          has_one :cable
+        end
+
+        class Cable
+          include Mongoid::Document
+
+          belongs_to :speaker
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Cable)
+        Object.send(:remove_const, :Speaker)
+        Object.send(:remove_const, :Gadget)
+      end
+
+      let!(:speaker) { Speaker.create! }
+      let!(:cable) { Cable.create!(speaker: speaker) }
+
+      it 'eager-loads it through the queried superclass' do
+        expect_query(1) do
+          loaded = Gadget.eager_load(:cable).first
+          expect(loaded.cable).to eq(cable)
+        end
+      end
+    end
+
+    context 'when a has_and_belongs_to_many is defined only on a subclass' do
+      before(:all) do
+        class Cable
+          include Mongoid::Document
+
+          has_and_belongs_to_many :speakers
+        end
+
+        class Gadget
+          include Mongoid::Document
+        end
+
+        class Speaker < Gadget
+          has_and_belongs_to_many :cables
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Speaker)
+        Object.send(:remove_const, :Gadget)
+        Object.send(:remove_const, :Cable)
+      end
+
+      let!(:cable) { Cable.create! }
+      let!(:speaker) { Speaker.create!(cables: [ cable ]) }
+
+      it 'eager-loads it through the queried superclass' do
+        expect_query(1) do
+          loaded = Gadget.eager_load(:cables).first
+          expect(loaded.cables).to eq([ cable ])
+        end
+      end
+    end
+
+    context 'when a belongs_to lives inside an embedded document' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          belongs_to :device
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :port
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device) { Device.create! }
+      let!(:computer) { Computer.create!(port: Port.new(device: device)) }
+
+      it 'eager-loads it through the embedded document' do
+        expect_query(1) do
+          loaded = Computer.eager_load(port: :device).first
+          expect(loaded.port.device).to eq(device)
+        end
+      end
+
+      it 'leaves the embedded document absent instead of synthesizing it' do
+        without_port = Computer.create!
+        loaded = expect_query(1) do
+          Computer.eager_load(port: :device).to_a.index_by(&:id)
+        end
+        expect_no_queries do
+          expect(loaded[without_port.id].port).to be_nil
+        end
+      end
+    end
+
+    context 'when two embeds_one associations of the same class are eager-loaded' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          belongs_to :device
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :left_port, class_name: 'Port'
+          embeds_one :right_port, class_name: 'Port'
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device1) { Device.create! }
+      let!(:device2) { Device.create! }
+      let!(:computer) do
+        Computer.create!(
+          left_port: Port.new(device: device1),
+          right_port: Port.new(device: device2)
+        )
+      end
+
+      it 'eager-loads the belongs_to in both embedded documents' do
+        expect_query(1) do
+          loaded = Computer.eager_load(left_port: :device, right_port: :device).first
+          expect(loaded.left_port.device).to eq(device1)
+          expect(loaded.right_port.device).to eq(device2)
+        end
+      end
+    end
+
+    context 'when a belongs_to lives inside a doubly embedded document' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :panel
+          belongs_to :device
+        end
+
+        class Panel
+          include Mongoid::Document
+
+          embedded_in :computer
+          embeds_one :port
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :panel
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Panel)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device) { Device.create! }
+      let!(:computer) { Computer.create!(panel: Panel.new(port: Port.new(device: device))) }
+
+      it 'eager-loads it through both embedded documents' do
+        expect_query(1) do
+          loaded = Computer.eager_load(panel: { port: :device }).first
+          expect(loaded.panel.port.device).to eq(device)
+        end
+      end
+    end
+
+    context 'when a belongs_to is defined only on a subclass of an embedded document' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+        end
+
+        class UsbPort < Port
+          belongs_to :device
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :port
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :UsbPort)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device) { Device.create! }
+      let!(:computer) { Computer.create!(port: UsbPort.new(device: device)) }
+
+      it 'eager-loads it through the embedded subclass' do
+        expect_query(1) do
+          loaded = Computer.eager_load(port: :device).first
+          expect(loaded.port.device).to eq(device)
+        end
+      end
+    end
+
+    context 'when a belongs_to lives inside an embeds_many' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          belongs_to :device
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_many :ports
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device1) { Device.create! }
+      let!(:device2) { Device.create! }
+      let!(:computer) { Computer.create!(ports: [ Port.new(device: device1), Port.new(device: device2) ]) }
+
+      it 'eager-loads each embedded belongs_to without extra queries' do
+        expect_query(1) do
+          loaded = Computer.eager_load(ports: :device).first
+          expect(loaded.ports.map(&:device)).to eq([ device1, device2 ])
+        end
+      end
+    end
+
+    context 'when a has_and_belongs_to_many lives inside an embedded document' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          has_and_belongs_to_many :devices
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :port
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device1) { Device.create! }
+      let!(:device2) { Device.create! }
+      let!(:computer) { Computer.create!(port: Port.new(devices: [ device1, device2 ])) }
+
+      it 'eager-loads the devices referenced by the embedded port' do
+        expect_query(1) do
+          loaded = Computer.eager_load(port: :devices).first
+          expect(loaded.port.devices).to eq([ device1, device2 ])
+        end
+      end
+    end
+
+    context 'when an embedded belongs_to targets a superclass of the queried subclass' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Computer < Device
+          embeds_one :port
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          belongs_to :device
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device) { Device.create! }
+      let!(:computer) { Computer.create!(port: Port.new(device: device)) }
+
+      it 'eager-loads the embedded belongs_to through the queried subclass' do
+        expect_query(1) do
+          loaded = Computer.eager_load(port: :device).first
+          expect(loaded.port.device).to eq(device)
+        end
+      end
+    end
+
+    context 'when an embedded association is nested under a referenced one' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          belongs_to :device
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :port
+        end
+
+        class Desk
+          include Mongoid::Document
+
+          belongs_to :computer
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Desk)
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device) { Device.create! }
+      let!(:computer) { Computer.create!(port: Port.new(device: device)) }
+      let!(:desk) { Desk.create!(computer: computer) }
+
+      it 'eager-loads the embedded association together with its referenced child' do
+        expect_query(1) do
+          loaded = Desk.eager_load(computer: { port: :device }).first
+          expect(loaded.computer.port.device).to eq(device)
+        end
+      end
+    end
+
+    context 'when an embedded association is nested two levels under a referenced one' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Pin
+          include Mongoid::Document
+
+          embedded_in :port
+          belongs_to :device
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :computer
+          embeds_one :pin
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_one :port
+        end
+
+        class Desk
+          include Mongoid::Document
+
+          belongs_to :computer
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Desk)
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Pin)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:device) { Device.create! }
+      let!(:computer) { Computer.create!(port: Port.new(pin: Pin.new(device: device))) }
+      let!(:desk) { Desk.create!(computer: computer) }
+
+      it 'eager-loads the doubly embedded association together with its referenced child' do
+        expect_query(1) do
+          loaded = Desk.eager_load(computer: { port: { pin: :device } }).first
+          expect(loaded.computer.port.pin.device).to eq(device)
+        end
+      end
+    end
+
+    context 'when an embeds_many is nested inside another embeds_many under a referenced one' do
+      before(:all) do
+        class Device
+          include Mongoid::Document
+        end
+
+        class Port
+          include Mongoid::Document
+
+          embedded_in :card
+          belongs_to :device
+        end
+
+        class Card
+          include Mongoid::Document
+
+          embedded_in :computer
+          embeds_many :ports
+        end
+
+        class Computer
+          include Mongoid::Document
+
+          embeds_many :cards
+        end
+
+        class Desk
+          include Mongoid::Document
+
+          belongs_to :computer
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Desk)
+        Object.send(:remove_const, :Computer)
+        Object.send(:remove_const, :Card)
+        Object.send(:remove_const, :Port)
+        Object.send(:remove_const, :Device)
+      end
+
+      let!(:devices) { Array.new(4) { Device.create! } }
+      let!(:computer) do
+        Computer.create!(
+          cards: [
+            Card.new(ports: [ Port.new(device: devices[0]), Port.new(device: devices[1]) ]),
+            Card.new(ports: [ Port.new(device: devices[2]), Port.new(device: devices[3]) ])
+          ]
+        )
+      end
+      let!(:desk) { Desk.create!(computer: computer) }
+
+      it 'eager-loads each deeply embedded belongs_to correlated to its own element' do
+        expect_query(1) do
+          loaded = Desk.eager_load(computer: { cards: { ports: :device } }).first
+          got = loaded.computer.cards.flat_map { |card| card.ports.map(&:device) }
+          expect(got).to eq(devices)
+        end
+      end
+    end
+
+    context 'when a polymorphic belongs_to is eager-loaded' do
+      before(:all) do
+        class Printer
+          include Mongoid::Document
+        end
+
+        class Scanner
+          include Mongoid::Document
+        end
+
+        class Cartridge
+          include Mongoid::Document
+
+          belongs_to :device, polymorphic: true
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Cartridge)
+        Object.send(:remove_const, :Scanner)
+        Object.send(:remove_const, :Printer)
+      end
+
+      let!(:printer) { Printer.create! }
+      let!(:scanner) { Scanner.create! }
+      let!(:printer_cartridge) { Cartridge.create!(device: printer) }
+      let!(:scanner_cartridge) { Cartridge.create!(device: scanner) }
+
+      it 'eager-loads polymorphic targets of different types in a single extra query' do
+        expect_query(2) do
+          loaded = Cartridge.eager_load(:device).to_a.index_by(&:id)
+          expect(loaded[printer_cartridge.id].device).to eq(printer)
+          expect(loaded[scanner_cartridge.id].device).to eq(scanner)
+        end
+      end
+    end
+
+    context 'when a polymorphic target is stored in another database' do
+      before(:all) do
+        class LocalDevice
+          include Mongoid::Document
+        end
+
+        class RemoteDevice
+          include Mongoid::Document
+
+          store_in database: 'secondary'
+        end
+
+        class Accessory
+          include Mongoid::Document
+
+          belongs_to :device, polymorphic: true
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Accessory)
+        Object.send(:remove_const, :RemoteDevice)
+        Object.send(:remove_const, :LocalDevice)
+      end
+
+      # RemoteDevice lives in its own database, which the global cleanup hook
+      # (default database only) does not touch, so drop it here.
+      after { RemoteDevice.collection.drop }
+
+      let!(:local_device) { LocalDevice.create! }
+      let!(:remote_device) { RemoteDevice.create! }
+      let!(:local_accessory) { Accessory.create!(device: local_device) }
+      let!(:remote_accessory) { Accessory.create!(device: remote_device) }
+
+      it 'eager-loads the target stored in the other database' do
+        # One query materializes the roots, one $facet fetches the same-database
+        # target, and one direct query fetches the target in the other database.
+        loaded = expect_query(3) do
+          Accessory.eager_load(:device).to_a.index_by(&:id)
+        end
+
+        expect_no_queries do
+          expect(loaded[local_accessory.id].device).to eq(local_device)
+          expect(loaded[remote_accessory.id].device).to eq(remote_device)
+        end
+      end
+    end
+
+    context 'when a non-polymorphic target is stored in another database' do
+      before(:all) do
+        class RemoteServer
+          include Mongoid::Document
+
+          store_in database: 'secondary'
+        end
+
+        class Workstation
+          include Mongoid::Document
+
+          belongs_to :server, class_name: 'RemoteServer', optional: true
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Workstation)
+        Object.send(:remove_const, :RemoteServer)
+      end
+
+      # RemoteServer lives in its own database, which the global cleanup hook
+      # (default database only) does not touch, so drop it here.
+      after { RemoteServer.collection.drop }
+
+      let!(:server) { RemoteServer.create! }
+      let!(:workstation) { Workstation.create!(server: server) }
+
+      it 'eager-loads the target stored in the other database' do
+        # A $lookup cannot reach another database, so this falls back to
+        # separate-query loading: one query materializes the roots and one fetches
+        # the targets, instead of silently returning nothing.
+        loaded = expect_query(2) do
+          Workstation.eager_load(:server).to_a
+        end
+
+        expect_no_queries do
+          expect(loaded.first.server).to eq(server)
+        end
+      end
+    end
+
+    context 'when a has_many of the same name is defined on more than one subclass' do
+      before(:all) do
+        class Supplier
+          include Mongoid::Document
+        end
+
+        class Cog
+          include Mongoid::Document
+
+          belongs_to :machine, optional: true
+          belongs_to :supplier, optional: true
+        end
+
+        class Belt
+          include Mongoid::Document
+
+          belongs_to :machine, optional: true
+          belongs_to :supplier, optional: true
+        end
+
+        class Machine
+          include Mongoid::Document
+        end
+
+        class Lathe < Machine
+          has_many :widgets, class_name: 'Cog', inverse_of: :machine
+        end
+
+        class Press < Machine
+          has_many :widgets, class_name: 'Belt', inverse_of: :machine
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Press)
+        Object.send(:remove_const, :Lathe)
+        Object.send(:remove_const, :Machine)
+        Object.send(:remove_const, :Belt)
+        Object.send(:remove_const, :Cog)
+        Object.send(:remove_const, :Supplier)
+      end
+
+      let!(:cog_supplier) { Supplier.create! }
+      let!(:belt_supplier) { Supplier.create! }
+      let!(:lathe) { Lathe.create! }
+      let!(:press) { Press.create! }
+      let!(:cog) { Cog.create!(machine: lathe, supplier: cog_supplier) }
+      let!(:belt) { Belt.create!(machine: press, supplier: belt_supplier) }
+
+      it 'loads each subclass association without one overwriting the other' do
+        loaded = expect_query(1) do
+          Machine.eager_load(:widgets).to_a.index_by(&:id)
+        end
+        expect_no_queries do
+          expect(loaded[lathe.id].widgets).to eq([ cog ])
+          expect(loaded[press.id].widgets).to eq([ belt ])
+        end
+      end
+
+      it 'eager-loads inclusions nested under each subclass association' do
+        loaded = expect_query(1) do
+          Machine.eager_load(widgets: :supplier).to_a.index_by(&:id)
+        end
+        expect_no_queries do
+          expect(loaded[lathe.id].widgets.first.supplier).to eq(cog_supplier)
+          expect(loaded[press.id].widgets.first.supplier).to eq(belt_supplier)
+        end
+      end
+    end
+
+    context 'when a has_many targets a class sharing its collection with sibling subclasses' do
+      before(:all) do
+        class Part
+          include Mongoid::Document
+        end
+
+        class Chip < Part
+          belongs_to :board, class_name: 'Board', optional: true
+        end
+
+        class Cable < Part
+          belongs_to :board, class_name: 'Board', optional: true
+        end
+
+        class Board
+          include Mongoid::Document
+
+          has_many :chips, class_name: 'Chip', inverse_of: :board
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :Board)
+        Object.send(:remove_const, :Cable)
+        Object.send(:remove_const, :Chip)
+        Object.send(:remove_const, :Part)
+      end
+
+      let!(:board) { Board.create! }
+      let!(:chip) { Chip.create!(board: board) }
+      let!(:cable) { Cable.create!(board: board) }
+
+      it 'eager-loads only the chips, not the sibling subclass' do
+        expect_query(1) do
+          loaded = Board.eager_load(:chips).first
+          expect(loaded.chips.to_a).to eq([ chip ])
+        end
+      end
+    end
+  end
+
+  describe '#inclusions' do
+    let(:criteria) do
+      Band.includes(:records)
+    end
+
+    let(:association) do
+      Band.relations['records']
+    end
+
+    it 'returns the inclusions' do
+      expect(criteria.inclusions).to eq([ association ])
+    end
+  end
+
+  describe '#inclusions=' do
+    let(:criteria) do
+      Band.all
+    end
+
+    let(:association) do
+      Band.relations['records']
+    end
+
+    before do
+      criteria.inclusions = [ association ]
+    end
+
+    it 'sets the inclusions' do
+      expect(criteria.inclusions).to eq([ association ])
+    end
+  end
+
+  context 'When multiple associations reference the same class' do
+    before do
+      IncBlog.create(
+        posts: [
+          IncBlogPost.create(author: IncAuthor.create),
+          IncBlogPost.create(author: IncAuthor.create),
+          IncBlogPost.create(author: IncAuthor.create)
+        ],
+        highlighted_post: IncBlogPost.create(author: IncAuthor.create)
+      )
+    end
+
+    let!(:result) do
+      IncBlog.includes(:posts, highlighted_post: :author).first
+    end
+
+    it 'does not execute a query' do
+      expect_query(0) do
+        result.posts.to_a
+        result.highlighted_post
+      end
+    end
+
+    it 'executes a query for the non-retrieved elements' do
+      expect_query(3) do
+        result.posts.each do |post|
+          post.author
+        end
+      end
+    end
+  end
+
+  context 'When multiple parent_inclusions for the same association' do
+    before do
+      IncBlog.create(
+        posts: [
+          IncBlogPost.create(author: IncAuthor.create),
+          IncBlogPost.create(author: IncAuthor.create),
+          IncBlogPost.create(author: IncAuthor.create)
+        ],
+        highlighted_post: IncBlogPost.create(author: IncAuthor.create),
+        pinned_post: IncBlogPost.create(author: IncAuthor.create)
+      )
+    end
+
+    let!(:result) do
+      IncBlog.includes(:posts, highlighted_post: :author, pinned_post: :author).first
+    end
+
+    it 'does not execute a query' do
+      expect_query(0) do
+        result.posts.to_a
+        result.highlighted_post
+        result.pinned_post
+      end
+    end
+
+    it 'executes a query for the non-retrieved elements' do
+      expect_query(3) do
+        result.posts.each do |post|
+          post.author
+        end
+      end
+    end
 
+    context 'when including an association and using each twice on a criteria' do
       let(:criteria) { IncPost.all.includes(:person) }
 
       before do
-        p = IncPerson.create!(name: "name")
-        4.times { IncPost.create!(person: p)}
+        p = IncPerson.create!(name: 'name')
+        4.times { IncPost.create!(person: p) }
         criteria
         expect_query(2) do
           criteria.each(&:person)
@@ -1483,7 +2407,7 @@ describe Mongoid::Criteria::Includable do
       # trying to retrieve their person.
       # MONGOID-3942 reported that after iterating the criteria a second time,
       # the posts would not get the eager loaded person.
-      it "eager loads the criteria" do
+      it 'eager loads the criteria' do
         expect_query(2) do
           criteria.each(&:person)
         end