RubyGems - clowne - Versions diffs - 0.1.0 → 1.3.0 - Mend

clowne 0.1.0 → 1.3.0

Files changed (125) hide show

checksums.yaml +5 -5
data/.rubocop.yml +11 -45
data/.travis.yml +14 -21
data/CHANGELOG.md +30 -0
data/Gemfile +11 -7
data/README.md +38 -18
data/Rakefile +3 -3
data/clowne.gemspec +17 -10
data/docs/.nojekyll +0 -0
data/docs/.rubocop.yml +8 -2
data/docs/CNAME +1 -0
data/docs/README.md +131 -0
data/docs/_sidebar.md +25 -0
data/docs/active_record.md +4 -7
data/docs/after_clone.md +53 -0
data/docs/after_persist.md +77 -0
data/docs/architecture.md +2 -5
data/docs/assets/docsify.min.js +1 -0
data/docs/assets/prism-ruby.min.js +1 -0
data/docs/assets/styles.css +348 -0
data/docs/assets/vue.css +1 -0
data/docs/clone_mapper.md +59 -0
data/docs/customization.md +6 -7
data/docs/exclude_association.md +6 -8
data/docs/finalize.md +11 -15
data/docs/from_v02_to_v1.md +83 -0
data/docs/getting_started.md +171 -0
data/docs/implicit_cloner.md +2 -5
data/docs/include_association.md +24 -10
data/docs/index.html +29 -0
data/docs/init_as.md +13 -9
data/docs/inline_configuration.md +5 -6
data/docs/nullify.md +3 -7
data/docs/operation.md +55 -0
data/docs/parameters.md +112 -0
data/docs/sequel.md +16 -22
data/docs/supported_adapters.md +3 -6
data/docs/testing.md +194 -0
data/docs/traits.md +1 -4
data/gemfiles/activerecord42.gemfile +7 -5
data/gemfiles/jruby.gemfile +8 -6
data/gemfiles/railsmaster.gemfile +8 -6
data/lib/clowne.rb +12 -9
data/lib/clowne/adapters/active_record.rb +4 -5
data/lib/clowne/adapters/active_record/associations.rb +8 -6
data/lib/clowne/adapters/active_record/associations/base.rb +1 -5
data/lib/clowne/adapters/active_record/associations/belongs_to.rb +29 -0
data/lib/clowne/adapters/active_record/associations/has_one.rb +3 -2
data/lib/clowne/adapters/active_record/dsl.rb +2 -2
data/lib/clowne/adapters/active_record/resolvers/association.rb +38 -0
data/lib/clowne/adapters/base.rb +49 -44
data/lib/clowne/adapters/base/association.rb +24 -15
data/lib/clowne/adapters/registry.rb +49 -0
data/lib/clowne/adapters/sequel.rb +14 -10
data/lib/clowne/adapters/sequel/associations.rb +6 -6
data/lib/clowne/adapters/sequel/associations/base.rb +9 -5
data/lib/clowne/adapters/sequel/associations/many_to_many.rb +6 -2
data/lib/clowne/adapters/sequel/associations/one_to_many.rb +7 -2
data/lib/clowne/adapters/sequel/associations/one_to_one.rb +7 -2
data/lib/clowne/adapters/sequel/operation.rb +35 -0
data/lib/clowne/adapters/sequel/record_wrapper.rb +0 -16
data/lib/clowne/adapters/sequel/resolvers/after_persist.rb +22 -0
data/lib/clowne/adapters/sequel/resolvers/association.rb +51 -0
data/lib/clowne/adapters/sequel/specifications/after_persist_does_not_support.rb +15 -0
data/lib/clowne/cloner.rb +49 -21
data/lib/clowne/declarations.rb +15 -12
data/lib/clowne/declarations/after_clone.rb +21 -0
data/lib/clowne/declarations/after_persist.rb +21 -0
data/lib/clowne/declarations/base.rb +13 -0
data/lib/clowne/declarations/exclude_association.rb +2 -2
data/lib/clowne/declarations/finalize.rb +5 -4
data/lib/clowne/declarations/include_association.rb +16 -2
data/lib/clowne/declarations/init_as.rb +5 -4
data/lib/clowne/declarations/nullify.rb +4 -3
data/lib/clowne/declarations/trait.rb +1 -0
data/lib/clowne/dsl.rb +9 -0
data/lib/clowne/ext/lambda_as_proc.rb +17 -0
data/lib/clowne/ext/orm_ext.rb +1 -1
data/lib/clowne/ext/record_key.rb +12 -0
data/lib/clowne/ext/string_constantize.rb +9 -3
data/lib/clowne/ext/yield_self_then.rb +25 -0
data/lib/clowne/planner.rb +16 -3
data/lib/clowne/resolvers/after_clone.rb +17 -0
data/lib/clowne/resolvers/after_persist.rb +18 -0
data/lib/clowne/resolvers/finalize.rb +12 -0
data/lib/clowne/resolvers/init_as.rb +13 -0
data/lib/clowne/resolvers/nullify.rb +15 -0
data/lib/clowne/rspec.rb +5 -0
data/lib/clowne/rspec/clone_association.rb +99 -0
data/lib/clowne/rspec/clone_associations.rb +26 -0
data/lib/clowne/rspec/helpers.rb +35 -0
data/lib/clowne/utils/clone_mapper.rb +26 -0
data/lib/clowne/utils/operation.rb +95 -0
data/lib/clowne/utils/options.rb +39 -0
data/lib/clowne/utils/params.rb +64 -0
data/lib/clowne/utils/plan.rb +90 -0
data/lib/clowne/version.rb +1 -1
metadata +99 -45
data/docs/alternatives.md +0 -26
data/docs/basic_example.md +0 -66
data/docs/configuration.md +0 -29
data/docs/execution_order.md +0 -14
data/docs/installation.md +0 -16
data/docs/web/.gitignore +0 -11
data/docs/web/core/Footer.js +0 -92
data/docs/web/i18n/en.json +0 -134
data/docs/web/package.json +0 -14
data/docs/web/pages/en/help.js +0 -50
data/docs/web/pages/en/index.js +0 -231
data/docs/web/pages/en/users.js +0 -47
data/docs/web/sidebars.json +0 -30
data/docs/web/siteConfig.js +0 -44
data/docs/web/static/css/custom.css +0 -229
data/docs/web/static/fonts/FiraCode-Medium.woff +0 -0
data/docs/web/static/fonts/FiraCode-Regular.woff +0 -0
data/docs/web/static/fonts/StemText.woff +0 -0
data/docs/web/static/fonts/StemTextBold.woff +0 -0
data/docs/web/static/img/favicon/favicon.ico +0 -0
data/docs/web/yarn.lock +0 -1741
data/lib/clowne/adapters/active_record/association.rb +0 -34
data/lib/clowne/adapters/base/finalize.rb +0 -19
data/lib/clowne/adapters/base/init_as.rb +0 -21
data/lib/clowne/adapters/base/nullify.rb +0 -19
data/lib/clowne/adapters/sequel/association.rb +0 -47
data/lib/clowne/plan.rb +0 -81

