cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections/rspec/deferred/collection_examples.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+require 'cuprum/collections/rspec/deferred'
+require 'cuprum/collections/rspec/deferred/relation_examples'
+
+module Cuprum::Collections::RSpec::Deferred
+  # Deferred examples for testing collections.
+  module CollectionExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+    include Cuprum::Collections::RSpec::Deferred::RelationExamples
+
+    deferred_examples 'should be a Collection' do |**options|
+      include Cuprum::Collections::RSpec::Deferred::RelationExamples
+
+      deferred_examples 'should define the command' \
+      do |command_name, command_class_name = nil|
+        next if options[:abstract]
+
+        tools      = SleepingKingStudios::Tools::Toolbelt.instance
+        class_name = tools.str.camelize(command_name)
+
+        describe "##{command_name}" do
+          let(:constructor_options) { defined?(super()) ? super() : {} }
+          let(:command)             { build_command(collection) }
+          let(:command_class) do
+            (
+              command_class_name ||
+              "#{options[:commands_namespace]}::#{class_name}"
+            )
+              .then { |str| Object.const_get(str) }
+          end
+
+          define_method(:build_command) do |collection|
+            collection.send(command_name, **constructor_options)
+          end
+
+          it 'should define the command' do
+            expect(collection)
+              .to respond_to(command_name)
+              .with(0).arguments
+              .and_any_keywords
+          end
+
+          it { expect(command).to be_a command_class }
+
+          it { expect(command.collection).to be subject }
+        end
+      end
+
+      include_deferred 'should be a Relation',
+        constructor:          false,
+        default_entity_class: options[:default_entity_class]
+
+      include_deferred 'should define Relation primary key'
+
+      include_deferred 'should define Relation scope',
+        default_scope: options[:default_scope]
+
+      include_deferred 'should define the command', :assign_one
+
+      include_deferred 'should define the command', :build_one
+
+      include_deferred 'should define the command', :destroy_one
+
+      include_deferred 'should define the command', :find_many
+
+      include_deferred 'should define the command', :find_matching
+
+      include_deferred 'should define the command', :find_one
+
+      include_deferred 'should define the command', :insert_one
+
+      include_deferred 'should define the command', :update_one
+
+      include_deferred 'should define the command', :validate_one
+
+      describe '#==' do
+        let(:other_options)    { { name: } }
+        let(:other_collection) { described_class.new(**other_options) }
+
+        describe 'with nil' do
+          it { expect(collection == nil).to be false } # rubocop:disable Style/NilComparison
+        end
+
+        describe 'with an object' do
+          it { expect(collection == Object.new.freeze).to be false }
+        end
+
+        describe 'with a collection with non-matching properties' do
+          let(:other_options) { super().merge(custom_option: 'value') }
+
+          it { expect(collection == other_collection).to be false }
+        end
+
+        describe 'with a collection with matching properties' do
+          it { expect(collection == other_collection).to be true }
+        end
+
+        describe 'with another type of collection' do
+          let(:other_collection) do
+            Spec::OtherCollection.new(**other_options)
+          end
+
+          example_class 'Spec::OtherCollection',
+            Cuprum::Collections::Collection
+
+          it { expect(collection == other_collection).to be false }
+        end
+
+        context 'when initialized with options' do
+          let(:constructor_options) do
+            super().merge(
+              qualified_name: 'spec/scoped_books',
+              singular_name:  'grimoire'
+            )
+          end
+
+          describe 'with a collection with non-matching properties' do
+            it { expect(collection == other_collection).to be false }
+          end
+
+          describe 'with a collection with matching properties' do
+            let(:other_options) do
+              super().merge(
+                qualified_name: 'spec/scoped_books',
+                singular_name:  'grimoire'
+              )
+            end
+
+            it { expect(collection == other_collection).to be true }
+          end
+        end
+      end
+
+      describe '#count' do
+        it { expect(collection).to respond_to(:count).with(0).arguments }
+
+        it { expect(collection).to have_aliased_method(:count).as(:size) }
+
+        next if options[:abstract]
+
+        it { expect(collection.count).to be 0 }
+
+        wrap_context 'when the collection has many items' do
+          it { expect(collection.count).to be items.count }
+        end
+      end
+
+      describe '#matches?' do
+        def tools
+          SleepingKingStudios::Tools::Toolbelt.instance
+        end
+
+        it 'should define the method' do
+          expect(collection)
+            .to respond_to(:matches?)
+            .with(0).arguments
+            .and_any_keywords
+        end
+
+        describe 'with no options' do
+          it { expect(collection.matches?).to be true }
+        end
+
+        describe 'with non-matching entity class as a Class' do
+          let(:other_options) { { entity_class: Grimoire } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with non-matching entity class as a String' do
+          let(:other_options) { { entity_class: 'Grimoire' } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with non-matching name' do
+          it { expect(collection.matches?(name: 'grimoires')).to be false }
+        end
+
+        describe 'with non-matching primary key name' do
+          let(:other_options) { { primary_key_name: 'uuid' } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with non-matching primary key type' do
+          let(:other_options) { { primary_key_type: String } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with non-matching qualified name' do
+          let(:other_options) { { qualified_name: 'spec/scoped_books' } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with non-matching singular name' do
+          let(:other_options) { { singular_name: 'grimoire' } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with non-matching custom options' do
+          let(:other_options) { { custom_option: 'custom value' } }
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with partially-matching options' do
+          let(:other_options) do
+            {
+              name:,
+              singular_name: 'grimoire'
+            }
+          end
+
+          it { expect(collection.matches?(**other_options)).to be false }
+        end
+
+        describe 'with matching entity class as a Class' do
+          let(:configured_entity_class) do
+            options.fetch(:default_entity_class, Book)
+          end
+          let(:other_options) { { entity_class: configured_entity_class } }
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with matching entity class as a String' do
+          let(:configured_entity_class) do
+            options.fetch(:default_entity_class, Book)
+          end
+          let(:other_options) do
+            { entity_class: configured_entity_class.to_s }
+          end
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with matching name' do
+          let(:other_options) { { name: } }
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with matching primary key name' do
+          let(:other_options) { { primary_key_name: 'id' } }
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with matching primary key type' do
+          let(:other_options) { { primary_key_type: Integer } }
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with matching qualified name' do
+          let(:other_options) { { qualified_name: name } }
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with matching singular name' do
+          let(:other_options) do
+            { singular_name: tools.str.singularize(name) }
+          end
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+
+        describe 'with multiple matching options' do
+          let(:other_options) do
+            {
+              name:,
+              primary_key_name: 'id',
+              qualified_name:   name
+            }
+          end
+
+          it { expect(collection.matches?(**other_options)).to be true }
+        end
+      end
+
+      describe '#query' do
+        let(:error_message) do
+          "#{described_class.name} is an abstract class. Define a " \
+            'collection subclass and implement the #query method.'
+        end
+        let(:default_order) { defined?(super()) ? super() : {} }
+        let(:query)         { collection.query }
+
+        it { expect(collection).to respond_to(:query).with(0).arguments }
+
+        if options[:abstract]
+          it 'should raise an exception' do
+            expect { collection.query }
+              .to raise_error(
+                described_class::AbstractCollectionError,
+                error_message
+              )
+          end
+        else
+          it { expect(collection.query).to be_a query_class }
+
+          it 'should set the query options' do
+            query_options.each do |option, value|
+              expect(collection.query.send(option)).to be == value
+            end
+          end
+
+          it { expect(query.limit).to be nil }
+
+          it { expect(query.offset).to be nil }
+
+          it { expect(query.order).to be == default_order }
+
+          it { expect(query.scope).to be == subject.scope }
+
+          context 'when initialized with a scope' do
+            let(:initial_scope) do
+              Cuprum::Collections::Scope.new({ 'ok' => true })
+            end
+            let(:constructor_options) do
+              super().merge(scope: initial_scope)
+            end
+
+            it { expect(query.scope).to be == subject.scope }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/deferred/command_examples.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'cuprum/rspec/deferred/parameter_validation_examples'
+require 'rspec/sleeping_king_studios/deferred'
+
+require 'cuprum/collections/rspec/deferred'
+
+module Cuprum::Collections::RSpec::Deferred
+  # Deferred examples for testing collection commands.
+  module CommandExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+    include Cuprum::RSpec::Deferred::ParameterValidationExamples
+
+    deferred_examples 'should implement the CollectionCommand methods' do
+      describe '#collection' do
+        include_examples 'should define reader', :collection, -> { collection }
+      end
+
+      describe '#name' do
+        include_examples 'should define reader', :name, -> { collection.name }
+
+        it 'should alias the method' do
+          expect(subject).to have_aliased_method(:name).as(:collection_name)
+        end
+      end
+
+      describe '#primary_key_name' do
+        include_examples 'should define reader',
+          :primary_key_name,
+          -> { collection.primary_key_name }
+      end
+
+      describe '#primary_key_type' do
+        include_examples 'should define reader',
+          :primary_key_type,
+          -> { collection.primary_key_type }
+      end
+
+      describe '#query' do
+        let(:mock_query) { instance_double(Cuprum::Collections::Query) }
+
+        before(:example) do
+          allow(collection).to receive(:query).and_return(mock_query)
+        end
+
+        it { expect(subject).to respond_to(:query).with(0).arguments }
+
+        it { expect(subject.query).to be mock_query }
+      end
+
+      describe '#singular_name' do
+        include_examples 'should define reader',
+          :singular_name,
+          -> { collection.singular_name }
+
+        it 'should alias the method' do
+          expect(subject)
+            .to have_aliased_method(:singular_name)
+            .as(:member_name)
+        end
+      end
+    end
+
+    deferred_examples 'should validate the attributes parameter' do
+      describe 'with an invalid attributes value' do
+        let(:attributes) { Object.new.freeze }
+
+        include_deferred 'should validate the parameter',
+          :attributes,
+          'sleeping_king_studios.tools.assertions.instance_of',
+          expected: Hash
+      end
+
+      describe 'with an attributes value with invalid keys' do
+        let(:attributes) do
+          {
+            nil      => 'NilClass',
+            'string' => 'String',
+            symbol:     'Symbol'
+          }
+        end
+
+        include_deferred 'should validate the parameter',
+          'attributes[nil] key',
+          'sleeping_king_studios.tools.assertions.presence'
+      end
+    end
+
+    deferred_examples 'should validate the primary key parameter' do
+      describe 'with an invalid primary key value' do
+        let(:primary_key) { Object.new.freeze }
+        let(:expected_error) do
+          Cuprum::Errors::InvalidParameters.new(
+            command_class: command.class,
+            failures:      [
+              tools.assertions.error_message_for(
+                'sleeping_king_studios.tools.assertions.instance_of',
+                as:       'primary_key',
+                expected: collection.primary_key_type
+              )
+            ]
+          )
+        end
+
+        it 'should return a failing result with InvalidParameters error' do
+          expect(call_command)
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+    end
+
+    deferred_examples 'should validate the primary keys parameter' do
+      describe 'with an invalid primary keys value' do
+        let(:primary_keys) { Object.new.freeze }
+
+        include_deferred 'should validate the parameter',
+          :primary_keys,
+          'sleeping_king_studios.tools.assertions.instance_of',
+          expected: Array
+      end
+
+      describe 'with an attributes value with invalid keys' do
+        let(:valid_primary_key_value) do
+          defined?(super()) ? super() : 0
+        end
+        let(:primary_keys) do
+          [
+            nil,
+            Object.new.freeze,
+            valid_primary_key_value
+          ]
+        end
+        let(:expected_error) do
+          Cuprum::Errors::InvalidParameters.new(
+            command_class: command.class,
+            failures:      [
+              tools.assertions.error_message_for(
+                'sleeping_king_studios.tools.assertions.instance_of',
+                as:       'primary_keys[0]',
+                expected: collection.primary_key_type
+              ),
+              tools.assertions.error_message_for(
+                'sleeping_king_studios.tools.assertions.instance_of',
+                as:       'primary_keys[1]',
+                expected: collection.primary_key_type
+              )
+            ]
+          )
+        end
+
+        it 'should return a failing result with InvalidParameters error' do
+          expect(call_command)
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/deferred/commands/assign_one_examples.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec/deferred/command_examples'
+require 'cuprum/collections/rspec/deferred/commands'
+
+module Cuprum::Collections::RSpec::Deferred::Commands
+  # Namespace for deferred example groups for validating AssignOne commands.
+  module AssignOneExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should implement the AssignOne command' \
+    do |allow_extra_attributes: true|
+      describe '#call' do
+        include Cuprum::Collections::RSpec::Deferred::CommandExamples
+
+        shared_examples 'should assign the attributes' do
+          it { expect(result).to be_a_passing_result }
+
+          it { expect(result.value).to be_a entity.class }
+
+          it { expect(result.value).to be == expected_value }
+        end
+
+        let(:attributes) { {} }
+        let(:result) do
+          command.call(attributes:, entity:)
+        end
+        let(:expected_attributes) do
+          initial_attributes.merge(attributes)
+        end
+        let(:expected_value) do
+          defined?(super()) ? super() : expected_attributes
+        end
+
+        def call_command
+          command.call(attributes:, entity:)
+        end
+
+        include_deferred 'should validate the attributes parameter'
+
+        if defined_deferred_examples? 'should validate the entity'
+          include_deferred 'should validate the entity'
+        else
+          # :nocov:
+          pending \
+            'the command should validate the entity parameter, but entity ' \
+            'validation is not defined - implement a "should validate the ' \
+            'entity" deferred example group to resolve this warning'
+          # :nocov:
+        end
+
+        describe 'with an empty attributes hash' do
+          let(:attributes) { {} }
+
+          include_examples 'should assign the attributes'
+        end
+
+        describe 'with an attributes hash with partial attributes' do
+          let(:attributes) { { title: 'Gideon the Ninth' } }
+
+          include_examples 'should assign the attributes'
+        end
+
+        describe 'with an attributes hash with full attributes' do
+          let(:attributes) do
+            {
+              title:    'Gideon the Ninth',
+              author:   'Tamsyn Muir',
+              series:   'The Locked Tomb',
+              category: 'Horror'
+            }
+          end
+
+          include_examples 'should assign the attributes'
+        end
+
+        describe 'with an attributes hash with extra attributes' do
+          let(:attributes) do
+            {
+              title:     'The Book of Lost Tales',
+              audiobook: true
+            }
+          end
+
+          if allow_extra_attributes
+            include_examples 'should assign the attributes'
+          else
+            # :nocov:
+            let(:valid_attributes) do
+              defined?(super()) ? super() : expected_attributes.keys
+            end
+            let(:expected_error) do
+              Cuprum::Collections::Errors::ExtraAttributes.new(
+                entity_class:     entity.class,
+                extra_attributes: %w[audiobook],
+                valid_attributes:
+              )
+            end
+
+            it 'should return a failing result' do
+              expect(result).to be_a_failing_result.with_error(expected_error)
+            end
+            # :nocov:
+          end
+        end
+
+        context 'when the entity has existing attributes' do
+          let(:initial_attributes) do
+            # :nocov:
+            if defined?(super())
+              super().merge(fixtures_data.first)
+            else
+              fixtures_data.first
+            end
+            # :nocov:
+          end
+
+          describe 'with an empty attributes hash' do
+            let(:attributes) { {} }
+
+            include_examples 'should assign the attributes'
+          end
+
+          describe 'with an attributes hash with partial attributes' do
+            let(:attributes) { { title: 'Gideon the Ninth' } }
+
+            include_examples 'should assign the attributes'
+          end
+
+          describe 'with an attributes hash with full attributes' do
+            let(:attributes) do
+              {
+                title:    'Gideon the Ninth',
+                author:   'Tamsyn Muir',
+                series:   'The Locked Tomb',
+                category: 'Horror'
+              }
+            end
+
+            include_examples 'should assign the attributes'
+          end
+
+          describe 'with an attributes hash with extra attributes' do
+            let(:attributes) do
+              {
+                title:     'The Book of Lost Tales',
+                audiobook: true
+              }
+            end
+
+            if allow_extra_attributes
+              include_examples 'should assign the attributes'
+            else
+              # :nocov:
+              let(:valid_attributes) do
+                defined?(super()) ? super() : expected_attributes.keys
+              end
+              let(:expected_error) do
+                Cuprum::Collections::Errors::ExtraAttributes.new(
+                  entity_class:     entity.class,
+                  extra_attributes: %w[audiobook],
+                  valid_attributes:
+                )
+              end
+
+              it 'should return a failing result' do
+                expect(result)
+                  .to be_a_failing_result
+                  .with_error(expected_error)
+              end
+              # :nocov:
+            end
+          end
+        end
+      end
+    end
+  end
+end