faker_maker 5.0.3 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 513de304bb5e07889bc3ebcfa0f79264aedca13b7d01ab29fc1fb5559d3d5266
-  data.tar.gz: 9e5475d85f6a5eb58934450f4d7d4075e8c3778d678dffa9e9ace40b074e23d8
+  metadata.gz: 1b44668161c6ce88829e45936506db190418e6091de053e989242501f393171e
+  data.tar.gz: 1b51f3d30bd45ef34ec7384c7dcbe7fd8ea18196130e10551d044cd40aca55ae
 SHA512:
-  metadata.gz: a190cd322a17ccf3ad4376e80ba27584bfd8f821432539dc738e39c9ec9bfae7dada1de12db82fa866d799daaa4c13746218142e20f534da5c5f3abfa5b4e44a
-  data.tar.gz: fada3749b0b6a767a7134375e7732ab8a14b545d7b118f6ef07365c397274ae3d3ef927791fb6be7a146cb1e358965f275d420edba60df6ba1406c05ddd6cc5b
+  metadata.gz: beabf0e7079472e45322bfe0d46b04879d16e8740ba62599d85607c1c72ed76a0f32bc1430c1eca0ad205eb8631ca3510c8e9482064d7bf2fd8e3c8b0b97ec62
+  data.tar.gz: ad699c63f26f18b05cbf6936c69d7943e6ffa5686ebdc726aa0449f7139518cb4797a4d10da17c2c562bd95e7b4f226f2c5f8d243201906f214e1338b7d2bbcd

data/lib/faker_maker/factory.rb

@@ -254,12 +254,18 @@ module FakerMaker
     end
 
     def value_for_attribute( instance, attr, attr_override_values, chaos: false )
-      # Note: This is a behaviour change on the 5.x branch
-      # If the attribute is overriden, that value will be supplied UNLESS
+      # NOTE: This is a behaviour change as of 5.x
+      # If the attribute is overridden, that value will be supplied UNLESS
       # - the value is a Hash, in which case FM will attempt to set nested parameters
-      # EXCEPT if the hash is empty, in which case the assumptions is that the user intends to always
-      # return an empty hash value
-      if overridden_value?( attr, attr_override_values ) && !non_empty_hash?(attr_override_values[attr.name])
+      #   EXCEPT if the Hash is empty, in which case the assumption is that the user intends to always
+      #   return an empty Hash value
+      # - the attribute is an array of embedded factories and the value is an Array, in which case FM
+      #   manufactures one object for each item, using the item as the override for that object
+      #   EXCEPT if the Array is empty, in which case nothing is manufactured
+      #   An item follows the same rules as a single embedded override, so an empty Hash item is supplied as is
+      if array_embedded_factory_override?( attr, attr_override_values )
+        manufacture_array_from_overrides( instance, attr, attr_override_values[attr.name], chaos: )
+      elsif overridden_value?( attr, attr_override_values ) && !non_empty_hash?(attr_override_values[attr.name])
         attr_override_values[attr.name]
       elsif attr.array?
         [].tap do |a|
@@ -276,13 +282,35 @@ module FakerMaker
       end
     end
 
+    # True when an Array override has been supplied for an embedded-factory array attribute.
+    # These overrides are handled item by item rather than as a single value.
+    def array_embedded_factory_override?( attr, attr_override_values )
+      overridden_value?( attr, attr_override_values ) &&
+        attr.array? &&
+        attr.embedded_factories? &&
+        attr_override_values[attr.name].is_a?( Array )
+    end
+
+    # Manufactures one object from the embedded factory for each item in the Array of overrides.
+    # Items follow the same rules as a single embedded override: a non-empty Hash is used as the
+    # overrides for the object, and anything else (such as nil or an empty Hash) is supplied
+    # as is, without running the attribute block. An empty Array yields no objects.
+    def manufacture_array_from_overrides( instance, attr, item_overrides, chaos: false )
+      item_overrides.map do |overrides|
+        next overrides unless non_empty_hash?( overrides )
+
+        manufacture = manufacture_from_embedded_factory( attr, overrides, chaos: )
+        attr.block ? instance.instance_exec( manufacture, &attr.block ) : manufacture
+      end
+    end
+
     def manufacture_from_embedded_factory( attr, attributes = {}, chaos: false )
       attributes ||= {}
       # The name of the embedded factory randomly selected from the list of embedded factories.
       embedded_factory = select_embedded_factory_or_sample(attr, attributes)
 
       if !embedded_factory && !attr.embedded_factories.empty?