data/docs/include_association.md CHANGED Viewed

@@ -1,7 +1,4 @@
----
-id: include_association
-title: Include Association
----
+# Include Association
 Use this declaration to clone model's associations:
@@ -23,10 +20,17 @@ The declaration supports additional arguments:
 include_association name, scope, options
 ```
+### Supported Associations
+Adapter                                   |1:1         |*:1         | 1:M         | M:M                     |
+------------------------------------------|------------|------------|-------------|-------------------------|
+[Active Record](active_record)  | has_one    | belongs_to | has_many    | has_and_belongs_to|
+[Sequel](sequel)                | one_to_one | -          | one_to_many | many_to_many     |
 ## Scope
 Scope can be a:
-- `Symbol` - named scope
+- `Symbol` - named scope.
 - `Proc` - custom scope (supports parameters).
 Example:
@@ -47,12 +51,12 @@ 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)
-# => <#User...
+UserCloner.call(user, state: :draft).to_record
+# => <#User id: nil, ... >
 ```
 ## Options
@@ -93,12 +97,16 @@ class UserCloner < Clowne::Cloner
   # include_association :posts, clone_with: PostSpecialCloner, traits: :with_tags
 end
-UserCloner.call(user)
-# => <#User...
+UserCloner.call(user).to_record
+# => <#User id: nil, ... >
 ```
 **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:
@@ -117,3 +125,9 @@ end
 ```
 **NOTE:** in that case, it's not possible to provide custom scopes and options.
