faker_maker 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d52a9450058657ec1fba8756afa5a965a6f92fcf074ef5d05c0c2b7a1d09ea2
-  data.tar.gz: e0c12b011abd0337a5699a054c44e0b4fc3eb05f385b24a0dd9e54d2864ee611
+  metadata.gz: cc9201db222f65f8df79f92edc882d9d76e5ca21c6220b377f5e86ce9414d287
+  data.tar.gz: d4601f347ce1231fd287d33addde2bb83c00a1a770783eec8007dd7417c6c2f3
 SHA512:
-  metadata.gz: d467cdafe73e4ddd1cf0b1677f96c935f28430b09b2580b7a141d674d4c8690f6c850bacb8c2f2c22ad32805e9d2d2e8c86c77f5807a50018d375299f56c70b1
-  data.tar.gz: 4f4ede5c6ac0e3290952e29f03b90855c7112332a32a6ceaebe0d5b8ab54340388698bebcdaadabe390beb55a4ac91597200a8960e668e8fb9f0a276ad9f00e1
+  metadata.gz: ce1be4538d82898bb1accd89585485e6072974350088261dece5f0481a3d1950cbf1462dba6363231e2b25019632d8f1aa649e04cab5c4a0a752c6ca9e428c7f
+  data.tar.gz: 2d442d69c483b0aa5ba5f7bc9fd26396376edbc2ff700c9d47305d27f2fc809d42d4971bf8ef8b09c67f7f4912395e6eb0127c0d105e6763708f342916e2ae85

data/.github/workflows/ruby.yml

