clowne 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cb07a988be474d61f3bbf9360cfc4ab25de047be
-  data.tar.gz: 1a4763ae4bd1537ab0a254d4a0ebcb5ddd56930d
+SHA256:
+  metadata.gz: 616d875656dc9fa7ef815190a4281d5cac5ebd8d6ac471bd6b7292a139f78d8e
+  data.tar.gz: 35fd2f7681c3e13152ad98562737e6bac498c79e569f330a9986eba2e45302a2
 SHA512:
-  metadata.gz: 1ff3270acfabe0aebebfd272b3cb6eb27c9c7faea337fb59489898e008095d71dbfb835062e6c99c3b0fbc4b63e909073dd7e9e46231a6c3a0ecf5762f7204ef
-  data.tar.gz: 53e267bcb71f9283a64bb95df753e26b38058d5283c0b0b01276209fe6a27a07b3906cfbae881734875fca9a987e25fcbda6b3143f44956ef361102296821860
+  metadata.gz: 81734963c899011b5f518d817dddeb4fe761df3326ec2165b99b877212ec8de19100d9cb2cd5beccebab276c42f0c6e806d6385ce2f929982c3509641e6c58b9
+  data.tar.gz: e6fa4181b54efcd3a33e9be9dc5a9f569f324954d9d72d4cb95a253bc8c5b1386e30060c52f9f6434ee3c2f03dd2e9f86c0e21f254fab9725efd927c2d07dda9

data/.travis.yml

@@ -22,7 +22,7 @@ matrix:
   include:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
-    - rvm: jruby-9.1.0.0
+    - rvm: jruby-9.1.15.0
       gemfile: gemfiles/jruby.gemfile
     - rvm: 2.5.0
       gemfile: Gemfile
@@ -40,7 +40,7 @@ matrix:
   allow_failures:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
-    - rvm: jruby-9.1.0.0
+    - rvm: jruby-9.1.15.0
       gemfile: gemfiles/jruby.gemfile
 deploy:
   provider: pages

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change log
 
