mongoid_includes 1.0.5

data/lib/mongoid/includes/version.rb

@@ -0,0 +1,10 @@
+# Mongoid is an ODM (Object Document Mapper) Framework for MongoDB, written in Ruby.
+module Mongoid
+  # Improves eager loading in Mongoid, supporting polymorphic associations,
+  # and up to two-levels of eager loading.
+  module Includes
+
+    # Public: This library will attempt to follow semantic versioning (whatever that's supposed to be).
+    VERSION = '1.0.5'
+  end
+end

data/lib/mongoid_includes.rb

@@ -0,0 +1,12 @@
+require 'mongoid'
+
+require 'mongoid/includes'
+
+# add english load path by default
+I18n.load_path << File.join(File.dirname(__FILE__), 'config', 'locales', 'en.yml')
+
+Mongoid::Contextual::Mongo.send :prepend, Mongoid::Includes::EagerLoad
+Mongoid::Contextual::Memory.send :prepend, Mongoid::Includes::EagerLoad
+
+Mongoid::Criteria.send :prepend, Mongoid::Includes::Criteria
+Mongoid::Relations::Eager::Base.send :prepend, Mongoid::Includes::Relations::Eager

data/spec/mongoid/includes/criteria_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe Mongoid::Criteria do
+  Given(:criteria) { Band.includes(:songs, :owner, from: :albums) }
+  Given(:other_criteria) { Band.includes(:musicians, :albums) }
+
+  describe '#merge' do
+    context 'inclusions are combined properly' do
+      When(:new_criteria) { criteria.merge(other_criteria) }
+      Then { new_criteria.inclusions.size == 4 }
+      And  { new_criteria.inclusions.class == Mongoid::Includes::Inclusions }
+      And  { criteria.inclusions.size == 3 }
+      And  { other_criteria.inclusions.size == 2 }
+    end
+  end
+
+  describe '#merge!' do
+    context 'inclusions are merged properly' do
+      When { criteria.merge!(other_criteria) }
+      Then { criteria.inclusions.size == 4 }
+      And  { criteria.inclusions.class == Mongoid::Includes::Inclusions }
+      And  { other_criteria.inclusions.size == 2 }
+    end
+  end
+end

data/spec/mongoid/includes/errors/invalid_includes_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Mongoid::Includes::Errors::InvalidIncludes do
+
+  describe "#message" do
+
+    Given(:error) {
+      described_class.new(Album, :something, {})
+    }
+
+    it "contains the problem in the message" do
+      expect(error.message).to include(
+        "Invalid includes directive: Album.includes(:something)"
+      )
+    end
+
+    it "contains the summary in the message" do
+      expect(error.message).to include(
+        "that are the names of relations on the Album model"
+      )
+    end
+
+    it "contains the resolution in the message" do
+      expect(error.message).to include(
+        "is a valid name of a relation on the Album model"
+      )
+    end
+  end
+end

data/spec/mongoid/includes/errors/invalid_polymorphic_includes_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Mongoid::Includes::Errors::InvalidPolymorphicIncludes do
+
+  describe "#message" do
+
+    Given(:error) {
+      described_class.new(Album, :something, from: :artist)
+    }
+
+    it "contains the problem in the message" do
+      expect(error.message).to include(
+        ":artist is a polymorphic relation"
+      )
+    end
+
+    it "contains the summary in the message" do
+      expect(error.message).to include(
+        "specify :from_class when calling the method to resolve the ambiguity"
+      )
+    end
+
+    it "contains the resolution in the message" do
+      expect(error.message).to include(
+        "non-polymorphic relation in the Album model, or a explicit class in :from_class"
+      )
+    end
+  end
+end

data/spec/mongoid/includes/inclusions_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe Mongoid::Includes::Inclusions do
+
+  describe '#inclusions' do
+    Given(:criteria) { Band.includes(:songs, :owner, from: :albums) }
+    Given(:inclusions) { criteria.inclusions }
+
+    context 'adding two different inclusions' do
+      Given(:other_criteria) { Band.includes(:musicians, :albums) }
+      When(:result) { inclusions + other_criteria.inclusions }
+      Then { result.size == 4 }
+      And  { result.class == Mongoid::Includes::Inclusions }
+    end
+
+    context 'when removing duplicates' do
+      Given(:inclusions) { Mongoid::Includes::Inclusions.new(criteria.inclusions) }
+      When(:result) { inclusions.uniq }
+      Then { result.size == 3 }
+      And  { result.class == Mongoid::Includes::Inclusions }
+    end
+  end
+end

