journeyman 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cc88ba880fcd67214a896dac32304a317037a538
+  data.tar.gz: 5e943948aea70eb2bcc2f4e58ce65671ef04a691
+SHA512:
+  metadata.gz: 4d2deabc6944da9b531b69861d78a7867d74a0f05eb1b7f8dffe5620916fd7d64190a8d265715f5c0fd5b046a79b24130701de0c234680a45a9363b57dc0f786
+  data.tar.gz: 0ed0da538b523579bf98500ff50e70de99ea7b80384b60190d9810279b8acbb981c9c6122f499f662b12b54cadee4e65404a577013c23be86579f8fb2f7021f7

data/README.md

@@ -0,0 +1,189 @@
+Journeyman [![Gem Version](https://badge.fury.io/rb/journeyman.svg)](http://badge.fury.io/rb/journeyman) [![Build Status](https://travis-ci.org/ElMassimo/journeyman.svg)](https://travis-ci.org/ElMassimo/journeyman) [![Test Coverage](https://codeclimate.com/repos/5372dce769568034ff0304c2/badges/e014d258ab0dbe3f668e/coverage.svg)](https://codeclimate.com/repos/5372dce769568034ff0304c2/feed) [![Code Climate](https://codeclimate.com/repos/5372dce769568034ff0304c2/badges/e014d258ab0dbe3f668e/gpa.png)](https://codeclimate.com/repos/5372dce769568034ff0304c2/feed) [![Inline docs](http://inch-ci.org/github/ElMassimo/journeyman.svg)](http://inch-ci.org/github/ElMassimo/journeyman) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ElMassimo/journeyman/blob/master/LICENSE.txt)
+=====================
+
+Journeyman is a fixtures replacement with an extremely light definition syntax,
+providing two default build strategies, but allowing full customization on how
+to build an object.
+
+## Usage
+Journeyman is built to work out of the box with RSpec and Cucumber, and any
+console environment, if you need support for other testing frameworks we can
+work it out :smiley:.
+
+Since it has no dependencies, it's possible to use it in any Ruby project.
+
+### Load
+Journeyman will attempt to load files under the `spec/factories` directory, but
+you may overwrite `Journeyman.factories_paths` by providing an Array that
+containst different paths for factories.
+
+### Definition
+Journeyman allows you to provide the default attributes for creation as the
+return value of the definition block.
+
+```ruby
+Journeyman.define :album do |c|
+  {
+    title: 'Wish You Were Here',
+    recorded_ago: -> { (Date.today - Date.new(1975, 9, 12)).round / 365 },
+    band: -> { Journeyman.create(:band, name: 'Pink Floyd') }
+  }
+end
+```
+The default values are superseded by the value you provide to `build` or `create`.
+
+```ruby
+pink_floyd = find_band('Pink Floyd')
+
+Journeyman.build(:album, band: pink_floyd) == Album.new({
+  title: 'Wish You Were Here',
+  recorded_ago: -> { ... }.call,
+  band: pink_floyd
+})
+```
+The default values can be static, or dynamic. If you specify a `Proc` or `lambda`
+as a default value for an attribute, it will be evaluated whenever the attribute
+is not provided when an object is built.
+
+### Configuration
+Journeyman is a configurable beast, yet has really strong defaults.
+```ruby
+# DSL Methods
+find, process, ignore, build, after_create
+
+# Configuration Options
+[:parent, :model, :finder_attribute]
+```
+
+#### DSL
+Journeyman provides a nice DSL that lets you provide a block or lambda with your
+own builder, or finder, and other miscellanous (and handy) hooks.
+
+* `find:` Allows you to define the finder, takes a single argument.
+
+* `build:` You can provide a custom builder, receives a Hash of attributes, but
+you have full liberty of what you do with them, the return value must be the
+built object.
+
+* `process:` If you need to process the attributes before building you can
+provide a block to do just that, make sure to return the attributes at the end.
+
+* `ignore:` There are cases where you want to ignore certain attributes during
+the `build`, but you want them in the `after_create` callback. You can ignore
+those attributes by passing a list, or Array with the attributes you wish to
+ignore.
+
+* `after_create`: Callback that takes the newly built object, and the original
+attributes. Specially useful when combined with ignore.
+
+```ruby
+Journeyman.define :employee do
+  find { |id| Person.find(id) }
+
+  build { |attrs|
+    attrs.delete(:company).new_employee(attrs)
+  }
+
+  ignore :work_history
+
+  after_create { |employee, attrs|
+    attrs[:work_history].each do |history|
+      check_references(history)
+    end
+  }
+end
+```
+
+#### Configuration Options
+Configuration options can be passed alongside the name in the factory definition:
+
+* `parent:` Name of the factory that is going to be used as a parent, if `parent`
+is set, the default builder consists of invoking the parent factory builder.
+
+* `model:` Expects a class that will be used for the default builder and finder.
+Useful for cases where the inferrence from the name does not work, or the factory
+name is simply different than the object class it's building.
+
+* `finder_attribute:` Name of the attribute used to find an object by the default
+finder. The default is `:name`.
+
+```ruby
+Journeyman.define :employee, model: People, finder_attribute: :social_security_id do
+...
+end
+
+Journeyman.define :journeyman, parent: :employee do
+...
+end
+```
+
+## Setup
+```ruby
+# Gemfile
+group :test do
+  gem 'journeyman'
+end
+
+# Generic Use (mock script)
+require 'journeyman'
+
+Journeyman.load(self)
+````
+### RSpec
+```ruby
+# spec/support/spec_helper.rb or similar
+require 'journeyman'
+
+Journeyman.load(self, framework: :rspec)
+````
+
+### Cucumber
+```ruby
+# features/support/journeyman.rb or similar
+require 'journeyman'
+
+Journeyman.load(self, framework: :cucumber)
+````
+
+## Advantages
+
+* You have full control of how your objects are created, *and* have to write
+less boilerplate.
+* You can chain several factories using parent, which allows you to create
+different factories for the same object with less effort.
+* Code is highly optimized, so the library is much faster than say, FactoryGirl,
+specially when building objects without database interaction.
+
+
+### Examples
+
+You can check the [specs](https://github.com/ElMassimo/journeyman/tree/master/spec) of the project
+to check how to check some basic factories, and learn how to set it up.
+
+## Notes
+* The DSL does not use instance_exec to allow access to the external context.
+
+
+License
+--------
+
+    Copyright (c) 2014 Máximo Mussini
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/journeyman.rb

@@ -0,0 +1,65 @@
+require 'journeyman/load'
+require 'journeyman/integration'
+require 'journeyman/definition'
+
+# Public: Allows to define and use factory methods. It is capable of providing
+# `build`, `create`, `find`, and `default` methods, the last two are optional.
+#
+# Examples:
+#
+#   Journeyman.define :user do |t|
+#     {
+#       name: "Johnnie Walker",
+#       date_of_birth: ->{ 150.years.ago }
+#     }
+#   end
+#
+#   Journeyman.build(:user)  => build_user
+#   Journeyman.create(:user) => create_user
+#
+module Journeyman
+  extend Load
+  extend Integration
+  extend Definition
+
+  # Public: Initializes Journeyman by loading the libraries, attaching to the
+  # current context, and configuring the testing libraries.
+  def self.load(env, framework: nil)
+    @helpers = Module.new
+    attach(env)
+    load_factories
+    setup_integration(env, framework)
+  end
+
+  # Public: Attaches Journeyman to the specified context, which enables the use
+  # of the convenience acessors for the factory methods, like `Journeyman.build`.
+  def self.attach(context)
+    @context = context
+  end
+
+  # Public: Convenience accessor for build methods.
+  def self.build(name, *args, &block)
+    @context.send("build_#{name}", *args, &block)
+  end
+
+  # Public: Convenience accessor for create methods.
+  def self.create(name, *args, &block)
+    @context.send("create_#{name}", *args, &block)
+  end
+
+  # Public: Convenience accessor for default methods.
+  def self.default(name)
+    @context.send("default_#{name}")
+  end
+
+  # Internal: Executes a proc in the context that is currently attached.
+  def self.execute(proc, *args)
+    if proc
+      if proc.arity == 0
+        @context.instance_exec(&proc)
+      else
+        @context.instance_exec(*args, &proc)
+      end
+    end
+  end
+end

data/lib/journeyman/builder.rb

@@ -0,0 +1,66 @@
+require 'journeyman/configuration'
+module Journeyman
+
+  # Internal: Builds and creates objects, using the configuration provided.
+  class Builder
+    extend Forwardable
+
+    attr_reader :config
+    def_delegators(:config, *Configuration::OPTIONS, *Configuration::METHOD_OPTIONS, :name)
+
+    def initialize(name, options, config)
+      @config = Configuration.new(name, options, config)
+    end
+
+    # Internal: Executes the finder.
+    def find(id)
+      config.finder.call(id)
+    end
+
+    # Internal: Builds a new instance, using the configuration specified in the
+    # factory.
+    #
+    # attrs - The attributes used to build the object
+    #
+    # Returns a new instance of the object.
+    def build(attrs={})
+      check_build_arguments(attrs)
+      attrs = merge_defaults(attrs)
+      attrs = Journeyman.execute(processor, attrs) if processor
+      config.builder.call(attrs)
+    end
+
+    # Internal: Create a new instance, using the configuration specified in the
+    # factory.
+    #
+    # attrs - The attributes used to build the object
+    #
+    # Returns a new instance of the object.
+    def create(attrs={})
+      build(attrs).tap { |instance|
+        instance.save!
+        Journeyman.execute(after_create_callback, instance, attrs)
+      }
+    end
+
+    private
+
+    # Internal: Merges the default attributes to the specified attributes Hash.
+    #
+    # Returns the modified Hash.
+    def merge_defaults(attributes={})
+      attributes.tap do |attrs|
+        attrs.merge!(static_defaults){ |key, user, default| user } # Reverse Merge
+        dynamic_defaults.each { |key, value| attrs[key] ||= Journeyman.execute(value, attrs) }
+      end
+    end
+
+    # Internal: Checks the attributes to make sure it's a Hash, to provide more
+    # insight on wrong usage.
+    def check_build_arguments(attrs)
+      unless attrs.is_a?(Hash)
+        raise ArgumentError, "Journeyman expected a Hash, but received: #{attrs}"
+      end
+    end
+  end
+end

data/lib/journeyman/configuration.rb

@@ -0,0 +1,168 @@
+module Journeyman
+
+  # Public: Provides a DSL for configuration of the factories.
+  class Configuration
+
+    METHOD_OPTIONS = [:finder, :builder, :processor]
+
+    OPTIONS = [
+      :parent, :defaults, :finder_attribute, # Public
+      :static_defaults, :dynamic_defaults, :after_create_callback # Internal
+    ]
+
+    # Internal: Name of the factory, and configuration options.
+    attr_reader :name, :options
+
+    # Public: Receives the name of the factory, and configuration options.
+    #
+    # Yields itself to the block passed to the `Journeyman.define`.
+    def initialize(name, options, config)
+      @name, @options = name, options
+      extract_defaults config.call(self)
+      verify_valid_or_exit
+    end
+
+    # Public: DSL to configure a Journeyman definition. The following are only
+    # the methods that take a block, other configuration options exist but take
+    # a single argument.
+
+    # Public: Defines how to find an instance.
+    #
+    #  find { |id|
+    #    User.find_by(name_or_email(id) => id)
+    #  }
+    #
+    # Yields the find argument passed to the `find_#{name}` method.
+    def find(proc=nil, &block)
+      options[:finder] = proc || block
+    end
+
+    # Public: Defines how to build an instance. Highly customizable.
+    #
+    #  build { |attributes|
+    #    blueprint, patient = attributes.delete(:blueprint), attributes.delete(:patient)
+    #    blueprint.enroll(patient)
+    #  }
+    #
+    # Yields the arguments passed to the `build_#{name}` method after adding the
+    # defaults and invoking the processor.
+    def build(proc=nil, &block)
+      options[:builder] ||= proc || block
+    end
+
+    # Public: Attributes processor, allows to modify the passed attributes
+    # before building an instance.
+    def process(proc=nil, &block)
+      options[:processor] ||= proc || block
+    end
+
+    # Public: Allows to ignore certain attributes, that can be accessed in the
+    # after_create callback.
+    def ignore(*ignored)
+      options[:ignored] = ->(attrs) do
+        attrs = attrs.dup; ignored.each { |key| attrs.delete(key) }; attrs
+      end
+    end
+
+    # Public: Invoked after creating an object, useful for setting up secondary
+    # or optional relations.
+    def after_create(proc=nil, &block)
+      options[:after_create_callback] ||= proc || block
+    end
+
+
+    # Internal: Configuration Options provided for the Journeyman builder. Here
+    # is where you can stop reading unless you are interested in the internals.
+
+    # Internal: Class of the model to build, used in the default build strategy.
+    def model
+      options[:model] ||= infer_model_class(name)
+    end
+
+    # Internal: Returns the finder proc, or the default finder strategy.
+    def finder
+      options[:finder] ||= default_finder
+    end
+
+    # Internal: Returns the finder proc, or the default builder strategy.
+    def builder
+      options[:builder] ||= parent_builder || default_builder
+    end
+
+    # Internal: Returns a custom processor, or ignore directive.
+    def processor
+      options[:ignored] || options[:processor]
+    end
+
+    private
+
+    # Internal: Default finder strategy used.
+    def default_finder
+      options[:finder_attribute] ||= :name
+      ->(name) { model.find_by(finder_attribute => name) }
+    end
+
+    # Internal: Creates the object by simply using the initializer.
+    def default_builder
+      ->(attrs={}) { model.new(attrs) }
+    end
+
+    # Internal: Uses the builder of the parent to construct the object.
+    #
+    # Returns the builder if a :parent was set, or nil.
+    def parent_builder
+      ->(attrs={}) { Journeyman.build(parent, attrs) } if parent
+    end
+
+    # Internal: Prepares the default arguments for the builder.
+    # The return value of the configuration block may provide the defaults.
+    #
+    # result - The return value of the configuration block.
+    #
+    # Returns nothing.
+    def extract_defaults(result)
+      defaults = options[:defaults] || (result if result.is_a?(Hash)) || {}
+
+      options[:dynamic_defaults], options[:static_defaults] = partition_defaults(defaults)
+    end
+
+    # Internal: Splits static from dynamic arguments for runtime performance.
+    def partition_defaults(defaults)
+      defaults.partition { |key, value| value.is_a?(Proc) }.map(&:to_h)
+    end
+
+    # Internal: Infers a model class.
+    def infer_model_class(name)
+      if defined? ActiveSupport
+        name.to_s.classify.constantize
+      else
+        Object.const_get(name.to_s.split('_').collect!{ |w| w.capitalize }.join)
+      end
+    end
+
+    # Internal: Checks the configuration's consistency
+    def verify_valid_or_exit
+      if options[:parent] && options[:builder]
+        raise InvalidArgumentError, 'custom builder can not be used in combination with `parent: true`'
+      end
+      if options[:ignored] && options[:processor]
+        raise InvalidArgumentError, 'custom processor can not be used in combination with `ignore`'
+      end
+    end
+
+    # Internal: Performance optimization, the option method is defined the first
+    # time it's accessed.
+    def self.define_option_method(name)
+      class_eval <<-OPTION
+        def #{name}(value=nil)
+          options[:#{name}] = value if value
+          options[:#{name}]
+        end
+      OPTION
+    end
+
+    OPTIONS.each do |name|
+      define_option_method(name)
+    end
+  end
+end

data/lib/journeyman/definition.rb

@@ -0,0 +1,55 @@
+require 'journeyman/builder'
+module Journeyman
+
+  # Internal: Contains all the factory method definition logic.
+  module Definition
+
+    # Public: Defines a new factory for Journeyman, which consists in a build
+    # and create method, and may optionally include finder and default methods.
+    #
+    # Returns Builder for debug purposes.
+    def define(name, options={}, &config)
+      finder, default = options.delete(:include_finder), options.delete(:include_default)
+
+      Builder.new(name, options, config).tap do |builder|
+        define_find_method(name, builder) unless finder == false
+        define_build_method(name, builder)
+        define_create_method(name, builder)
+        define_default_method(name) if default
+      end
+    end
+
+    private
+
+    # Factories Definitions
+
+    # Internal: Defines the finder method.
+    def define_find_method(name, builder)
+      define_helper "find_#{name}", ->(id) { builder.find(id) }
+    end
+
+    # Internal: Defines the builder method.
+    def define_build_method(name, builder)
+      define_helper "build_#{name}", ->(attrs={}) { builder.build(attrs) }
+    end
+
+    # Internal: Defines the create method.
+    def define_create_method(name, builder)
+      define_helper "create_#{name}", ->(attrs={}) { builder.create(attrs) }
+    end
+
+    # Internal: Defines the default method.
+    def define_default_method(name)
+      @helpers.send :class_eval, <<-EVAL
+        def default_#{name}
+          @#{name} ||= Journeyman.create(:'#{name}')
+        end
+      EVAL
+    end
+
+    # Internal: Syntax sugar to define a method in the helpers module.
+    def define_helper(name, proc)
+      @helpers.send :define_method, name, proc
+    end
+  end
+end

data/lib/journeyman/integration.rb

@@ -0,0 +1,38 @@
+module Journeyman
+
+  # Internal: Integrations with testing frameworks.
+  module Integration
+
+    # Internal: Sets up the integration with the framework being used.
+    def setup_integration(env, framework)
+      case framework
+      when :rspec then setup_rspec_integration(env)
+      when :cucumber then setup_cucumber_integration(env)
+      else setup_default_integration(env)
+      end
+    end
+
+    private
+
+    # Internal: Sets up the default integration, which is helpful for console and
+    # mock scripts.
+    def setup_default_integration(env)
+      env.send :include, @helpers
+      Journeyman.attach(env)
+    end
+
+    # Internal: Attaches Journeyman to the RSpec context, and adds the helpers.
+    def setup_rspec_integration(env)
+      RSpec.configure do |config|
+        config.include @helpers
+        config.before(:each) { Journeyman.attach(self) }
+      end
+    end
+
+    # Internal: Attaches Journeyman to the Cucumber context, and adds the helpers.
+    def setup_cucumber_integration(cucumber)
+      cucumber.World(@helpers)
+      cucumber.Before { Journeyman.attach(self) }
+    end
+  end
+end

data/lib/journeyman/load.rb

@@ -0,0 +1,52 @@
+module Journeyman
+
+  # Internal: Contains all the file requirement logic, to load the factory definitions.
+  module Load
+
+    # Public: Paths that will be loaded expecting factory definitions.
+    attr_accessor :factories_paths
+
+    def self.extended(journeyman)
+      journeyman.factories_paths = %w(spec/factories)
+    end
+
+    # Internal: Loads all the factory files and processes the factory definitions.
+    def load_factories
+      absolute_factories_paths.each do |path|
+        load_factories_if_file(path)
+        load_factories_if_directory(path)
+      end
+    end
+
+    private
+
+    # Internal: Builds the absolute path for the factories location.
+    def absolute_factories_paths
+      if root_path
+        factories_paths.map { |path| root_path.join(path) }
+      else
+        factories_paths.map { |path| File.expand_path(path) }.uniq
+      end
+    end
+
+    # Internal: If the path matches a file, it loads the factories defined in it.
+    def load_factories_if_file(path)
+      Kernel.load("#{path}.rb") if File.exists?("#{path}.rb")
+    end
+
+    # Internal: If the path is a directory, it loads all the factories in that path.
+    def load_factories_if_directory(path)
+      if File.directory?(path)
+        Dir[File.join(path, '**', '*.rb')].sort.each { |file| Kernel.load file }
+      end
+    end
+
+    # Internal: Returns the root path of the project
+    # TODO: Extract Rails and Sinatra integration.
+    def root_path
+      defined?(Rails) && Rails.root ||
+      defined?(Sinatra::Application) && Pathname.new(Sinatra::Application.root) ||
+      defined?(ROOT_DIR) && Pathname.new(ROOT_DIR)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: journeyman
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Máximo Mussini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-16 00:00:00.000000000 Z
+dependencies: []
+description: Journeyman allows you to define factories with custom build methods,
+  allowing you to easily bend object creation to the nuances of your application and
+  domain. This means you can rely more in Ruby, and less on your ORM
+email:
+- maximomussini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/journeyman.rb
+- lib/journeyman/builder.rb
+- lib/journeyman/configuration.rb
+- lib/journeyman/definition.rb
+- lib/journeyman/integration.rb
+- lib/journeyman/load.rb
+homepage: https://github.com/ElMassimo/journeyman
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Let your factories use your business logic, keeping them flexible and making
+  them easier to update.
+test_files: []
+has_rdoc: