cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/rspec/contracts/actions/create_contracts.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/contract'
+
+require 'cuprum/rails/rspec/contract_helpers'
+require 'cuprum/rails/rspec/contracts/action_contracts'
+require 'cuprum/rails/rspec/contracts/actions'
+
+module Cuprum::Rails::RSpec::Contracts::Actions
+  # Namespace for RSpec create contracts, which validate create implementations.
+  module CreateContracts
+    # Contract asserting the action implements the create action interface.
+    module ShouldBeACreateActionContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, invalid_attributes:, valid_attributes:, **options)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param invalid_attributes [Hash<String>] A set of attributes that will
+      #     fail validation.
+      #   @param valid_attributes [Hash<String>] A set of attributes that will
+      #     pass validation.
+      #
+      #   @option options [Hash<String>] duplicate_attributes A set of
+      #     attributes for a duplicate entity.
+      #   @option options [#to_proc] examples_on_failure Extra examples to run
+      #     for the failing cases.
+      #   @option options [#to_proc] examples_on_success Extra examples to run
+      #     for the passing case.
+      #   @option options [Hash<String>] expected_attributes The expected
+      #     attributes for both a failed validation and a returned entity.
+      #   @option options [Hash<String>] expected_attributes_on_failure The
+      #     expected attributes for a failed validation. Defaults to the value
+      #     of invalid_attributes.
+      #   @option options [Hash<String>] expected_attributes_on_success The
+      #     expected attributes for the returned object. Defaults to the value
+      #     of valid_attributes.
+      #   @option options [Hash<String>] expected_value_on_success The expected
+      #     value for the passing result. Defaults to a Hash with the created
+      #     entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to the given attributes.
+      #
+      #   @yield Additional examples to run for the passing case.
+
+      contract do |invalid_attributes:, valid_attributes:, **options, &block|
+        include Cuprum::Rails::RSpec::Contracts::ActionContracts
+        include Cuprum::Rails::RSpec::Contracts::Actions::CreateContracts
+
+        options = options.merge(valid_attributes: valid_attributes)
+        configured_params = lambda do
+          attributes =
+            Cuprum::Rails::RSpec::ContractHelpers.option_with_default(
+              valid_attributes,
+              context: self
+            )
+
+          Cuprum::Rails::RSpec::ContractHelpers.option_with_default(
+            options[:params],
+            context: self,
+            default: {
+              configured_resource.singular_name => attributes
+            }
+          )
+        end
+
+        # :nocov:
+        if options[:examples_on_success] && block
+          raise ArgumentError, 'provide either :examples_on_success or a block'
+        elsif block
+          options[:examples_on_success] = block
+        end
+        # :nocov:
+
+        should_not_create_an_entity = lambda do
+          it 'should not create an entity' do
+            expect { call_action }
+              .not_to change(configured_resource.entity_class, :count)
+          end
+
+          # :nocov:
+          if options[:examples_on_failure]
+            instance_exec(&options[:examples_on_failure])
+          end
+          # :nocov:
+        end
+
+        include_contract 'should be a resource action',
+          require_permitted_attributes: true
+
+        include_contract(
+          'should require parameters',
+          params: configured_params,
+          &should_not_create_an_entity
+        )
+
+        include_contract(
+          'should validate attributes',
+          expected_attributes: options.fetch(
+            :expected_attributes,
+            options[:expected_attributes_on_failure]
+          ),
+          invalid_attributes:  invalid_attributes,
+          params:              configured_params,
+          &should_not_create_an_entity
+        )
+
+        if options[:duplicate_attributes]
+          include_contract(
+            'should not create a duplicate entity',
+            params:           configured_params,
+            valid_attributes: options[:duplicate_attributes],
+            &should_not_create_an_entity
+          )
+        end
+
+        include_contract 'should create the entity',
+          expected_attributes: options.fetch(
+            :expected_attributes,
+            options[:expected_attributes_on_success]
+          ),
+          expected_value:      options[:expected_value_on_success],
+          params:              configured_params,
+          valid_attributes:    valid_attributes,
+          &options[:examples_on_success]
+      end
+    end
+
+    # Contract asserting the action creates a new entity.
+    module ShouldCreateTheEntityContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @!method apply(example_group, valid_attributes:, **options)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #
+      #   @option options [Hash<String>] expected_attributes The expected
+      #     attributes for the returned object. Defaults to the value of
+      #     valid_attributes.
+      #   @option options [Hash<String>] expected_value The expected value for
+      #     the passing result. Defaults to a Hash with the created entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to the given attributes.
+      #   @option options [Hash<String>] valid_attributes A set of attributes
+      #     that will pass validation.
+      #
+      #   @yield Additional examples.
+
+      contract do |valid_attributes:, **options, &block|
+        describe '#call' do
+          include Cuprum::Rails::RSpec::ContractHelpers
+
+          context 'with valid parameters' do
+            let(:request) do
+              Cuprum::Rails::Request.new(params: configured_params)
+            end
+            let(:configured_valid_attributes) do
+              option_with_default(valid_attributes)
+            end
+            let(:configured_params) do
+              resource_name = resource.singular_name
+
+              option_with_default(
+                options[:params],
+                default: {}
+              )
+                .merge({ resource_name => configured_valid_attributes })
+            end
+            let(:configured_expected_attributes) do
+              option_with_default(
+                options[:expected_attributes],
+                default: configured_valid_attributes
+              )
+            end
+            let(:configured_expected_entity) do
+              action
+                .resource
+                .entity_class
+                .where(configured_expected_attributes)
+                .first
+            end
+            let(:configured_expected_value) do
+              resource_name = resource.singular_name
+
+              option_with_default(
+                options[:expected_value],
+                default: {
+                  resource_name => configured_expected_entity
+                }
+              )
+            end
+
+            it 'should return a passing result' do
+              expect(call_action)
+                .to be_a_passing_result
+                .with_value(configured_expected_value)
+            end
+
+            it 'should create the entity', :aggregate_failures do
+              expect { call_action }
+                .to change(configured_resource.entity_class, :count)
+                .by(1)
+
+              expect(
+                action
+                  .resource
+                  .entity_class
+                  .where(configured_expected_attributes)
+                  .exists?
+              ).to be true
+            end
+
+            instance_exec(&block) if block.is_a?(Proc)
+          end
+        end
+      end
+    end
+
+    # Contract asserting the action does not create a duplicate entity.
+    module ShouldNotCreateADuplicateEntityContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @!method apply(example_group, valid_attributes:, primary_key: "id")
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param valid_attributes [Hash<String>] A set of attributes that will
+      #     pass validation.
+      #
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to the given attributes.
+      #
+      #   @yield Additional examples.
+
+      contract do |valid_attributes:, **options, &block|
+        describe '#call' do
+          include Cuprum::Rails::RSpec::ContractHelpers
+
+          context 'with duplicate parameters' do
+            let(:request) do
+              Cuprum::Rails::Request.new(params: configured_params)
+            end
+            let(:configured_valid_attributes) do
+              option_with_default(valid_attributes)
+            end
+            let(:configured_duplicate_entity) do
+              configured_resource.entity_class.new(valid_attributes)
+            end
+            let(:configured_params) do
+              resource_name = configured_resource.singular_name
+
+              option_with_default(
+                options[:params],
+                default: {}
+              )
+                .merge({ resource_name => configured_valid_attributes })
+            end
+            let(:configured_expected_error) do
+              primary_key_name  = configured_resource.primary_key.to_s
+              primary_key_value = configured_duplicate_entity[primary_key_name]
+
+              Cuprum::Collections::Errors::AlreadyExists.new(
+                attribute_name:  primary_key_name,
+                attribute_value: primary_key_value,
+                collection_name: configured_resource.name,
+                primary_key:     true
+              )
+            end
+
+            before(:example) { configured_duplicate_entity.save! }
+
+            it 'should return a failing result' do
+              expect(call_action)
+                .to be_a_failing_result
+                .with_error(configured_expected_error)
+            end
+
+            instance_exec(&block) if block.is_a?(Proc)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/rails/rspec/contracts/actions/destroy_contracts.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/contract'
+
+require 'cuprum/rails/rspec/contract_helpers'
+require 'cuprum/rails/rspec/contracts/action_contracts'
+require 'cuprum/rails/rspec/contracts/actions'
+
+module Cuprum::Rails::RSpec::Contracts::Actions
+  # Namespace for RSpec destroy contracts, which validate destroy
+  # implementations.
+  module DestroyContracts
+    # Contract asserting the action implements the destroy action interface.
+    module ShouldBeADestroyActionContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, existing_entity:, **options)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param existing_entity [Object] The existing entity to destroy.
+      #
+      #   @option options [#to_proc] examples_on_failure Extra examples to run
+      #     for the failing cases.
+      #   @option options [#to_proc] examples_on_success Extra examples to run
+      #     for the passing case.
+      #   @option options [Hash<String>] expected_value_on_success The expected
+      #     value for the passing result. Defaults to a Hash with the destroyed
+      #     entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to the id of the entity.
+      #   @option options [Object] primary_key_value The value of the primary
+      #     key for the missing entity.
+      #
+      #   @yield Additional examples to run for the passing case.
+
+      contract do |existing_entity:, **options, &block|
+        include Cuprum::Rails::RSpec::Contracts::ActionContracts
+        include Cuprum::Rails::RSpec::Contracts::Actions::DestroyContracts
+
+        # :nocov:
+        if options[:examples_on_success] && block
+          raise ArgumentError, 'provide either :examples_on_success or a block'
+        elsif block
+          options[:examples_on_success] = block
+        end
+        # :nocov:
+
+        should_not_destroy_the_entity = lambda do
+          it 'should not destroy the entity' do
+            expect { call_action }
+              .not_to change(configured_resource.entity_class, :count)
+          end
+
+          # :nocov:
+          if options[:examples_on_failure]
+            instance_exec(&options[:examples_on_failure])
+          end
+          # :nocov:
+        end
+
+        include_contract 'should be a resource action'
+
+        include_contract(
+          'should require primary key',
+          params: options[:params],
+          &should_not_destroy_the_entity
+        )
+
+        include_contract(
+          'should require existing entity',
+          params:            options[:params],
+          primary_key_value: options[:primary_key_value],
+          &should_not_destroy_the_entity
+        )
+
+        include_contract(
+          'should destroy the entity',
+          existing_entity: existing_entity,
+          expected_value:  options[:expected_value_on_success],
+          params:          options[:params],
+          &options[:examples_on_success]
+        )
+      end
+    end
+
+    # Contract asserting the action destroys the specified entity.
+    module ShouldDestroyTheEntityContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, existing_entity:, **options, &block)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param existing_entity [Object] The existing entity to destroy.
+      #
+      #   @option options [Hash<String>] expected_value The expected value for
+      #     the passing result. Defaults to a Hash with the destroyed entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to the id of the entity.
+      #
+      #   @yield Additional configuration or examples.
+
+      contract do |existing_entity:, **options, &block|
+        describe '#call' do
+          include Cuprum::Rails::RSpec::ContractHelpers
+
+          context 'when the entity exists' do
+            let(:request) do
+              Cuprum::Rails::Request.new(params: configured_params)
+            end
+            let(:configured_existing_entity) do
+              option_with_default(existing_entity)
+            end
+            let(:configured_params) do
+              resource_id =
+                configured_existing_entity[configured_resource.primary_key]
+
+              option_with_default(
+                options[:params],
+                default: { 'id' => resource_id }
+              )
+            end
+            let(:configured_expected_value) do
+              resource_name = configured_resource.singular_name
+
+              option_with_default(
+                options[:expected_value],
+                default: {
+                  resource_name => configured_existing_entity
+                }
+              )
+            end
+
+            it 'should return a passing result' do
+              expect(call_action)
+                .to be_a_passing_result
+                .with_value(configured_expected_value)
+            end
+
+            it 'should destroy the entity', :aggregate_failures do
+              expect { call_action }
+                .to change(configured_resource.entity_class, :count)
+                .by(-1)
+
+              primary_key_name  = configured_resource.primary_key
+              primary_key_value = configured_existing_entity[primary_key_name]
+              expect(
+                action
+                .resource
+                .entity_class
+                .exists?(primary_key_name => primary_key_value)
+              ).to be false
+            end
+
+            instance_exec(&block) if block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/rails/rspec/contracts/actions/edit_contracts.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/contract'
+
+require 'cuprum/rails/rspec/contract_helpers'
+require 'cuprum/rails/rspec/contracts/action_contracts'
+require 'cuprum/rails/rspec/contracts/actions'
+
+module Cuprum::Rails::RSpec::Contracts::Actions
+  # Namespace for RSpec edit contracts, which validate edit implementations.
+  module EditContracts
+    # Contract asserting the action implements the edit action interface.
+    module ShouldBeAnEditActionContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, existing_entity:, **options)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param existing_entity [Object] The existing entity to find.
+      #
+      #   @option options [#to_proc] examples_on_failure Extra examples to run
+      #     for the failing cases.
+      #   @option options [#to_proc] examples_on_success Extra examples to run
+      #     for the passing case.
+      #   @option options [Hash<String>] expected_value_on_success The expected
+      #     value for the passing result. Defaults to a Hash with the found
+      #     entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to the id of the entity.
+      #   @option options [Object] primary_key_value The value of the primary
+      #     key for the missing entity.
+      #
+      #   @yield Additional examples to run for the passing case.
+
+      contract do |existing_entity:, **options, &block|
+        include Cuprum::Rails::RSpec::Contracts::ActionContracts
+
+        # :nocov:
+        if options[:examples_on_success] && block
+          raise ArgumentError, 'provide either :examples_on_success or a block'
+        elsif block
+          options[:examples_on_success] = block
+        end
+        # :nocov:
+
+        include_contract 'should be a resource action'
+
+        include_contract(
+          'should require primary key',
+          params: options[:params],
+          &options[:examples_on_failure]
+        )
+
+        include_contract(
+          'should require existing entity',
+          params:            options[:params],
+          primary_key_value: options[:primary_key_value],
+          &options[:examples_on_failure]
+        )
+
+        include_contract(
+          'should find the entity',
+          existing_entity: existing_entity,
+          expected_value:  options[:expected_value_on_success],
+          params:          options[:params],
+          &options[:examples_on_success]
+        )
+      end
+    end
+  end
+end

data/lib/cuprum/rails/rspec/contracts/actions/index_contracts.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/rspec/contracts/action_contracts'
+require 'cuprum/rails/rspec/contracts/actions'
+
+module Cuprum::Rails::RSpec::Contracts::Actions
+  # Namespace for RSpec index contracts, which validate index implementations.
+  module IndexContracts
+    # Contract asserting the action implements the index action interface.
+    module ShouldBeAnIndexActionContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, existing_entities:, **options)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param existing_entities [Object] The existing entities to find.
+      #
+      #   @option options [#to_proc] examples_on_success Extra examples to run
+      #     for the passing case.
+      #   @option options [Hash<String>] expected_value_on_success The expected
+      #     value for the passing result. Defaults to a Hash with the found
+      #     entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to an empty hash.
+      #
+      #   @yield Additional examples to run for the passing case.
+
+      contract do |existing_entities:, **options, &block|
+        include Cuprum::Rails::RSpec::Contracts::ActionContracts
+        include Cuprum::Rails::RSpec::Contracts::Actions::IndexContracts
+
+        # :nocov:
+        if options[:examples_on_success] && block
+          raise ArgumentError, 'provide either :examples_on_success or a block'
+        elsif block
+          options[:examples_on_success] = block
+        end
+        # :nocov:
+
+        include_contract 'should be a resource action'
+
+        include_contract 'should find the entities',
+          existing_entities: existing_entities,
+          expected_value:    options[:expected_value_on_success],
+          params:            options[:params],
+          &options[:examples_on_success]
+      end
+    end
+
+    # Contract asserting the action queries the repository for the entities.
+    module ShouldFindTheEntitiesContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, existing_entities:, **options)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param existing_entities [Object] The existing entities to find.
+      #
+      #   @option options [Hash<String>] expected_value The expected
+      #     value for the passing result. Defaults to a Hash with the found
+      #     entity.
+      #   @option options [Hash<String>] params The parameters used to build the
+      #     request. Defaults to an empty hash.
+      #
+      #   @yield Additional examples.
+
+      contract do |existing_entities:, **options, &block|
+        include Cuprum::Rails::RSpec::Contracts::ActionContracts
+
+        describe '#call' do
+          include Cuprum::Rails::RSpec::ContractHelpers
+
+          let(:request) do
+            Cuprum::Rails::Request.new(params: configured_params)
+          end
+          let(:configured_params) do
+            option_with_default(options[:params], default: {})
+          end
+          let(:configured_existing_entities) do
+            option_with_default(existing_entities)
+          end
+          let(:configured_expected_value) do
+            resource_name = configured_resource.name
+
+            option_with_default(
+              options[:expected_value],
+              default: {
+                resource_name => configured_existing_entities
+              }
+            )
+          end
+
+          it 'should return a passing result' do
+            expect(call_action)
+              .to be_a_passing_result
+              .with_value(configured_expected_value)
+          end
+
+          instance_exec(&block) if block
+        end
+      end
+    end
+  end
+end