+## 0.2.0 (2018-02-21)
+
+- Add `Cloner#partial_apply` method. ([@palkan][])
+
+- Add RSpec matchers `clone_association` / `clone_associations`. ([@palkan][])
+
+- [[#15](https://github.com/palkan/clowne/issues/15)] Add control over nested params. ([@ssnickolay][])
+
 ## 0.1.0 (2018-02-01)
 
 - Add `init_as` declaration. ([@palkan][])

data/Gemfile

@@ -3,8 +3,12 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in clowne.gemspec
 gemspec
 
-gem 'pry-byebug'
-gem 'sqlite3'
+gem 'pry-byebug', platform: :mri
+
+gem 'sqlite3', platform: :mri
+gem 'activerecord-jdbcsqlite3-adapter', '~> 50.0', platform: :jruby
+gem 'jdbc-sqlite3', platform: :jruby
+
 gem 'activerecord', '>= 5.0'
 gem 'sequel', '>= 5.0'
 gem 'simplecov'

data/README.md

@@ -5,8 +5,6 @@
 
 # Clowne
 
-**NOTE**: this is the documentation for pre-release version **0.1.0.beta1**.
-
 A flexible gem for cloning your models. Clowne focuses on ease of use and provides the ability to connect various ORM adapters.
 
 <a href="https://evilmartians.com/">

data/docs/customization.md

@@ -12,9 +12,10 @@ Suppose that you want to add the `include_all` declaration to automagically incl
 First, you should add a custom declaration:
 
 ```ruby
-class IncludeAll # :nodoc: all
+# Extend from Base declaration
+class IncludeAll < Clowne::Declarations::Base # :nodoc: all
   def compile(plan)
-    # Just add all_associations object to plan
+    # Just add all_associations declaration (self) to plan
     plan.set(:all_associations, self)
   end
 end

data/docs/finalize.md

@@ -19,16 +19,16 @@ class UserCloner < Clowne::Cloner
   end
 end
 
-clone = UserCloner.call(user)
-clone.name
+cloned = UserCloner.call(user)
+cloned.name
 # => 'This is copy!'
-clone.email == 'clone@example.com'
+cloned.email == 'clone@example.com'
 # => false
 
-clone2 = UserCloner.call(user, traits: :change_email)
-clone2.name
+cloned2 = UserCloner.call(user, traits: :change_email)
+cloned2.name
 # => 'This is copy!'
-clone2.email
+cloned2.email
 # => 'clone@example.com'
 ```
 

data/docs/include_association.md

@@ -26,7 +26,7 @@ include_association name, scope, options
 ## Scope
 
 Scope can be a:
-- `Symbol` - named scope
+- `Symbol` - named scope.
 - `Proc` - custom scope (supports parameters).
 
 Example:
@@ -47,11 +47,11 @@ end
 
 class UserCloner < Clowne::Cloner
   include_association :accounts, :active
-  include_association :posts, ->(params) { where(state: params[:status]) if params[:status] }
+  include_association :posts, ->(params) { where(state: params[:state]) }
 end
 
 # Clone only draft posts
-UserCloner.call(user, status: :draft)
+UserCloner.call(user, state: :draft)
 # => <#User...
 ```
 
@@ -99,6 +99,10 @@ UserCloner.call(user)
 
 **NOTE**: if custom cloner is not defined, Clowne tries to infer the [implicit cloner](implicit_cloner.md).
 
+## Nested parameters
+
+Follow to [documentation page](parameters.md).
+
 ## Include multiple associations
 
 You can include multiple associations at once too:

data/docs/parameters.md

@@ -0,0 +1,114 @@
+---
+id: parameters
+title: Parameters
+---
+
+Clowne provides parameters for make your cloning logic more flexible. You can see their using in [`include_association`](include_association.md#scope) and [`finalize`](finalize.md) documentation pages.
+
+Example:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  include_association :posts, ->(params) { where(state: params[:state]) }
+
+  finalize do |_source, record, params|
+    record.email = params[:email]
+  end
+end
+
+cloned = UserCloner.call(user, state: :draft, email: 'cloned@example.com')
+cloned.email
+# => 'cloned@example.com'
+```
+
+## Potential Problems
+
+Clowne is born as a part of our big project and we use it for cloning really deep object relations. When we started to use params and forwarding them between parent-child cloners we got a nasty bugs.
+
+As result we strongly recommend to use ruby keyword arguments instead of params hash:
+
+```ruby
+# Bad
+finalize do |_source, record, params|
+  record.email = params[:email]
+end
+
+# Good
+finalize do |_source, record, email:, **|
+  record.email = email
+end
+```
+
+## Nested Parameters
+
+Also we implemented control over the parameters for cloning associations (you can read more [here](https://github.com/palkan/clowne/issues/15)).
+
+Let's explain what the difference:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  # Don't pass parameters to associations
+  trait :default do
+    include_association :profile
+    # equal to include_association :profile, params: false
+  end
+
+  # Pass all parameters to associations
+  trait :params_true do
+    include_association :profile, params: true
+  end
+
+  # Filter parameters by key.
+  # Notice: value by key must be a Hash.
+
+  trait :by_key do
+    include_association :profile, params: :profile
+  end
+
+  # Execute custom block with params as argument
+  trait :by_block do
+    include_association :profile, params: Proc.new do |params|
+      params[:profile].map { |k, v| [k, v.upcase] }.to_h
+    end
+  end
+
+  # Execute custom block with params and parent record as arguments
+  trait :by_block_with_parent do
+    include_association :profile, params: Proc.new do |params, user|
+      {
+        name: params[:profile][:name],
+        email: user.email
+      }
+    end
+  end
+end
+
+class ProfileCloner < Clowne::Cloner
+  finalize do |_source, record, params|
+    record.jsonb_field = params
+  end
+end
+
+# Execute:
+
+def get_profile_jsonb(user, trait)
+  params = { profile: { name: 'John', surname: 'Cena' } }
+  cloned = UserCloner.call(user, traits: trait, **params)
+  cloned.profile.jsonb_field
+end
+
+get_profile_jsonb(user, :default)
+# => {}
+
+get_profile_jsonb(user, :params_true)
+# => { profile: { name: 'John', surname: 'Cena' } }
+
+get_profile_jsonb(user, :by_key)
+# => { name: 'John', surname: 'Cena' }
+
+get_profile_jsonb(user, :by_block)
+# => { name: 'JOHN', surname: 'CENA' }
+
+get_profile_jsonb(user, :by_block_with_parent)
+# => { name: 'JOHN', email: user.email }
+```

data/docs/testing.md

@@ -0,0 +1,195 @@
+---
+id: testing
+title: Testing
+---
+
+Clowne provides specific tools to help you test your cloners.
+
+The main goal is to make it possible to test different cloning phases separately and avoid _heavy_ tests setup phases.
+
+Let's consider the following models and cloners:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_one :profile
+  has_many :posts
+end
+
+# app/models/post.rb
+class Post < ApplicationRecord
+  has_many :comments
+  has_many :votes
+
+  scope :draft, -> { where(draft: true) }
+end
+
+# app/cloners/user_cloner.rb
+class UserCloner < Clowne::Cloner
+  class ProfileCloner
+    nullify :rating
+  end
+
+  include_association :profile, clone_with: ProfileCloner
+
+  nullify :email
+
+  finalize do |_, record, name: nil, **|
+    record.name = name unless name.nil?
+  end
+
+  trait :copy do
+    init_as do |user, target:, **|
+      # copy name
+      target.name = user.name
+      target
+    end
+  end
+
+  trait :with_posts do
+    include_association :posts, :draft, traits: :mark_as_copy
+  end
+
+  trait :with_popular_posts do
+    include_association :posts, (lambda do |params|
+      where('rating > ?', params[:min_rating])
+    end)
+  end
+end
+
+# app/cloners/post_cloner.rb
+class PostCloner < Clowne::Cloner
+  include_association :comments
+
+  trait :mark_as_copy do |_, record|
+    record.title += ' (copy)'
+  end
+end
+```
+
+## Getting started
+
+Currently, only [RSpec](http://rspec.info/) is supported.
+
+Add this line to your `spec_helper.rb` (or `rails_helper.rb`):
+
+```ruby
+require 'clowne/rspec'
+```
+
+## Configuration matchers
+
+There are several matchers that allow you to verify the cloner configuration.
+
+### `clone_associations`
+
+This matcher vefifies that your cloner includes the specified associations:
+
+```ruby
+# spec/cloners/user_cloner_spec.rb
+RSpec.describe UserCloner, type: :cloner do
+  subject { described_class }
+
+  specify do
+    # checks that only the specified associations is included
+    is_expected.to clone_associations(:profile)
+
+    # with traits
+    is_expected.to clone_associations(:profile, :posts)
+      .with_traits(:with_posts)
+
+    # raises when there are some unspecified associations
+    is_expected.to clone_associations(:profile)
+      .with_traits(:with_posts)
+    #=> raises RSpec::Expectations::ExpectationNotMetError
+  end
+end
+```
+
+### `clone_association`
+
+This matcher allows to verify the specified association options:
+
+```ruby
+# spec/cloners/user_cloner_spec.rb
+RSpec.describe UserCloner, type: :cloner do
+  subject { described_class }
+
+  specify do
+    # simply check that association is included
+    is_expected.to clone_association(:profile)
+
+    # check options
+    is_expected.to clone_association(
+      :profile,
+      clone_with: described_class::ProfileCloner
+    )
+
+    # with traits, scope and activated trait
+    is_expected.to clone_association(
+      :posts,
+      traits: :mark_as_copy,
+      scope: :draft
+    ).with_traits(:with_posts)
+  end
+end
+```
+
+**NOTE:** `clone_associations`/`clone_association` matchers are only available in groups marked with `type: :cloner` tag.
+
+Clowne automaticaly marks all specs in `spec/cloners` folder with `type: :cloner`. Otherwise you have to add this tag you.
+
+
+## Clone actions matchers
+
+Under the hood, Clowne builds a [compilation plan](architecture.md) which is used to clone the record.
+
+Plan is a set of _actions_ (such as `nullify`, `finalize`, `association`, `init_as`) which are applied to the record.
+
+Most of the time these actions don't depend on each other, thus we can test them separately:
+
+```ruby
+# spec/cloners/user_cloner_spec.rb
+RSpec.describe UserCloner, type: :cloner do
+  subject(:user) { create :user, name: 'Bombon' }
+
+  specify 'simple case' do
+    # apply only the specified part of the plan
+    cloned_user = described_class.partial_apply(:nullify, user)
+    expect(cloned_user.email).to be_nil
+    # finalize wasn't applied
+    expect(cloned_user.name).to eq 'Bombon'
+  end
+
+  specify 'with params' do
+    cloned_user = described_class.partial_apply(:finalize, user, name: 'new name')
+    # nullify actions were not applied!
+    expect(cloned_user.email).to eq user.email
+    # finalize was applied
+    expect(cloned_user.name).to eq 'new name'
+  end
+
+  specify 'with traits' do
+    a_user = create(:user, name: 'Dindon')
+    cloned_user = described_class.partial_apply(:init_as, user, traits: :copy, target: a_user)
+    # returned user is the same as target
+    expect(cloned_user).to be_eql(a_user)
+    expect(cloned_user.name).to eq 'Bombon'
+  end
+
+  specify 'associations' do
+    create(:post, user: user, rating: 1, text: 'Boom Boom')
+    create(:post, user: user, rating: 2, text: 'Flying Dumplings')
+
+    # you can specify which associations to include (you can use array)
+    # to apply all associations write:
+    #   plan.apply(:association)
+    cloned_user = described_class.partial_apply(
+      'association.posts', user, traits: :with_popular_posts, min_rating: 1
+    )
+
+    expect(cloned_user.posts.size).to eq 1
+    expect(cloned_user.posts.first.text).to eq 'Flying Dumplings'
+  end
+end
+```

data/docs/web/i18n/en.json

@@ -22,8 +22,10 @@
     "installation": "Installation",
     "nullify": "Nullify Attributes",
     "Nullify": "Nullify",
+    "parameters": "Parameters",
     "sequel": "Sequel",
     "supported_adapters": "Supported Adapters",
+    "testing": "Testing",
     "traits": "Traits",
     "HISTORY": "HISTORY",
     "README": "README",

data/docs/web/sidebars.json

@@ -13,6 +13,7 @@
       "finalize",
       "init_as",
       "traits",
+      "parameters",
       "execution_order"
     ],
     "Adapters": [

data/lib/clowne/adapters/base/association.rb

@@ -17,7 +17,7 @@ module Clowne
           @params = params
           @association_name = declaration.name.to_s
           @reflection = reflection
-          @cloner_options = params
+          @cloner_options = declaration.params_proxy.permit(params: params, parent: source)
           @cloner_options.merge!(traits: declaration.traits) if declaration.traits
         end
 

data/lib/clowne/adapters/base/init_as.rb

@@ -6,7 +6,7 @@ module Clowne
       module InitAs # :nodoc: all
         # rubocop: disable Metrics/ParameterLists
         def self.call(source, _record, declaration, params:, adapter:, **_options)
-          adapter.init_record(declaration.block.call(source, params))
+          adapter.init_record(declaration.block.call(source, **params))
         end
         # rubocop: enable Metrics/ParameterLists
       end

data/lib/clowne/cloner.rb

@@ -2,6 +2,7 @@
 
 require 'clowne/planner'
 require 'clowne/dsl'
+require 'clowne/params'
 
 module Clowne # :nodoc: all
   class UnprocessableSourceError < StandardError; end
@@ -47,6 +48,8 @@ module Clowne # :nodoc: all
 
         traits = options.delete(:traits)
 
+        only = options.delete(:clowne_only_actions)
+
         traits = Array(traits) unless traits.nil?
 
         plan =
@@ -58,9 +61,15 @@ module Clowne # :nodoc: all
 
         plan = Clowne::Planner.enhance(plan, Proc.new) if block_given?
 
+        plan = Clowne::Planner.filter_declarations(plan, only)
+
         adapter.clone(object, plan, params: options)
       end
 
+      def partial_apply(only, *args, **hargs)
+        call(*args, **hargs, clowne_only_actions: prepare_only(only))
+      end
+
       # rubocop: enable Metrics/AbcSize, Metrics/MethodLength
       # rubocop: enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
@@ -88,6 +97,18 @@ module Clowne # :nodoc: all
         return @traits_plans if instance_variable_defined?(:@traits_plans)
         @traits_plans = {}
       end
+
+      def prepare_only(val)
+        val = Array.wrap(val)
+        val.each_with_object({}) do |type, acc|
+          # type is a Symbol or Hash
+          if type.is_a?(Hash)
+            acc.merge!(type)
+          elsif type.is_a?(Symbol)
+            acc[type] = nil
+          end
+        end
+      end
     end
   end
 end

data/lib/clowne/declarations.rb

@@ -23,6 +23,7 @@ module Clowne
   end
 end
 
+require 'clowne/declarations/base'
 require 'clowne/declarations/init_as'
 require 'clowne/declarations/exclude_association'
 require 'clowne/declarations/finalize'

data/lib/clowne/declarations/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Clowne
+  module Declarations
+    class Base # :nodoc: all
+      # Used with partial_apply.
+      # By default match everything
+      def matches?(_)
+        true
+      end
+    end
+  end
+end

data/lib/clowne/declarations/exclude_association.rb

@@ -2,7 +2,7 @@
 
 module Clowne
   module Declarations
-    class ExcludeAssociation # :nodoc: all
+    class ExcludeAssociation < Base # :nodoc: all
       attr_accessor :name
 
       def initialize(name)

data/lib/clowne/declarations/finalize.rb

@@ -2,7 +2,7 @@
 
 module Clowne
   module Declarations
-    class Finalize # :nodoc: all
+    class Finalize < Base # :nodoc: all
       attr_reader :block
 
       def initialize

data/lib/clowne/declarations/include_association.rb

@@ -4,7 +4,7 @@ require 'clowne/ext/string_constantize'
 
 module Clowne
   module Declarations
-    class IncludeAssociation # :nodoc: all
+    class IncludeAssociation < Base # :nodoc: all
       using Clowne::Ext::StringConstantize
 
       attr_accessor :name, :scope, :options
@@ -19,6 +19,19 @@ module Clowne
         plan.add_to(:association, name, self)
       end
 
+      def matches?(names)
+        names = Array(names)
+        names.include?(name)
+      end
+
+      def params_proxy
+        @_params_proxy ||= Clowne::Params.proxy(options[:params])
+      end
+
+      def params
+        options[:params]
+      end
+
       def clone_with
         return @clone_with if instance_variable_defined?(:@clone_with)
         @clone_with =

data/lib/clowne/declarations/init_as.rb

@@ -2,7 +2,7 @@
 
 module Clowne
   module Declarations
-    class InitAs # :nodoc: all
+    class InitAs < Base # :nodoc: all
       attr_reader :block
 
       def initialize

data/lib/clowne/declarations/nullify.rb

@@ -2,7 +2,7 @@
 
 module Clowne
   module Declarations
-    class Nullify # :nodoc: all
+    class Nullify < Base # :nodoc: all
       attr_reader :attributes
 
       def initialize(*attributes)

data/lib/clowne/ext/lambda_as_proc.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Clowne
+  module Ext
+    # Add to_proc method for lambda
+    module LambdaAsProc
+      refine Proc do
+        def to_proc
+          return self unless lambda?
+          this = self
+          proc { |*args| this.call(*args.take(this.arity)) }
+        end
+      end
+    end
+  end
+end

data/lib/clowne/ext/string_constantize.rb

@@ -13,8 +13,14 @@ module Clowne
           # Remove the first blank element in case of '::ClassName' notation.
           names.shift if names.size > 1 && names.first.empty?
 
-          names.inject(Object) do |constant, name|
-            constant.const_get(name) if constant.const_defined?(name)
+          begin
+            names.inject(Object) do |constant, name|
+              constant.const_get(name)
+            end
+          # rescue instead of const_defined? allow us to use
+          # Rails const autoloading (aka patched const_get)
+          rescue NameError
+            nil
           end
         end
       end

data/lib/clowne/params.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'clowne/ext/lambda_as_proc'
+
+module Clowne
+  class Params # :nodoc: all
+    class BaseProxy
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      def permit(_params)
+        raise NotImplementedError
+      end
+    end
+
+    class PassProxy < BaseProxy
+      def permit(params:, **)
+        params
+      end
+    end
+
+    class NullProxy < BaseProxy
+      def permit(_params)
+        {}
+      end
+    end
+
+    class BlockProxy < BaseProxy
+      using Clowne::Ext::LambdaAsProc
+
+      def permit(params:, parent:)
+        value.to_proc.call(params, parent)
+      end
+    end
+
+    class KeyProxy < BaseProxy
+      def permit(params:, **)
+        nested_params = params.fetch(value)
+        return nested_params if nested_params.is_a?(Hash)
+
+        raise KeyError, "value by key '#{value}' must be a Hash"
+      end
+    end
+
+    class << self
+      def proxy(value)
+        if value == true
+          PassProxy
+        elsif value.nil? || value == false
+          NullProxy
+        elsif value.is_a?(Proc)
+          BlockProxy
+        else
+          KeyProxy
+        end.new(value)
+      end
+    end
+  end
+end

data/lib/clowne/plan.rb

@@ -56,14 +56,16 @@ module Clowne
       data[type].delete(id)
     end
 
-    def declarations
-      registry.actions.flat_map do |type|
-        value = data[type]
-        next if value.nil?
-        value = value.values if value.is_a?(TwoPhaseSet)
-        value = Array(value)
-        value.map { |v| [type, v] }
-      end.compact
+    def declarations(reload = false)
+      return @declarations if !reload && instance_variable_defined?(:@declarations)
+      @declarations =
+        registry.actions.flat_map do |type|
+          value = data[type]
+          next if value.nil?
+          value = value.values if value.is_a?(TwoPhaseSet)
+          value = Array(value)
+          value.map { |v| [type, v] }
+        end.compact
     end
 
     def dup

data/lib/clowne/planner.rb

@@ -26,6 +26,16 @@ module Clowne
         end
       end
 
+      def filter_declarations(plan, only)
+        return plan if only.nil?
+
+        plan.dup.tap do |new_plan|
+          new_plan.declarations.reject! do |(type, declaration)|
+            !only.key?(type) || !declaration.matches?(only[type])
+          end
+        end
+      end
+
       private
 
       def compile_traits(cloner, traits)

data/lib/clowne/rspec.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'clowne/rspec/helpers'
+require 'clowne/rspec/clone_associations'
+require 'clowne/rspec/clone_association'

data/lib/clowne/rspec/clone_association.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Clowne
+  module RSpec
+    module Matchers # :nodoc: all
+      class CloneAssociation < ::RSpec::Matchers::BuiltIn::BaseMatcher
+        include Clowne::RSpec::Helpers
+
+        AVAILABLE_PARAMS = %i[
+          traits
+          clone_with
+          params
+          scope
+        ].freeze
+
+        attr_reader :expected_params
+
+        def initialize(name, options)
+          @expected = name
+          extract_options! options
+        end
+
+        # rubocop: disable Metrics/AbcSize
+        def match(expected, _actual)
+          @actual = plan.declarations
+                        .find { |key, decl| key == :association && decl.name == expected }
+
+          return false if @actual.nil?
+
+          @actual = actual.last
+
+          AVAILABLE_PARAMS.each do |param|
+            if expected_params[param] != UNDEFINED
+              return false if expected_params[param] != actual.send(param)
+            end
+          end
+
+          true
+        end
+        # rubocop: enable Metrics/AbcSize
+
+        def does_not_match?(*)
+          raise "This matcher doesn't support negation"
+        end
+
+        def failure_message
+          if @actual.nil?
+            "expected to include association #{expected}, but none found"
+          else
+            params_failure_message
+          end
+        end
+
+        private
+
+        def extract_options!(options)
+          @expected_params = {}
+
+          AVAILABLE_PARAMS.each do |param|
+            expected_params[param] = options.fetch(param, UNDEFINED)
+          end
+
+          raise ArgumentError, 'Lambda scope is not supported' if
+            expected_params[:scope].is_a?(Proc)
+
+          raise ArgumentError, 'Lambda params is not supported' if
+            expected_params[:params].is_a?(Proc)
+        end
+
+        def params_failure_message
+          "expected :#{@expected} association " \
+          "to have options #{formatted_expected_params}, " \
+          "but got #{formatted_actual_params}"
+        end
+
+        def formatted_expected_params
+          ::RSpec::Support::ObjectFormatter.format(
+            expected_params.reject { |_, v| v == UNDEFINED }
+          )
+        end
+
+        def formatted_actual_params
+          actual_params = AVAILABLE_PARAMS.each_with_object({}) do |key, acc|
+            acc[key] = actual.send(key)
+          end
+          ::RSpec::Support::ObjectFormatter.format(actual_params)
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include(Module.new do
+    def clone_association(expected, **options)
+      Clowne::RSpec::Matchers::CloneAssociation.new(expected, options)
+    end
+  end, type: :cloner)
+end

data/lib/clowne/rspec/clone_associations.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Clowne
+  module RSpec
+    module Matchers # :nodoc: all
+      # `clone_associations` matcher is just an extension of `contain_exactly` matcher
+      class CloneAssociations < ::RSpec::Matchers::BuiltIn::ContainExactly
+        include Clowne::RSpec::Helpers
+
+        def convert_actual_to_an_array
+          @actual = plan.declarations
+                        .select { |key, _| key == :association }
+                        .map { |_, decl| decl.name }
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include(Module.new do
+    def clone_associations(*expected)
+      Clowne::RSpec::Matchers::CloneAssociations.new(expected)
+    end
+  end, type: :cloner)
+end

data/lib/clowne/rspec/helpers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Clowne
+  module RSpec
+    module Helpers # :nodoc: all
+      attr_reader :cloner
+
+      def with_traits(*traits)
+        @traits = traits
+        self
+      end
+
+      def matches?(actual)
+        raise ArgumentError, non_cloner_message unless actual <= ::Clowne::Cloner
+        @cloner = actual
+        super
+      end
+
+      def plan
+        @plan ||=
+          if @traits.nil?
+            cloner.default_plan
+          else
+            cloner.plan_with_traits(@traits)
+          end
+      end
+
+      def non_cloner_message
+        'expected a cloner to be passed to `expect(...)`, ' \
+        "but got #{actual_formatted}"
+      end
+    end
+  end
+end

data/lib/clowne/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clowne
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clowne
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vladimir Dementyev
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-01 00:00:00.000000000 Z
+date: 2018-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -134,8 +134,10 @@ files:
 - docs/inline_configuration.md
 - docs/installation.md
 - docs/nullify.md
+- docs/parameters.md
 - docs/sequel.md
 - docs/supported_adapters.md
+- docs/testing.md
 - docs/traits.md
 - docs/web/.gitignore
 - docs/web/core/Footer.js
@@ -184,6 +186,7 @@ files:
 - lib/clowne/adapters/sequel/record_wrapper.rb
 - lib/clowne/cloner.rb
 - lib/clowne/declarations.rb
+- lib/clowne/declarations/base.rb
 - lib/clowne/declarations/exclude_association.rb
 - lib/clowne/declarations/finalize.rb
 - lib/clowne/declarations/include_association.rb
@@ -191,10 +194,16 @@ files:
 - lib/clowne/declarations/nullify.rb
 - lib/clowne/declarations/trait.rb
 - lib/clowne/dsl.rb
+- lib/clowne/ext/lambda_as_proc.rb
 - lib/clowne/ext/orm_ext.rb
 - lib/clowne/ext/string_constantize.rb
+- lib/clowne/params.rb
 - lib/clowne/plan.rb
 - lib/clowne/planner.rb
+- lib/clowne/rspec.rb
+- lib/clowne/rspec/clone_association.rb
+- lib/clowne/rspec/clone_associations.rb
+- lib/clowne/rspec/helpers.rb
 - lib/clowne/version.rb
 homepage: https://github.com/palkan/clowne
 licenses:
@@ -216,7 +225,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.4
 signing_key: 
 specification_version: 4
 summary: A flexible gem for cloning your models.