scheherazade 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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/README.md

@@ -0,0 +1,140 @@
+# Scheherazade
+
+With Sheherazade's imagination and storytelling skills, fixtures can be as entertaining as the "Arabian Nights".
+
+## Goals
+
+Scheherazade
+
+* imagines plausible characters (creates valid objects automatically)
+* keeps track of her story (reuse objects within a given context)
+* isn't wearing much (minimal DSL, no instance_eval)
+
+## Simple Example
+
+  # Say we have a model like:
+  class Department
+    belongs_to :company
+    has_many :employees
+    validates_presence_of :company, :name
+  end
+
+  # Without any configuration, if we write in a test:
+  story.imagine(Department) # creates a Department,
+                            # with a default name,
+                            # associated to a new Company
+  story.imagine(Department) # creates another Department
+                            # with another name
+                            # and associated to the same Company
+
+## Features
+
+For FactoryGirl (or Machinist) users: a Factory (or Blueprint) corresponds loosely to a Character
+
+### Characters (Models)
+
+Scheherazade creates ActiveRecord objects. The types of objects are called a 'character'. A generic character could be a `User` (or equivalently `:user`) or there could be more specialized characters (say `:admin`).
+
+All your models have a default character type; you can use the class directly or the corresponding symbol. Specialized characters must be defined within the current story before they can be used.
+
+### Context (Story)
+
+The current story holds:
+
+* information on how to build characters
+* the last built character (called the current character)
+* any options you want
+
+Scheherazade can tell nested stories and all this information is inherited.
+
+### Automatic objects (Characters)
+
+Scheherazade can be setup to generate attributes for any model. She will also by default generate values for attributes that are needed.
+
+If the object imagined is not valid, she will try to makeup values for the attributes that have errors (e.g. because of a `validates_presence_of` with a condition that is `true`)
+
+By default, assocations will reuse objects within the current story. For example, two imagined comments will automatically be about the current blog and posted by the current user.
+
+### Logging
+
+Scheherazade is meant to testing and has a logging feature that makes it easier to know what's going on. Turn it on with `Scheherazade.logger.on`
+
+## Documentation
+
+The main class is `Story` and there are 2 important methods: Story#imagine and Story#fill. Story#get is a simple shorthand to get the current character or create it if there isn't any.
+
+## Complete example
+
+  class User
+    belongs_to :blog
+    validates_presence_of :first_name, :last_name
+  end
+
+  class Blog
+    has_many :users
+    has_one :admin, :class_name => "User", :condition => {:admin => true}
+    validates_presence_of :admin
+
+    has_many :posts
+  end
+
+  story.instance_eval do
+    fill User, :email do
+      fill :admin, :admin => true,
+           :nickname => ->(user, sequence){"The boss #{sequence}"}
+    end
+
+    fill Blog, :posts
+  end
+
+## To do
+
+Configurable automatic attributes
+Finish doc
+Finish specs
+
+## Why? Scheherazade vs FactoryGirl vs Machinist
+
+FactoryGirl and Machinist are DSLs to create ActiveRecord objects.
+
+Both make it tedious to deal with nested structures. Example:
+
+    #          / Location - Building - Product
+    # Company {
+    #          \ Department — Employee
+
+    company = FactoryGirl.create(:company)
+    location = FactoryGirl.create(:location, :company => company)
+    building = FactoryGirl.create(:building, :location => location)
+    product = FactoryGirl.create(:product, :building => building)
+    department = FactoryGirl.create(:department, :company => company)
+    employee = FactoryGirl.create(:employee, :department => department)
+
+Since Scheherazade reuses the characters she invents, the above example can be written:
+
+    product = story.imagine Product
+    employee = story.imagine Employee
+
+Moreover, the above two lines can often be skipped altogether and by replacing the few instances of `product` by `story.get(Product)` which will return the current Product (and imagine one when called for the first time).
+
+FactoryGirl is also terrible for dealing with `has_many` associations. Scheherazade is clever about these.
+
+FactoryGirl needs all factories to be created explicitly, and all attributes to be generated must also be explictly defined. Scheherazade uses convention over configuration.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'scheherazade'
+
+And then execute:
+
+    $ bundle
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Scheherazade'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/scheherazade/bare.rb