+### Belongs To association
+You can include belongs_to association, but will do it carefully.
+If you have loop by relations in your models, when you clone it will raise SystemStackError.
+Check this [test](https://github.com/palkan/clowne/blob/master/spec/clowne/integrations/active_record_belongs_to_spec.rb) for instance.

data/docs/index.html ADDED Viewed

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="assets/vue.css">
+  <link rel="stylesheet" href="assets/styles.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'Clowne',
+      repo: 'https://github.com/clowne-rb/clowne',
+      loadSidebar: true,
+      subMaxLevel: 2,
+      auto2top: true,
+      search: {
+        namespace: 'clowne'
+      }
+    }
+  </script>
+  <script src="assets/docsify.min.js"></script>
+  <script src="assets/prism-ruby.min.js"></script>
+</body>
+</html>

data/docs/init_as.md CHANGED Viewed

@@ -1,8 +1,4 @@
----
-id: init_as
-title: Initialize Cloning Target
-sidebar_label: Init As
----
+# Initialize Cloning Target
 You can override the default Clowne method which generates a _plain_ copy of a source object.
 By default, Clowne initiates the cloned record using a `#dup` method.
@@ -27,10 +23,18 @@ class UserCloner < Clowne::Cloner
   end
 end
-jack = User.find_by(email: 'jack@evl.ms')
-john = User.find_by(email: 'john@evl.ms')
+jack = User.find_by(email: "jack@evl.ms")
+# => <#User id: 1, ...>
+jack.create_profile(name: "Jack")
+# => <#Profile id: 1, name: 'Jack', ...>
-# we want to clone Jack's profile settings to another user,
+john = User.find_by(email: "john@evl.ms")
+# => <#User id: 2, ...>
+# we want to clone Jack's profile to John's user,
 # without creating a new one
-UserCloner.call(jack, traits: :copy_settings, target: john)
+john_with_profile = UserCloner.call(jack, traits: :copy_settings, target: john).to_record
+# => <#User id: 2, ...>
+john_with_profile.profile
+#=> <#Profile id: nil, name: 'Jack',...>
 ```

data/docs/inline_configuration.md CHANGED Viewed

@@ -1,12 +1,9 @@
----
-id: inline_configuration
-title: Inline Configuration
----
+# Inline Configuration
 You can also enhance the cloner configuration inline (i.e., add declarations dynamically):
 ```ruby
-cloned = UserCloner.call(User.last) do
+operation = UserCloner.call(User.last) do
   exclude_association :profile
   finalize do |source, record|
@@ -14,6 +11,8 @@ cloned = UserCloner.call(User.last) do
   end
 end
+cloned = operation.to_record
 cloned.email
 # => "clone_of_john@example.com"