-        raise NoSuchFactoryError, "Unable to match given attributes to an embedded factory. Atributes: #{attributes.keys}"
+        raise NoSuchFactoryError, "Unable to match given attributes to an embedded factory. Attributes: #{attributes.keys}"
       end
 
       # The object that is being manufactured by the factory.

data/lib/faker_maker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FakerMaker
-  VERSION = '5.0.3'
+  VERSION = '5.1.0'
 end

data/usefakermaker.com.site/site/src/docs/usage/building-instances/index.page.md

@@ -40,7 +40,7 @@ end
 
 then the value of `result.name` is 'Electric Sheep'.
 
-Beware when overriding values in this way: there is no type checking. You will get an exception if you try to set a value to an attribute that doesn't exist but you won't get one if you assign, say, an array of values where you would otherwise have a string and vice versa.
+Beware when overriding values in this way: there is no type checking. You will get an exception if you try to set a value to an attribute that doesn't exist but you won't get one if you assign, say, an array of values where you would otherwise have a string and vice versa. The exception is an array of embedded factories, where an Array of Hashes is built into objects (see [Embedding Factories](docs/usage/embedding-factories/)).
 
 Calling `result.to_json` will give a stringified JSON representation. Because ActiveSupport is used under the covers, `as_json` will give you a `Hash` rather than the stringified version.
 

data/usefakermaker.com.site/site/src/docs/usage/chaos/index.page.md

@@ -48,3 +48,5 @@ result.name
 ```
 
 Even though `name` is optional and Chaos might otherwise remove it, explicitly overriding it guarantees it will be present with the value you specified.
+
+This also applies to arrays of embedded factories: an Array override is kept as given, and Chaos is still applied to the objects built from its items.

data/usefakermaker.com.site/site/src/docs/usage/embedding-factories/index.page.md

@@ -89,6 +89,50 @@ end
 
 **Since v5.0.3** when passing override values to `#build` and where the factory has a choice of embedded factory, as in the example above where an inventory may contain either an item or a coupon, Faker Maker will attempt to locate the embedded factory which most matches the values give in the override. For example, if the attributes given to build the `item` field most match `coupon` fields, that embedded factory will be chosen. If there are still several choices which match the given attributes, a random selection will be made.
 
+## Overriding arrays of embedded factories
+
+When an embedded factory attribute is an Array:
+
+```ruby
+FakerMaker.factory :item do
+  name { Faker::Commerce.product_name }
+  price { Faker::Commerce.price }
+end
+
+FakerMaker.factory :basket do
+  items( has: 3, factory: :item )
+end
+```
+
+A Hash override is applied to every object that is built:
+
+```ruby
+FM[:basket].build( attributes: { items: { name: 'Electric Blanket' } } ).as_json
+=> {:items=>[{:name=>"Electric Blanket", :price=>94.33}, {:name=>"Electric Blanket", :price=>40.86}, {:name=>"Electric Blanket", :price=>93.73}]}
+```
+
+**Since v5.1.0** an Array can be passed instead. Faker Maker builds one object for each item in the Array, using the item as the overrides for that object. The number of objects comes from the Array, not from `has:`:
+
+```ruby
+FM[:basket].build( attributes: { items: [{ name: 'Electric Blanket' }, { name: 'Electric Sheep', price: 5.99 }] } ).as_json
+=> {:items=>[{:name=>"Electric Blanket", :price=>34.28}, {:name=>"Electric Sheep", :price=>5.99}]}
+```
+
+Each object is built by its embedded factory, so it uses that factory's JSON field names, `omit` options and (when enabled) Chaos, and anything the item does not set is generated as usual. When the factory has a choice of embedded factory, each item is matched separately.
+
+An item follows the same rules as a single embedded override:
+
+* A non-empty Hash is used as the overrides for the object that is built. An attribute which does not exist raises `NoSuchFactoryError`.
+* An empty Hash, `nil` or any other value is supplied as it is, and the attribute's block is not run for it. This supports testing invalid message formats, as with a single empty Hash override.
+* An empty Array builds no objects.
+
+```ruby
+FM[:basket].build( attributes: { items: [{ name: 'Electric Blanket' }, {}, nil] } ).as_json
+=> {:items=>[{:name=>"Electric Blanket", :price=>47.86}, {}, nil]}
+```
+
+An Array of values is still passed through untouched when the attribute has no embedded factory.
+
 ## Alternative method
 
 There is an alternative style which might be of use, **but** you have less control using build-time overrides for values (you can't set nested values). *This is no longer a recommended pattern*.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faker_maker
 version: !ruby/object:Gem::Version
-  version: 5.0.3
+  version: 5.1.0
 platform: ruby
 authors:
 - Nigel Brookes-Thomas
@@ -274,7 +274,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: FakerMaker bakes fakes.
 test_files: []