@@ -0,0 +1,3 @@
+%w[log story character_builder extension].each do |lib|
+  require_relative lib
+end

data/lib/scheherazade/character_builder.rb

@@ -0,0 +1,166 @@
+module Scheherazade
+  class CharacterBuilder < Struct.new(:character)
+    AUTO = 'Auto'  # Note: must be equal? to AUTO (i.e. same object), not just ==
+
+    def initialize(character)
+      super
+      @chain = [character]
+      while (c = story.characters[@chain.first])
+        @chain.unshift c
+      end
+      @model = @chain.first
+      story.send(:building) << @ar = @model.new
+      @chain.each{|c| story.current[c] = @ar }
+    end
+
+    # builds a character, filling required attributes,
+    # default attributes for this type of character and
+    # the attributes given.
+    #
+    # If the built object is invalid, the attributes with
+    # errors will also be filled.
+    #
+    # An invalid object may be returned. In particular, it is
+    # possible that it is only invalid because an associated
+    # model is not yet valid.
+    #
+    def build(attribute_list = nil)
+      @seq = (story.counter[@model] += 1)
+      lists = [required_attributes, *default_attribute_lists, attribute_list]
+      attribute_list = lists.map{|al| canonical(al)}.inject(:merge)
+      log(:building, attribute_list)
+      set_attributes(attribute_list)
+      unless @ar.valid?
+        attribute_list = canonical(@ar.errors.map{|attr, _| attr})
+        log(:fixing_errors, attribute_list)
+        set_attributes(attribute_list)
+      end
+      yield @ar if block_given?
+      log(:final_value, @ar)
+      @ar
+    end
+
+  private
+    def log(action, *args)
+      Scheherazade.log(action, @model, *args)
+    end
+
+    def required_attributes
+      @model.validators.select{|v| v.is_a?(ActiveModel::Validations::PresenceValidator) && v.options.empty?}
+            .flat_map(&:attributes)
+    end
+
+    def default_attribute_lists
+      story.fill_attributes.values_at(*@chain)
+    end
+
+    def set_attributes(attributes)
+      attributes.each do |attr, value|
+        set_attribute(attr, value)
+      end
+    end
+
+    def set_attribute(attribute, value = AUTO)
+      if assoc = @model.reflect_on_association(attribute)
+        # It's possible that build records are not yet valid, so we
+        # can expect errors on associations. At least for these reasons:
+        return if @ar.send(attribute).present?
+
+        value = assoc.klass.name.underscore.to_sym if value == AUTO
+        value = value_for_association(assoc, value)
+      elsif value.equal?(AUTO)
+        value = automatic_value_for_basic_attribute(attribute)
+      end
+      log :setting, attribute, value
+      @ar.send("#{attribute}=", value)
+    end
+
+    def value_for_association(assoc, associated_character)
+      log(:setting_assocation, associated_character)
+      opts = {assoc.active_record.name.underscore.to_sym => @ar} if [:has_many, :has_one].include? assoc.macro
+      ar =  if associated_character.is_a?(Symbol)
+              story.current[associated_character] || self.class.new(associated_character).build(opts)
+            else
+              associated_character
+            end
+      case assoc.macro
+      when :belongs_to
+        ar
+      when :has_and_belongs_to_many
+        [ar]
+      when :has_one
+        ar
+      when :has_many
+        if ar && ar.persisted?
+          if ar.send(assoc.active_record.name.underscore) != @ar
+            log :additional_character, assoc.name
+            [self.class.new(associated_character).build(opts)]
+          else
+            [ar]
+          end
+        else
+          [*ar]
+        end
+      end
+    end
+
+    def automatic_value_for_basic_attribute(attribute)
+      seq_string = " {#{@seq}}" if @seq > 1
+      case @model.columns_hash[attribute.to_s].try(:type)
+      when :integer  then @seq
+      when :float    then @seq
+      when :decimal  then "#{@seq}.99"
+      when :datetime then Time.now
+      when :date     then Date.today
+      when :string   then
+        case attribute
+        when :email
+          "joe#{@seq}@example.com"
+        when :name, :title
+          "Example #{@model.name.humanize}#{seq_string}"
+        else "Some #{attribute}#{seq_string}"
+        end
+      when :text     then "Some #{attribute} text#{seq_string}"
+      when :boolean  then false
+      else
+        if enum = @model.enum_definitions[attribute]
+          @model.send(attribute.to_s.pluralize).keys.first
+        else
+          puts "Unknown type for #{@model}##{attribute}"
+          nil
+        end
+      end
+    end
+
+    # Converts an attribute_list to a single Hash;
+    # some of the values may be set to AUTO.
+    #
+    #   canonical [:foo, {:bar => 42}]
+    #    # => {:foo => AUTO, :bar => 42}
+    #
+    def canonical(attribute_list)
+      case attribute_list
+      when nil then {}
+      when Hash then attribute_list
+      when Array
+        attribute_list.map! do |attributes|
+          case attributes
+          when Symbol
+            {attributes => AUTO}
+          when Hash
+            attributes
+          else
+            raise "Unexpected attributes #{attributes}"
+          end
+        end
+        attribute_list.inject({}, :merge)
+      else
+        raise "Unexpected attribute_list #{attribute_list}"
+      end
+    end
+
+    def story
+      Story.current
+    end
+  end
+end