@@ -31,7 +30,7 @@ Thus it's also possible to clone objects without any cloner classes at all by us
 ```ruby
 cloned = Clowne::Cloner.call(user) do
   # anything you want!
-end
+end.to_record
 cloned
 # => <#User..

data/docs/nullify.md CHANGED Viewed

@@ -1,8 +1,4 @@
----
-id: nullify
-title: Nullify Attributes
-sidebar_label: Nullify
----
+# Nullify Attributes
 To set a bunch of attributes to `nil` you can use the `nullify` declaration:
@@ -21,7 +17,7 @@ class UserCloner < Clowne::Cloner
   end
 end
-clone = UserCloner.call(user)
+clone = UserCloner.call(user).to_record
 clone.name.nil?
 # => true
 clone.email.nil?
@@ -29,7 +25,7 @@ clone.email.nil?
 clone.surname.nil?
 # => false
-clone2 = UserCloner.call(user, traits: :nullify_surname)
+clone2 = UserCloner.call(user, traits: :nullify_surname).to_record
 clone2.name.nil?
 # => true
 clone2.surname.nil?

data/docs/operation.md ADDED Viewed

@@ -0,0 +1,55 @@
+# Operation
+Since version 1.0 Clowne has been returning specific result object instead of a raw cloned object. It has allowed unifying interface between adapters and has opened an opportunity to implement new features. We call this object `Operation`.
+An instance of `Operation` has a very clear interface:
+```ruby
+class User < ActiveRecord::Base; end
+class UserCloner < Clowne::Cloner
+  nullify :email
+  after_persist do |_origin, cloned, **|
+    cloned.update(email: "evl-#{cloned.id}.ms")
+  end
+end
+user = User.create(email: "evl.ms")
+# => <#User id: 1, email: 'evl.ms', ...>
+operation = UserCloner.call(user)
+# Return resulted (non saved) object:
+operation.to_record
+# => <#User id: nil, email: nil, ...>
+# Save cloned object and call after_persist callbacks:
+operation.persist # or operation.persist!
+# => true
+operation.to_record
+# => <#User id: 2, email: 'evl-2.ms', ...>
+# Call only after_persist callbacks:
+user2 = operation.to_record
+# => <#User id: 2, email: 'evl-2.ms', ...>
+user2.update(email: "admin@example.com")
+# => <#User id: 2, email: 'admin@example.com' ...>
+operation.run_after_persist
+# => <#User id: 2, email: 'evl-2.ms', ...>
+```
+The last example is weird, but it can be helpful when you need to execute `save` (or `save!`) separately from `after_persist` callbacks:
+```ruby
+operation = UserClone.call(user)
+# Wrap main cloning into the transaction
+ActiveRecord::Base.transaction do
+  operation.to_record.save!
+end
+# And after that execute after_persist without transaction
+operation.run_after_persist
+```

data/docs/parameters.md ADDED Viewed

@@ -0,0 +1,112 @@
+# 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
+operation = UserCloner.call(user, state: :draft, email: "cloned@example.com")
+cloned = operation.to_record
+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/clowne-rb/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 :all_params 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).to_record
+  cloned.profile.jsonb_field
+end
+get_profile_jsonb(user, :default)
+# => {}
+get_profile_jsonb(user, :all_params)
+# => { 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/sequel.md CHANGED Viewed

@@ -1,11 +1,6 @@
----
-id: sequel
-title: Sequel
----
+# Sequel
-Clowne uses Sequel [`NestedAttributes` plugin](http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/NestedAttributes.html) for cloning source's associations and you need to configure it.
-Also, Sequel target record wrapped into a special class for implementation full Clowne's behavior. You need to use method `to_model` for getting final cloned `Sequel::Model` object (or you can use `save` for saving the cloned object to DB).
+Under the hood, Clowne uses Sequel [`NestedAttributes` plugin](http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/NestedAttributes.html) for cloning source's associations, and you need to configure it.
 Example:
@@ -29,13 +24,11 @@ and get cloned user
 ```ruby
 user = User.last
-wrapper = UserCloner.call(user)
-wrapper.class
-# => Clowne::Adapters::Sequel::RecordWrapper
-cloned_record = wrapper.to_model
-cloned_record.class
-# => User
-cloned_record.new?
+operation = UserCloner.call(user)
+# => <#Clowne::Adapters::Sequel::Operation...>
+cloned = operation.to_record
+# => <#User id: nil, ...>
+cloned.new?
 # => true
 ```
@@ -43,14 +36,15 @@ or you can save it immediately
 ```ruby
 user = User.last
-wrapper = UserCloner.call(user)
-wrapper.class
-# => Clowne::Adapters::Sequel::RecordWrapper
-cloned_record = wrapper.save
-cloned_record.class
-# => User
-cloned_record.new?
+# => <#User id: 1, ...>
+operation = UserCloner.call(user)
+# => <#Clowne::Adapters::Sequel::Operation...>
+operation.persist
+# => true
+cloned = operation.to_record
+# => <#User id: 2, ...>
+cloned.new?
 # => false
 ```
-If you try to clone associations without `NestedAttributes` plugin, Clowne will skip this declaration.
+If you try to clone association without `NestedAttributes` plugin, Clowne will skip this declaration.

data/docs/supported_adapters.md CHANGED Viewed

@@ -1,13 +1,10 @@
----
-id: supported_adapters
-title: Supported Adapters
----
+# Supported Adapters
 Clowne supports the following ORM adapters (and associations):
 Adapter                                            |1:1         | 1:M         | M:M                     |
 ---------------------------------------------------|------------|-------------|-------------------------|
-[:active_record](/clowne/docs/active_record.html)   | has_one    | has_many    | has_and_belongs_to_many |
-[:sequel](/clowne/docs/sequel.html)                 | one_to_one | one_to_many | many_to_many            |
+[:active_record](active_record)         | has_one    | has_many    | has_and_belongs_to_many |
+[:sequel](sequel)                       | one_to_one | one_to_many | many_to_many            |
 For more information see the corresponding adapter documentation.

data/docs/testing.md ADDED Viewed

@@ -0,0 +1,194 @@
+# 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.
+## Using partial cloning
+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).to_record
+    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").to_record
+    # 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
+    ).to_record
+    # 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
+    ).to_record
+    expect(cloned_user.posts.size).to eq 1
+    expect(cloned_user.posts.first.text).to eq "Flying Dumplings"
+  end
+end
+```