data/spec/mongoid/includes/nested_inclusions_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+describe Mongoid::Includes::Criteria do
+
+  describe '#includes' do
+
+    context 'inclusion has additional options' do
+      Given(:band) { Band.create!(name: 'Pink Floyd') }
+      Given {
+        Album.create!(name: 'Wish You Were Here', release: Date.new(1975), owner: band)
+        Album.create!(name: 'The Dark Side of the Moon', release: Date.new(1973), owner: band)
+      }
+      Given(:criteria) {
+        Band.includes(:albums, with: ->(albums) { albums.lt(release: Date.new(1974)) })
+      }
+      When(:result) { criteria.entries.first }
+      Then { expect(result).to eq band }
+      And  { result.albums.first.name == 'The Dark Side of the Moon' }
+      And  { result.albums.size == 1 }
+      And  { band.albums.size == 2 }
+    end
+  end
+
+  describe '#inclusions' do
+    Given(:inclusions) { criteria.inclusions }
+
+    context 'does not duplicate inclusions' do
+      When(:criteria) {
+        Band.includes(:songs, :owner, from: :albums)
+          .includes(:musicians, :albums)
+          .includes(:songs, :owner, from: :albums)
+      }
+      Then { inclusions.size == 4 }
+    end
+
+    context 'each inclusion has valid properties' do
+      Given(:metadata) { Band.relations['albums'] }
+      Given(:nested_metadata) { Album.relations['songs'] }
+      Given(:polymorphic_metadata) { Album.relations['owner'] }
+
+      When(:criteria) { Band.includes(:songs, :owner, from: :albums) }
+
+      Then { inclusions.size == 3 }
+      And  { expect(inclusions).to include(metadata) }
+      And  { expect(inclusions).to include(nested_metadata) }
+      And  { expect(inclusions).to include(polymorphic_metadata) }
+      And  { !inclusions.to_a[0].nested? && !inclusions.to_a[0].polymorphic_belongs_to? }
+      And  { inclusions.to_a[1].nested? && !inclusions.to_a[1].polymorphic_belongs_to? }
+      And  { inclusions.to_a[2].nested? && inclusions.to_a[2].polymorphic_belongs_to? }
+    end
+  end
+end

data/spec/mongoid/includes/simple_inclusions_spec.rb

@@ -0,0 +1,1010 @@
+require 'spec_helper'
+
+describe Mongoid::Includes::Criteria do
+
+  describe '#includes' do
+
+    let!(:person) do
+      Person.create(age: 1)
+    end
+
+    context 'when providing a name that is not a relation' do
+
+      it 'raises an error' do
+        expect {
+          Person.includes(:members)
+        }.to raise_error(Mongoid::Includes::Errors::InvalidIncludes)
+      end
+    end
+
+    context 'when the models are inherited' do
+
+      before(:all) do
+        class A
+          include Mongoid::Document
+        end
+
+        class B < A
+          belongs_to :c
+        end
+
+        class C
+          include Mongoid::Document
+          has_one :b
+        end
+      end
+
+      after(:all) do
+        Object.send(:remove_const, :A)
+        Object.send(:remove_const, :B)
+        Object.send(:remove_const, :C)
+      end
+
+      context 'when the includes is on the subclass' do
+
+        let!(:c_one) do
+          C.create
+        end
+
+        let!(:c_two) do
+          C.create
+        end
+
+        let!(:b) do
+          B.create(c: c_two)
+        end
+
+        let!(:results) do
+          C.includes(:b).to_a.detect do |c|
+            c.id == c_two.id
+          end
+        end
+
+        it 'returns the correct documents' do
+          expect(results).to eq(c_two)
+        end
+
+        it 'does not query the db' do
+          expect_query(0) do
+            results.b
+          end
+        end
+      end
+    end
+
+    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
+          end
+
+          class B < A
+            belongs_to :d
+          end
+
+          class C < A
+            belongs_to :d
+          end
+
+          class D
+            include Mongoid::Document
+            has_one :b
+            has_one :c
+          end
+        end
+
+        after(:all) do
+          Object.send(:remove_const, :A)
+          Object.send(:remove_const, :B)
+          Object.send(:remove_const, :C)
+          Object.send(:remove_const, :D)
+        end
+
+        context 'when the includes is on the several relations' do
+
+          let!(:d_one) do
+            D.create
+          end
+
+          let!(:d_two) do
+            D.create
+          end
+
+          let!(:b) do
+            B.create(d: d_two)
+          end
+
+          let!(:c) do
+            C.create(d: d_two)
+          end
+
+          let!(:results) do
+            D.includes(:b, :c).entries.detect do |d|
+              d.id == d_two.id
+            end
+          end
+
+          it 'returns the correct documents' do
+            expect(results).to eq(d_two)
+          end
+
+          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
+            expect_query(0) do
+              results.b
+            end
+          end
+        end
+      end
+
+      context 'when the relation is a has_many' do
+
+        before(:all) do
+          class A
+            include Mongoid::Document
+          end
+
+          class B < A
+            belongs_to :d
+          end
+
+          class C < A
+            belongs_to :d
+          end
+
+          class D
+            include Mongoid::Document
+            has_many :b
+            has_many :c
+          end
+        end
+
+        after(:all) do
+          Object.send(:remove_const, :A)
+          Object.send(:remove_const, :B)
+          Object.send(:remove_const, :C)
+          Object.send(:remove_const, :D)
+        end
+
+        context 'when the includes is on the several relations' do
+
+          let!(:d_one) do
+            D.create
+          end
+
+          let!(:d_two) do
+            D.create
+          end
+
+          let!(:bs) do
+            2.times.map { B.create(d: d_two) }
+          end
+
+          let!(:cs) do
+            2.times.map { C.create(d: d_two) }
+          end
+
+          let!(:results) do
+            D.includes(:b, :c).entries.detect do |d|
+              d.id == d_two.id
+            end
+          end
+
+          it 'returns the correct documents' do
+            expect(results).to eq(d_two)
+          end
+
+          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
+            expect_query(0) do
+              results.b
+            end
+          end
+        end
+      end
+    end
+
+    context 'when including the same metadata multiple times' do
+
+      let(:criteria) do
+        Person.all.includes(:posts, :posts).includes(:posts)
+      end
+
+      let(:metadata) do
+        Person.reflect_on_association(:posts)
+      end
+
+      it 'does not duplicate the metadata in the inclusions' do
+        expect(criteria.inclusions.size).to eq 1
+        expect(criteria.inclusions.first).to eq metadata
+      end
+    end
+
+    context 'when mapping the results more than once' do
+
+      let!(:post) do
+        person.posts.create(title: 'one')
+      end
+
+      let(:criteria) do
+        Post.includes(:person)
+      end
+
+      let!(:results) do
+        criteria.map { |doc| doc }
+        criteria.map { |doc| doc }
+      end
+
+      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
+
+        let!(:person_two) do
+          Person.create(age: 2)
+        end
+
+        let!(:post_one) do
+          person.posts.create(title: 'one')
+        end
+
+        let!(:post_two) do
+          person_two.posts.create(title: 'two')
+        end
+
+        context 'when calling first' do
+
+          let(:criteria) do
+            Post.includes(:person)
+          end
+
+          let!(:document) do
+            criteria.first
+          end
+
+          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
+            expect(document).to eq(post_one)
+          end
+        end
+
+        context 'when calling last' do
+
+          let!(:criteria) do
+            Post.asc(:_id).includes(:person)
+          end
+
+          let!(:document) do
+            criteria.last
+          end
+
+          it 'eager loads the last document' do
+            expect_query(0) do
+              expect(document.person).to eq(person_two)
+            end
+          end
+
+          it 'does not eager load the first document' do
+            doc = criteria.first
+            expect_query(1) do
+              expect(doc.person).to eq(person)
+            end
+          end
+
+          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
+
+        let(:peep) do
+          Person.create
+        end
+
+        let!(:address_one) do
+          peep.addresses.create(street: 'rosenthaler')
+        end
+
+        let!(:address_two) do
+          peep.addresses.create(street: 'weinmeister')
+        end
+
+        let!(:depeche) do
+          Band.create!(name: 'Depeche Mode')
+        end
+
+        let!(:tool) do
+          Band.create!(name: 'Tool')
+        end
+
+        before do
+          address_one.band = depeche
+          address_two.band = tool
+          address_one.save
+          address_two.save
+        end
+
+        context 'when calling first' do
+
+          let(:criteria) do
+            peep.reload.addresses.includes(:band)
+          end
+
+          let(:context) do
+            criteria.context
+          end
+
+          let!(:document) do
+            criteria.first
+          end
+
+          it 'eager loads the first document' do
+            expect_query(0) do
+              expect(document.band).to eq(depeche)
+            end
+          end
+
+          it 'does not eager load the last document' do
+            doc = criteria.last
+            expect_query(1) do
+              expect(doc.band).to eq(tool)
+            end
+          end
+
+          it 'returns the document' do
+            expect(document).to eq(address_one)
+          end
+        end
+
+        context 'when calling last' do
+
+          let(:criteria) do
+            peep.reload.addresses.includes(:band)
+          end
+
+          let(:context) do
+            criteria.context
+          end
+
+          let!(:document) do
+            criteria.last
+          end
+
+          it 'eager loads the last document' do
+            expect_query(0) do
+              expect(document.band).to eq(tool)
+            end
+          end
+
+          it 'does not eager load the first document' do
+            doc = criteria.first
+            expect_query(1) do
+              expect(doc.band).to eq(depeche)
+            end
+          end
+
+          it 'returns the document' do
+            expect(document).to eq(address_two)
+          end
+        end
+
+        context 'when iterating all documents' do
+
+          let(:criteria) do
+            peep.reload.addresses.includes(:band)
+          end
+
+          let(:context) do
+            criteria.context
+          end
+
+          let!(:documents) do
+            criteria.to_a
+          end
+
+          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
+            expect_query(0) do
+              expect(documents.last.band).to eq(tool)
+            end
+          end
+
+          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
+
+      before do
+        Person.default_scope(->{ Person.includes(:posts) })
+      end
+
+      after do
+        Person.default_scoping = nil
+      end
+
+      let!(:post_one) do
+        person.posts.create(title: 'one')
+      end
+
+      let!(:post_two) do
+        person.posts.create(title: 'two')
+      end
+
+      context 'when the criteria has no options' do
+
+        let!(:criteria) do
+          Person.asc(:age).all
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(documents).to eq([ person ])
+        end
+
+        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
+          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
+
+          before do
+            expect(new_context).to receive(:eager_load_one).with(person).once.and_call_original
+          end
+
+          let!(:from_db) do
+            new_criteria.first
+          end
+
+          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
+
+        let(:criteria) do
+          Person.asc(:age).all
+        end
+
+        let!(:from_db) do
+          criteria.first
+        end
+
+        it 'returns the correct documents' do
+          expect(from_db).to eq(person)
+        end
+
+        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
+          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
+
+        before do
+          expect(context).to receive(:eager_load_one).with(person).once.and_call_original
+        end
+
+        let!(:from_db) do
+          criteria.last
+        end
+
+        it 'returns the correct documents' do
+          expect(from_db).to eq(person)
+        end
+
+        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
+          expect_query(0) do
+            expect(from_db.posts.last).to eq(post_two)
+          end
+        end
+      end
+
+      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')
+        end
+
+        let!(:criteria) do
+          Person.asc(:age).limit(1)
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(criteria).to eq([ person ])
+        end
+
+        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
+          expect_query(0) do
+            expect(documents.first.posts.last).to eq(post_two)
+          end
+        end
+      end
+    end
+
+    context 'when including a has and belongs to many' do
+
+      let!(:preference_one) do
+        person.preferences.create(name: 'one')
+      end
+
+      let!(:preference_two) do
+        person.preferences.create(name: 'two')
+      end
+
+      context 'when the criteria has no options' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:preferences)
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(documents).to eq([ person ])
+        end
+
+        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
+          expect_query(0) do
+            expect(documents.first.preferences.last).to eq(preference_two)
+          end
+        end
+      end
+
+      context 'when calling first on the criteria' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:preferences)
+        end
+
+        let!(:from_db) do
+          criteria.first
+        end
+
+        it 'returns the correct documents' do
+          expect(from_db).to eq(person)
+        end
+
+        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
+          expect_query(0) do
+            expect(from_db.preferences.last).to eq(preference_two)
+          end
+        end
+      end
+
+      context 'when calling last on the criteria' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:preferences)
+        end
+
+        let!(:from_db) do
+          criteria.last
+        end
+
+        it 'returns the correct documents' do
+          expect(from_db).to eq(person)
+        end
+
+        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
+          expect_query(0) do
+            expect(from_db.preferences.last).to eq(preference_two)
+          end
+        end
+      end
+    end
+
+    context 'when including a has many' do
+
+      let!(:post_one) do
+        person.posts.create(title: 'one')
+      end
+
+      let!(:post_two) do
+        person.posts.create(title: 'two')
+      end
+
+      context 'when the criteria has no options' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:posts)
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(documents).to eq([ person ])
+        end
+
+        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
+          expect_query(0) do
+            expect(documents.first.posts.last).to eq(post_two)
+          end
+        end
+      end
+
+      context 'when calling first on the criteria' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:posts)
+        end
+
+        let!(:from_db) do
+          criteria.first
+        end
+
+        it 'returns the correct documents' do
+          expect(from_db).to eq(person)
+        end
+
+        context 'when subsequently getting all documents' do
+
+          let!(:documents) do
+            criteria.entries
+          end
+
+          it 'returns the correct documents' do
+            expect(documents).to eq([ person ])
+          end
+        end
+      end
+
+      context 'when calling last on the criteria' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:posts)
+        end
+
+        let!(:from_db) do
+          criteria.last
+        end
+
+        it 'returns the correct documents' do
+          expect(from_db).to eq(person)
+        end
+
+        context 'when subsequently getting all documents' do
+
+          let!(:documents) do
+            criteria.entries
+          end
+
+          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
+          Person.create
+        end
+
+        let!(:post_three) do
+          person_two.posts.create(title: 'three')
+        end
+
+        let!(:criteria) do
+          Person.includes(:posts).asc(:age).limit(1)
+        end
+
+        let(:context) do
+          criteria.context
+        end
+
+        before do
+          expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(documents).to eq([ person ])
+        end
+      end
+    end
+
+    context 'when including a has one' do
+
+      let!(:game_one) do
+        person.create_game(name: 'one')
+      end
+
+      let!(:game_two) do
+        person.create_game(name: 'two')
+      end
+
+      context 'when the criteria has no options' do
+
+        let!(:criteria) do
+          Person.asc(:age).includes(:game)
+        end
+
+        let(:context) do
+          criteria.context
+        end
+
+        before do
+          expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        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
+          Person.create(age: 2)
+        end
+
+        let!(:game_three) do
+          person_two.create_game(name: 'Skyrim')
+        end
+
+        let!(:criteria) do
+          Person.where(id: person.id).includes(:game).asc(:age).limit(1)
+        end
+
+        let(:context) do
+          criteria.context
+        end
+
+        before do
+          expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(documents).to eq([ person ])
+        end
+      end
+    end
+
+    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')
+      end
+
+      let!(:game_two) do
+        person_two.create_game(name: 'two')
+      end
+
+      context 'when providing no options' do
+
+        let!(:criteria) do
+          Game.includes(:person)
+        end
+
+        let(:context) do
+          criteria.context
+        end
+
+        before do
+          expect(context).to receive(:eager_load).with([ game_one, game_two ]).once.and_call_original
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(criteria).to eq([ game_one, game_two ])
+        end
+      end
+
+      context 'when the criteria has limiting options' do
+
+        let!(:criteria) do
+          Game.where(id: game_one.id).includes(:person).asc(:_id).limit(1)
+        end
+
+        let(:context) do
+          criteria.context
+        end
+
+        before do
+          expect(context).to receive(:eager_load).with([ game_one ]).once.and_call_original
+        end
+
+        let!(:documents) do
+          criteria.entries
+        end
+
+        it 'returns the correct documents' do
+          expect(documents).to eq([ game_one ])
+        end
+      end
+    end
+
+    context 'when including multiples in the same criteria' do
+
+      let!(:post_one) do
+        person.posts.create(title: 'one')
+      end
+
+      let!(:post_two) do
+        person.posts.create(title: 'two')
+      end
+
+      let!(:game_one) do
+        person.create_game(name: 'one')
+      end
+
+      let!(:game_two) do
+        person.create_game(name: 'two')
+      end
+
+      let!(:criteria) do
+        Person.includes(:posts, :game).asc(:age)
+      end
+
+      let(:context) do
+        criteria.context
+      end
+
+      before do
+        expect(context).to receive(:eager_load).with([ person ]).once.and_call_original
+      end
+
+      let!(:documents) do
+        criteria.entries
+      end
+
+      it 'returns the correct documents' do
+        expect(criteria).to eq([ person ])
+      end
+    end
+  end
+
+  describe '#inclusions' do
+
+    Given(:criteria) { Band.includes(:albums) }
+    Given(:metadata) { Band.relations['albums'] }
+    Then { expect(criteria.inclusions).to include(metadata) }
+    And  { criteria.inclusions.none?(&:nested?) }
+  end
+
+  describe '#inclusions=' do
+    Given(:criteria) { Band.all }
+    Given(:metadata) { Band.relations['records'] }
+
+    When { criteria.inclusions = [ Mongoid::Includes::Inclusion.new(metadata) ] }
+
+    Then { expect(criteria.inclusions).to include(metadata) }
+    And  { criteria.inclusions.first.is_a?(Mongoid::Includes::Inclusion) }
+  end
+end