data/lib/scheherazade/extension.rb

@@ -0,0 +1,7 @@
+module Scheherazade
+  module Extension
+    def imagine(attributes = nil)
+      story.imagine(self, attributes)
+    end
+  end
+end

data/lib/scheherazade/log.rb

@@ -0,0 +1,33 @@
+module Scheherazade
+  class Logger
+    EVENTS = [:saving, :building, :fixing_errors, :final_value, :setting_assocation, :setting, :additional_character].to_set.freeze
+
+    def off
+      @events = []
+    end
+
+    def on
+      only
+    end
+
+    def only *events_and_characters
+      events_and_characters = events_and_characters.to_set
+      @events = (EVENTS & events_and_characters).presence || EVENTS
+      @characters = (events_and_characters - @events).to_set.presence
+    end
+
+    def log(event, character, *rest)
+      if @events && @events.include?(event) && (@characters.nil? || @characters.include?(character))
+        puts "#{character}: #{rest.unshift(event).join(' | ')}"
+      end
+    end
+  end
+
+  def self.logger
+    Thread.current[:scheherazade_logger] ||= Logger.new
+  end
+
+  def self.log(*args)
+    logger.log(*args)
+  end
+end

data/lib/scheherazade/story.rb

@@ -0,0 +1,169 @@
+module Scheherazade
+  class Story < Hash
+    attr_reader :fill_attributes, :characters, :counter, :current
+
+    def self.current
+      Thread.current[:scheherazade_stories].last
+    end
+
+    # Begins a story within the current story.
+    # Should be balanced with a call to +end+
+    #
+    def self.begin
+      (Thread.current[:scheherazade_stories] ||= []).push Story.new
+      current
+    end
+
+    # Ends the current substory and comes back
+    # to the previous current story
+    #
+    def self.end(rollback = false)
+      current.send :rollback if rollback
+      Thread.current[:scheherazade_stories].pop
+      current
+    end
+
+    # Begins a substory, yields, and ends the story
+    #
+    def self.tell(opts = nil)
+      yield self.begin
+    ensure
+      self.end(opts && opts[:rollback])
+    end
+
+    def initialize(parent = self.class.current)
+      super(){|h, k| parent[k] if parent }
+      @parent = parent
+      @current = Hash.new{|h, k| parent.current[k] if parent}
+      @fill_attributes = Hash.new{|h, k| parent.fill_attributes[k] if parent }
+      @characters = Hash.new do |h, k|
+        if parent
+          parent.characters[k]
+        elsif k.is_a?(Symbol)
+          k.to_s.camelize.constantize
+        end
+      end
+      @counter = parent ? parent.counter.dup : Hash.new(0)
+      @filling = []
+      @after_imagine = {}
+      @built = []
+    end
+
+    # Creates a character with the given attributes
+    #
+    # A character can be designated either by the model (e.g. `User`), the corresponding
+    # symbol (`:user`) or the symbol for a specialized type of character, defined using +fill+
+    # (e.g. `:admin`).
+    #
+    # The attributes can be nil, a list of symbols, a hash or a combination of both
+    # These, along with attributes passed to +fill+ for the current stories
+    # and the mandatory attributes for the model will be provided.
+    #
+    # If some fields generate validation errors, they will be provided also.
+    #
+    # For associations, the values can also be a character (Symbol or Model),
+    # integers (meaning the default Model * that integer) or arrays of characters.
+    #
+    #    imagine(:user, :account, :company => :fortune_500_company, :emails => 3)
+    #
+    # Similarly:
+    #
+    #    User.imagine(...)
+    #    :user.imagine(...)
+    #
+    # This record (and any other imagined through associations) will become the
+    # current character in the current story:
+    #
+    #    story.current[User] # => nil
+    #    story.tell do
+    #      :admin.imagine # => A User record
+    #      story.current[:admin] # => same
+    #      story.current[User]   # => same
+    #    end
+    #    story.current[User] # => nil
+    #
+    def imagine(character, attributes = nil)
+      prev, @building = @building, [] # because method might be re-entrant
+      CharacterBuilder.new(character).build(attributes) do |ar|
+        ar.save!
+        # While errors on records associated with :has_many will prevent records
+        # from being saved, they won't for :belongs_to, so:
+        @building.each do |ar|
+          ar.valid? and raise ActiveRecord::RecordInvalid, ar.errors unless ar.persisted?
+        end
+        Scheherazade.log(:saving, character, ar)
+        handle_callbacks(@building)
+      end
+    ensure
+      @built.concat(@building)
+      @building = prev
+    end
+
+    def get(character)
+      current[character] || imagine(character)
+    end
+
+    def begin
+      self.class.begin
+    end
+
+    def end
+      self.class.end
+    end
+
+    def tell(opts = nil)
+      self.class.tell(opts){|story| yield story }
+    end
+
+    # Allows one to temporarily override the current characters while
+    # the given block executes
+    #
+    def with(temp_current, &block)
+      old = current.slice(*temp_current.keys)
+      current.merge!(temp_current)
+      instance_eval(&block)
+    ensure
+      current.merge!(old)
+    end
+
+    def fill(character_or_model, *with)
+      fill_attributes[character_or_model] = with
+      @characters[character_or_model] = current_fill if character_or_model.is_a? Symbol
+      begin
+        @filling.push(character_or_model)
+        yield
+      ensure
+        @filling.pop
+      end if block_given?
+    end
+
+    def after_imagine(&block)
+      raise NotImplementedError if current_fill.is_a?(Symbol)
+      @after_imagine[current_fill] = block
+    end
+
+    protected
+    def current_fill
+      @filling.last or raise "Expected to be inside a story.fill"
+    end
+
+    def handle_callbacks(on)
+      @parent.handle_callbacks(on) if @parent
+      on.each do |char|
+        if (ai = @after_imagine[char.class])
+          ai.yield(char)
+        end
+      end
+    end
+
+    def rollback
+      @built.each(&:destroy)
+    end
+
+    attr_reader :building
+    private :building
+
+  end
+end
+
+Scheherazade::Story.begin

data/lib/scheherazade/version.rb

@@ -0,0 +1,3 @@
+module Scheherazade
+  VERSION = "0.0.1"
+end

data/lib/scheherazade.rb

@@ -0,0 +1,12 @@
+require_relative "scheherazade/bare"
+
+# Scheherazade publishes a method imagine for characters:
+ActiveRecord::Base.extend Scheherazade::Extension # models
+Symbol.send :include, Scheherazade::Extension     # and symbols
+
+# as well as a global shortcut to get the current story.
+def story
+  Scheherazade::Story.current
+end
+
+# Require directly "scheherazade/bare" if you don't want these.

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: scheherazade
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Marc-André Lafortune
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: With Sheherazade's imagination and storytelling skills, fixtures can
+  be as entertaining as the “Arabian Nights”.
+email:
+- github@marc-andre.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/scheherazade/bare.rb
+- lib/scheherazade/character_builder.rb
+- lib/scheherazade/extension.rb
+- lib/scheherazade/log.rb
+- lib/scheherazade/story.rb
+- lib/scheherazade/version.rb
+- lib/scheherazade.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: http://github.com/marcandre/scheherazade
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3557737727214523228
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3557737727214523228
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Entertaining fixtures for Rails
+test_files: []