@@ -0,0 +1,37 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ["3.0", "3.1", "3.2"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -14,4 +14,5 @@ Gemfile.lock
 .DS_Store
 
 faker_maker-*.gem
-test.rb
+test.rb
+.idea

data/.rubocop.yml

@@ -43,4 +43,13 @@ Metrics/MethodLength:
   Enabled: false
 
 Lint/MissingSuper:
-  Enabled: false
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+AllCops:
+  NewCops: enable

data/Guardfile

@@ -17,7 +17,7 @@
 #
 # and, you'll have to watch "config/Guardfile" instead of "Guardfile"
 
-# Note: The cmd option is now required due to the increasing number of ways
+# NOTE: The cmd option is now required due to the increasing number of ways
 #       rspec may be run, below are examples of the most common uses.
 #  * bundler: 'bundle exec rspec'
 #  * bundler binstubs: 'bin/rspec'

data/bin/console

@@ -3,6 +3,7 @@
 
 require 'bundler/setup'
 require 'faker_maker'
+require 'faker'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/docs/usage/audit_logs.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: Audit (History) Logs
+parent: Usage
+nav_order: 10
+---
+
+_(since 1.3.0)_
+
+# Audit logs
+
+It might be useful to collect the history of all the fakes generated by your factories. FakerMaker allows you to stream (or write to a file) all the instances it builds for you. This is optional and disabled by default.
+
+## Enable logging
+
+By default audit logging is disabled. The default output stream is `STDOUT`. The output target can either be an object that responds to `puts`, or be a string which will be interpreted as a file location to use to write to. If file path string is used, it will be opened in 'append' mode.
+
+```ruby
+FakerMaker.configure do |config|
+  config.audit = true
+  config.audit_destination = '/tmp/faker_maker_audit_logs'
+end
+```
+
+## Audit streams
+
+Immediately after each object is built and after the post-build hooks have completed, the instance details will be logged in line-delimited JSON (JSONL), to the stream or file. Each line is contained in an envelope containing the following metadata:
+
+* The timestamp at the time of logging
+* The name of factory
+* The class name of the object the factory instantiated
+
+For example, given the factory:
+
+```ruby
+FakerMaker.factory :user do 
+  name {'Patsy Stone'}
+  email {'patsy@fabulous.co.uk'}
+  admin {false}
+end
+```
+
+The audit log, on build, would look like:
+
+```
+{"timestamp":"2023-05-15T15:46:30+01:00","factory":"user","class":"User","body":{"name":"Patsy Stone","email":"patsy@fabulous.co.uk","admin":false}}
+```

data/docs/usage/chaos.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Chaos
+parent: Usage
+nav_order: 11
+---
+
+# Chaos
+
+Chaos mode introduces extra spice to your generated factories. 
+
+Attributes can be marked as either `required` or `optional`, which Chaos will use to determine what attributes are included when instantiating your factory. 
+
+Required attributes will always be present, however, optional attributes are not guaranteed to be present when Chaos is enabled. 
+
+*All attributes are optional by default.*
+
+To explicitly mark attributes as either required or optional:
+
+```ruby
+FM.factory :item, naming: :json do
+  name { 'Blanket' }
+  price(required: true) { 100 }
+  description(optional: true) { 'Keeps you warm and cozy' }
+  manufacturer(optional: 0.7) { 'A large fruit company' }
+end
+```
+
+You can state an attribute is optional using the `optional` option set to either be a `Boolean`, `Integer` or a `Float`. 
+
+When optional is set to either an `Integer` or a `Float`, this overrides the weighting which Chaos uses to determine the likelihood that attribute will be removed.
+
+Higher the value, the more likely that attribute will be present. By default there's a 50/50 chance an optional attribute will be present. 
+
+To unleash Chaos over a factory, you need to enable it when instantiating your object:
+
+```ruby
+result = FakerMaker[:item].build( chaos: true )
+```
+
+You can also specify which attributes Chaos can use when instantiating your object:
+
+```ruby
+result = FakerMaker[:item].build( chaos: %i[name manufacturer] )
+```

data/faker_maker.gemspec

@@ -41,10 +41,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activesupport', '>= 5.2', '< 7'
+  spec.add_dependency 'activesupport', '>= 5.2', '< 8'
 
   spec.add_development_dependency 'bundler',       '~> 2.0'
-  spec.add_development_dependency 'faker',         '~> 2.1'
+  spec.add_development_dependency 'faker',         '~> 3.2'
   spec.add_development_dependency 'guard',         '~> 2.16'
   spec.add_development_dependency 'guard-bundler', '~> 3.0'
   spec.add_development_dependency 'guard-rubocop', '~> 1.3'
@@ -53,8 +53,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake',          '~> 13.0'
   spec.add_development_dependency 'rspec',         '~> 3.8'
   spec.add_development_dependency 'rubocop',       '~> 1.0'
-  spec.add_development_dependency 'simplecov',     '~> 0.16'
-  spec.add_development_dependency 'coveralls',     '~> 0.8'
 
-  spec.required_ruby_version = '>= 2.6'
+  spec.required_ruby_version = '>= 3.0'
 end

data/lib/faker_maker/attribute.rb

@@ -3,16 +3,25 @@
 module FakerMaker
   # Attributes describe the fields of classes
   class Attribute
-    attr_reader :name, :block, :translation
+    attr_reader :name, :block, :translation, :required, :optional, :optional_weighting
+
+    DEFAULT_OPTIONAL_WEIGHTING = 0.5
 
     def initialize( name, block = nil, options = {} )
       assert_valid_options options
       @name = name
-      @block = block || proc { nil }
+      @block = block || proc {}
       @cardinality = options[:has] || 1
       @translation = options[:json]
       @omit = *options[:omit]
       @array = options[:array] == true
+
+      if options[:required].to_s.downcase.eql?('true') || options[:optional].to_s.downcase.eql?('false')
+        @required = true
+      else
+        @optional = true
+        @optional_weighting = determine_optional_weighting(options[:optional])
+      end
     end
 
     def array?
@@ -49,7 +58,18 @@ module FakerMaker
     end
 
     def assert_valid_options( options )
-      options.assert_valid_keys :has, :array, :json, :omit
+      options.assert_valid_keys :has, :array, :json, :omit, :required, :optional
+    end
+
+    def determine_optional_weighting( value )
+      case value
+      when Float
+        value.between?(0, 1) ? value : (value / 100)
+      when Integer
+        value.ceil.between?(0, 100) ? (value.to_f / 100) : DEFAULT_OPTIONAL_WEIGHTING
+      else
+        DEFAULT_OPTIONAL_WEIGHTING
+      end
     end
   end
 end

data/lib/faker_maker/auditable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# FakerMaker module for generating Fakes
+module FakerMaker
+  # Mix-in module which provides the auditable functionality
+  module Auditable
+    def audit(instance)
+      envelope = audit_envelope(class: instance.class.name, body: instance.as_json)
+      audit_stream.puts(JSON.generate(envelope))
+      audit_stream.flush if audit_stream.respond_to?(:flush)
+    rescue StandardError => e
+      warn "FakerMaker Warning: #{e.class}: \"#{e.message}\" occurred. FakerMaker will disable audit logging. " \
+           'Further warnings supressed.'
+      FakerMaker.configuration.audit = false
+    end
+
+    private
+
+    def audit_stream
+      destination = FakerMaker.configuration.audit_destination
+      return destination if destination.respond_to?(:puts)
+
+      file_destination = File.new(destination, 'a')
+      FakerMaker.configuration.audit_destination = file_destination
+    end
+
+    def audit_envelope(**overrides)
+      {
+        timestamp: DateTime.now.iso8601,
+        factory: name.to_s,
+        **overrides
+      }
+    end
+  end
+end

data/lib/faker_maker/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# FakerMaker module for generating Fakes
+module FakerMaker
+  # Configuration class, holds all the config options for FM
+  class Configuration
+    attr_writer :audit
+    attr_accessor :audit_destination
+
+    def initialize
+      @audit = false
+      @audit_destination = $stdout
+    end
+
+    def audit?
+      @audit
+    end
+  end
+
+  # Mixin to provide configuraton methods to an extending or implementing class
+  module Configurable
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configuration=(config)
+      @configuration = config
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+  end
+end

data/lib/faker_maker/factory.rb

@@ -4,7 +4,8 @@
 module FakerMaker
   # Factories construct instances of a fake
   class Factory
-    attr_reader :name, :class_name, :parent
+    include Auditable
+    attr_reader :name, :class_name, :parent, :chaos_selected_attributes
 
     def initialize( name, options = {} )
       assert_valid_options options
@@ -18,7 +19,7 @@ module FakerMaker
                          when nil
                            nil
                          else
-                           raise FakerMaker::NoSuchAttributeNamingStrategy, opttions[:naming]
+                           raise FakerMaker::NoSuchAttributeNamingStrategy, options[:naming]
                          end
       @attributes = []
       @klass = nil
@@ -41,13 +42,25 @@ module FakerMaker
       @instance ||= instantiate
     end
 
-    def build( attributes = {} )
+    def build( attributes: {}, chaos: false, **kwargs )
+      if kwargs.present?
+        validate_deprecated_build(kwargs)
+        attributes = kwargs
+      end
+
       @instance = nil
       before_build if respond_to? :before_build
       assert_only_known_attributes_for_override( attributes )
-      populate_instance instance, attributes
+
+      assert_chaos_options chaos if chaos
+
+      optional_attributes
+      required_attributes
+
+      populate_instance instance, attributes, chaos
       yield instance if block_given?
       after_build if respond_to? :after_build
+      audit(@instance) if FakerMaker.configuration.audit?
       instance
     end
 
@@ -108,11 +121,14 @@ module FakerMaker
 
     protected
 
-    def populate_instance( instance, attr_override_values )
-      FakerMaker[parent].populate_instance instance, attr_override_values if parent?
-      @attributes.each do |attr|
-        value = value_for_attribute( instance, attr, attr_override_values )
-        instance.send "#{attr.name}=", value
+    def populate_instance( instance, attr_override_values, chaos )
+      FakerMaker[parent].populate_instance instance, attr_override_values, chaos if parent?
+
+      attributes = chaos ? chaos_select(chaos) : @attributes
+
+      attributes.each do |attribute|
+        value = value_for_attribute( instance, attribute, attr_override_values )
+        instance.send "#{attribute.name}=", value
       end
       instance.instance_variable_set( :@fm_factory, self )
     end
@@ -126,6 +142,19 @@ module FakerMaker
       raise FakerMaker::NoSuchAttributeError, issue unless unknown_attrs.empty?
     end
 
+    def assert_only_known_and_optional_attributes_for_chaos( chaos_attr_values )
+      chaos_attr_values = chaos_attr_values.map(&:to_sym)
+      unknown_attrs = chaos_attr_values - attribute_names
+      issue = "Can't build an instance of '#{class_name}' " \
+              "setting '#{unknown_attrs.join( ', ' )}', no such attribute(s)"
+      raise FakerMaker::NoSuchAttributeError, issue unless unknown_attrs.empty?
+
+      # Are any chaos attributes marked as required?
+      conflicting_attributes = chaos_attr_values.select { |attr| required_attributes.map(&:name).include? attr }
+      issue = "Can't use chaos on a required attribute: '#{conflicting_attributes}'"
+      raise FakerMaker::ChaosConflictingAttributeError, issue unless conflicting_attributes.empty?
+    end
+
     def attribute_hash_overridden_value?( attr, attr_override_values )
       attr_override_values.keys.include?( attr.name )
     end
@@ -162,6 +191,68 @@ module FakerMaker
     def assert_valid_options( options )
       options.assert_valid_keys :class, :parent, :naming
     end
+
+    # Asserts attributes passed in for chaos mode are valid
+    def assert_chaos_options( chaos )
+      eval = -> { [Array, String, TrueClass, FalseClass, Symbol].include? chaos.class }
+      msg = "chaos: arg does not support object of type: '#{chaos.class}'"
+      raise NoSuchAttributeError, msg unless eval.call
+
+      case chaos
+      when Array
+        assert_only_known_and_optional_attributes_for_chaos(chaos)
+      when String, Symbol
+        assert_only_known_and_optional_attributes_for_chaos([chaos])
+      end
+    end
+
+    # Selects required @attributes
+    def required_attributes
+      @required_attributes ||= @attributes.select { |attr| attr.required.eql? true }
+    end
+
+    # Selects optional @attributes
+    def optional_attributes
+      @optional_attributes ||= @attributes.select(&:optional)
+    end
+
+    # Randomly selects optional attributes
+    # Attributes selected from parent will also be selected for the child
+    # @param [Array || TrueClass] chaos_attrs
+    # @return [Array]
+    def chaos_select( chaos_attrs = [] )
+      selected_attrs = []
+      optional_attrs = optional_attributes.dup
+
+      # Filter specific optional attributes if present
+      if chaos_attrs.is_a?(Array) && chaos_attrs.size.positive?
+        optional_attrs, selected_attrs = optional_attrs.partition { |attr| chaos_attrs.include?(attr.name) }
+      end
+
+      # Grab parent selected attributes
+      @chaos_selected_attributes = parent? ? FakerMaker[parent].chaos_selected_attributes : []
+      selected_inherited_attr = optional_attrs.select do |attr|
+        @chaos_selected_attributes.map(&:name).include? attr.name
+      end
+
+      # Select optional attributes based on weighting
+      optional_attrs.each do |optional_attr|
+        selected_attrs.push(optional_attr) if Random.rand < optional_attr.optional_weighting
+      end
+
+      # Concat required, selected and parent attributes
+      @chaos_selected_attributes.concat(required_attributes)
+                                .concat(selected_inherited_attr)
+                                .concat(selected_attrs).uniq!
+      @chaos_selected_attributes
+    end
+
+    def validate_deprecated_build(kwargs)
+      usage = kwargs.each_with_object([]) { |kwarg, result| result << "#{kwarg.first}: #{kwarg.last}" }.join(', ')
+
+      warn "[DEPRECATION] `FM[:#{name}].build(#{usage})` is deprecated. " \
+           "Please use `FM[:#{name}].build(attributes: { #{usage} })` instead."
+    end
   end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/faker_maker/lifecycle_hooks.rb

@@ -4,12 +4,12 @@ module FakerMaker
   module LifecycleHooks
     # Lifecycle hooks which can be called during the building of an instance
     module DefinitionProxy
-      def before_build(&block)
-        @factory.define_singleton_method(:before_build) { yield(self.instance, self) }
+      def before_build
+        @factory.define_singleton_method(:before_build) { yield(instance, self) }
       end
 
-      def after_build(&block)
-        @factory.define_singleton_method(:after_build) { yield(self.instance, self) }
+      def after_build
+        @factory.define_singleton_method(:after_build) { yield(instance, self) }
       end
     end
   end

data/lib/faker_maker/version.rb

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

data/lib/faker_maker.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require 'time'
+
 require 'active_support'
 require 'active_support/core_ext/hash'
 require 'active_support/core_ext/object/json'
 require 'active_support/core_ext/string'
 require 'faker_maker/attribute'
+require 'faker_maker/auditable'
 require 'faker_maker/base'
+require 'faker_maker/configuration'
 require 'faker_maker/lifecycle_hooks'
 require 'faker_maker/definition_proxy'
 require 'faker_maker/factory'
@@ -18,10 +22,12 @@ require 'faker_maker/version'
 # FakerMaker module for generating Fakes
 module FakerMaker
   extend FakerMaker::Base
+  extend FakerMaker::Configurable
 
   class Error < StandardError; end
   class NoSuchFactoryError < StandardError; end
   class NoSuchAttributeError < StandardError; end
+  class ChaosConflictingAttributeError < StandardError; end
   class NoSuchAttributeNamingStrategy < StandardError; end
   # Your code goes here...
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faker_maker
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Nigel Brookes-Thomas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-16 00:00:00.000000000 Z
+date: 2023-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -19,7 +19,7 @@ dependencies:
         version: '5.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '5.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '8'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -50,14 +50,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -170,34 +170,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.16'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.16'
-- !ruby/object:Gem::Dependency
-  name: coveralls
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
 description: FakerMaker is a simple factory builder so you can throw away your fixtures
   and generate test data instead.
 email:
@@ -206,9 +178,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".circleci/config.yml"
-- ".coveralls.yml"
 - ".github/dependabot.yml"
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -230,7 +201,9 @@ files:
 - docs/installation.md
 - docs/logo.png
 - docs/usage/arrays.md
+- docs/usage/audit_logs.md
 - docs/usage/building_instances.md
+- docs/usage/chaos.md
 - docs/usage/dependencies.md
 - docs/usage/destroying_factories.md
 - docs/usage/embedding_factories.md
@@ -243,7 +216,9 @@ files:
 - img/unipug.svg
 - lib/faker_maker.rb
 - lib/faker_maker/attribute.rb
+- lib/faker_maker/auditable.rb
 - lib/faker_maker/base.rb
+- lib/faker_maker/configuration.rb
 - lib/faker_maker/definition_proxy.rb
 - lib/faker_maker/factory.rb
 - lib/faker_maker/lifecycle_hooks.rb
@@ -266,14 +241,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: FakerMaker bakes fakes.

data/.circleci/config.yml

@@ -1,13 +0,0 @@
-# Use the latest 2.1 version of CircleCI pipeline processing engine, see https://circleci.com/docs/2.0/configuration-reference/
-version: 2.1
-
-jobs:
-  build:
-    docker:
-      - image: circleci/ruby:2.6.3-stretch-node
-    steps:
-      - checkout
-      - run: gem update --system
-      - run: gem install bundler
-      - run: bundle install
-      - run: bundle exec rake spec

data/.coveralls.yml

@@ -1 +0,0 @@
-repo_token: K7czIqoKhrE9BRBk1ubEToyJkLgTk0frJ