fluent_fixtures 0.0.2

data/lib/fluent_fixtures/dsl.rb

@@ -0,0 +1,106 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'fluent_fixtures' unless defined?( FluentFixtures )
+
+
+module FluentFixtures::DSL
+
+	#
+	# Accessors for extended fixture modules
+	#
+
+	##
+	# The Hash of decorators declared for this fixture module
+	attr_reader :decorators
+
+	##
+	# The name of the base fixture for the fixture module as a Symbol
+	attr_accessor :base_fixture
+
+
+	##
+	# The FluentFixtures::Collection the fixture is part of
+	attr_accessor :collection
+
+
+	#
+	# Fixture API
+	#
+
+	### Declare a base fixture for the current module called +name+, with an optional
+	### initial decorator as a +block+. If no +name+ is given, one is chosen based on the
+	### name of the declaring module.
+	def base( name=nil, &block )
+		name ||= self.collection.default_base_fixture_name( self )
+
+		self.base_fixture = name
+		self.decorators[ :_ ] = block if block
+
+		self.collection.add_base_fixture( name, self )
+	end
+
+
+	### Get/set the Class the fixture will use.
+	def fixtured_class( new_class=nil )
+		@fixtured_class = new_class if new_class
+		return @fixtured_class
+	end
+
+
+	### Declare a decorator for the fixture with the specified +name+ that will use the
+	### given +block+.
+	def decorator( name, &block )
+		self.decorators[ name.to_sym ] = block
+	end
+
+
+	### Returns +true+ if there is a decorator with the specified +name+.
+	def decorator?( name )
+		return self.decorators.key?( name.to_sym )
+	end
+	alias_method :has_decorator?, :decorator?
+
+
+	### Declare a +new_name+ for the decorator declarted with with +original_name+.
+	def alias_decorator( new_name, original_name )
+		block = self.decorators[ original_name.to_sym ] or
+			raise ScriptError, "undefined decorator %p" % [ original_name ]
+		self.decorators[ new_name.to_sym ] = block
+	end
+
+
+	### Add a callback to the fixture that will passed new instances after all
+	### decorators have been applied and immediately before it's saved. The results of
+	### the block will be used as the fixtured instance. This can be
+	### used for tables with fixed rows to use `find_or_create` or similar.
+	def before_saving( &block )
+		define_singleton_method( :call_before_saving, &block )
+	end
+
+
+	### Return an instance of Cozy::FluentFixtures::FluentFactory for the base fixture
+	### of the receiving module.
+	def factory( *args, &block )
+		return FluentFixtures::Factory.new( self, *args, &block )
+	end
+
+
+	### Return an unsaved instance of the fixtured class with the specified +args+
+	### and +block+, applying the base decorator if there is one.
+	def fixtured_instance( *args, &block )
+		fixclass = self.fixtured_class or
+			raise ScriptError, "%p doesn't declare its fixtured class!" % [ self ]
+
+		instance = fixclass.new( *args, &block )
+
+		if (( base_decorator = self.decorators[:_] ))
+			self.log.debug "Applying base decorator to %p" % [ instance ]
+			instance.instance_exec( &base_decorator )
+		end
+
+		return instance
+	end
+
+
+end # module FluentFixtures::DSL

data/lib/fluent_fixtures/factory.rb

@@ -0,0 +1,201 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability'
+require 'fluent_fixtures' unless defined?( FluentFixtures )
+
+
+# The fluent fixture monadic factory class.
+class FluentFixtures::Factory
+	extend Loggability
+
+
+	# The methods to look for to save new instances when #create is called
+	CREATE_METHODS = %i[ save_changes save ]
+
+
+	# Loggability API -- log to the FluentFixtures logger
+	log_to :fluent_fixtures
+
+
+	### Create a new FluentFactory that will act as a monadic factory for the specified
+	### +fixture_module+, and use the given +args+ in the construction of new objects.
+	def initialize( fixture_module, *args, &block )
+		@fixture_module = fixture_module
+		@constructor_args = args
+		@constructor_block = block
+		@decorators = []
+	end
+
+
+	### Copy constructor -- make a distinct copy of the clone's decorators.
+	def initialize_copy( original )
+		@decorators = @decorators.dup
+	end
+
+
+	##
+	# The fixture module that contains the decorator declarations
+	attr_reader :fixture_module
+
+	##
+	# The decorators that will be applied to the fixtured object when it's created.
+	attr_reader :decorators
+
+	##
+	# The Array of arguments to pass to the constructor when creating a new fixtured object.
+	attr_reader :constructor_args
+
+	##
+	# The block to pass to the constructor when creating a new fixtured object.
+	attr_reader :constructor_block
+
+
+	### Return a new clone of the receiver with an additional decorator composed of the
+	### specified +name+, +args+, and +block+.
+	def mutate( name, *args, &block )
+		new_instance = self.dup
+		new_instance.decorators << [ name, args, block ]
+		return new_instance
+	end
+
+
+	### Create an instance, apply declared decorators in order, and return the resulting
+	### object.
+	def instance( *args, &block )
+		instance = self.fixture_module.
+			fixtured_instance( *self.constructor_args, &self.constructor_block )
+
+		self.decorators.each do |decorator_name, args, block|
+			# :TODO: Reify other fixtures in `args` here?
+			if !decorator_name
+				self.apply_inline_decorator( instance, block )
+			elsif self.fixture_module.decorators.key?( decorator_name )
+				self.apply_named_decorator( instance, args, decorator_name )
+			else
+				self.apply_method_decorator( instance, args, decorator_name, block )
+			end
+		end
+
+		# If the factory was called with a block, use it as a final decorator before
+		# returning it.
+		if block
+			self.log.debug "Applying inline decorator %p" % [ block ]
+			if block.arity.zero?
+				instance.instance_exec( *args, &block )
+			else
+				block.call( instance, *args )
+			end
+		end
+
+		return instance
+	end
+
+
+	### Return a saved #instance of the fixtured object.
+	def create( *args, &block )
+		obj = self.with_transaction do
+			obj = self.instance( *args, &block )
+			obj = self.fixture_module.call_before_saving( obj ) if
+				self.fixture_module.respond_to?( :call_before_saving )
+
+			self.try_to_save( obj )
+
+			obj
+		end
+
+		return obj
+	end
+
+
+	### Return a copy of the factory that will apply the specified +block+ as a decorator.
+	def decorated_with( &block )
+		return self.mutate( nil, &block )
+	end
+
+
+	### Return a human-readable representation of the object suitable for debugging.
+	def inspect
+		decorator_description = self.decorators.map( &:first ).join( ' + ' )
+
+		return "#<%p:%0#16x for %p%s>" % [
+			self.class,
+			self.__id__ * 2,
+			self.fixture_module,
+			decorator_description.empty? ? '' : ' + ' + decorator_description
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Apply a decorator +block+ added to the factory via #decorated_with to the +instance+.
+	def apply_inline_decorator( instance, block )
+		self.log.debug "Applying anonymous inline decorator %p" % [ block ]
+		if block.arity.nonzero?
+			block.call( instance )
+		else
+			instance.instance_eval( &block )
+		end
+	end
+
+
+	### Apply a decorator declared in the fixture module by the given
+	### +decorator_name+ to the specified +instance+.
+	def apply_named_decorator( instance, args, decorator_name )
+		decorator_block = self.fixture_module.decorators[ decorator_name ]
+		self.log.debug "Applying decorator %p (%p) to a %p with args: %p" %
+			[ decorator_name, decorator_block, instance.class, args ]
+		instance.instance_exec( *args, &decorator_block )
+	end
+
+
+	### Apply a decorator declared by calling the proxy method with the specified
+	### +name+, +args+, and +block+ to the given +instance+.
+	def apply_method_decorator( instance, args, name, block )
+		self.log.debug "Mutating instance %p with regular method %p( %p, %p )" %
+			[ instance, name, args, block ]
+		if block
+			instance.public_send( name, *args )
+		else
+			instance.public_send( name, *args, &block )
+		end
+	end
+
+
+	### Look for common transaction mechanisms on the fixtured class, and wrap one of
+	### them around the +block+ if one exists. If no transaction mechanism can be found,
+	### just yield to the block.
+	def with_transaction( &block )
+		fixtured_class = self.fixture_module.fixtured_class
+		if fixtured_class.respond_to?( :db )
+			self.log.debug "Using db.transaction for creation."
+			return fixtured_class.db.transaction( &block )
+		else
+			yield
+		end
+	end
+
+
+	### Try various methods for saving the given +object+, logging a warning if it doesn't
+	### respond to any of them.
+	def try_to_save( object )
+		CREATE_METHODS.each do |methodname|
+			return object.public_send( methodname ) if object.respond_to?( methodname )
+		end
+
+		self.log.warn "create: don't know how to save %p" % [ object ]
+	end
+
+
+	### Proxy method -- look up the decorator with the same name as the method being called,
+	### and if one is found, returned a new instance of the factory with the additional
+	### decorator.
+	def method_missing( sym, *args, &block )
+		return self.mutate( sym, *args, &block )
+	end
+
+end # class FluentFixtures::Factory
+

data/lib/fluent_fixtures.rb

@@ -0,0 +1,29 @@
+# -*- ruby -*-
+#encoding: utf-8
+# frozen_string_literal: true
+
+require 'loggability'
+
+
+# Fluent fixtures
+module FluentFixtures
+	extend Loggability
+
+
+	# Package version
+	VERSION = '0.0.2'
+
+	# Version control revision
+	REVISION = %q$Revision: e500071dd9c0 $
+
+
+	# Loggability API -- set up a named logger
+	log_as :fluent_fixtures
+
+
+	require 'fluent_fixtures/collection'
+	require 'fluent_fixtures/dsl'
+	require 'fluent_fixtures/factory'
+
+end # module FluentFixtures
+

data/spec/fluent_fixtures/collection_spec.rb

@@ -0,0 +1,145 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../spec_helper'
+
+require 'fluent_fixtures/collection'
+
+
+describe FluentFixtures::Collection do
+
+	let( :collection ) do
+		mod = Module.new
+		mod.extend( described_class )
+		mod
+	end
+
+
+	it "registers its fixture modules when they are extended if they have a name" do
+		mod = Module.new do
+			def self::name; "NamedFixture"; end
+		end
+		mod.extend( collection )
+
+		expect( collection.modules ).to include( namedfixture: mod )
+	end
+
+
+	it "registers its fixture modules when they declare a base if they are anonymous" do
+		mod = Module.new
+		mod.extend( collection )
+
+		expect( collection.modules ).to be_empty
+
+		mod.base( :namedfixture )
+
+		expect( collection.modules ).to include( namedfixture: mod )
+	end
+
+
+	it "generates a factory constructor for the fixture when it regsters a base" do
+		mod = Module.new
+		mod.extend( collection )
+		mod.base( :new_fixture )
+
+		expect( collection ).to respond_to( :new_fixture )
+		expect( collection.new_fixture ).to be_a( FluentFixtures::Factory )
+		expect( collection.new_fixture.fixture_module ).to be( mod )
+	end
+
+
+	it "raises if two base fixtures are registered with the same name" do
+		mod1 = Module.new
+		mod1.extend( collection )
+
+		mod2 = Module.new
+		mod2.extend( collection )
+
+		mod1.base( :base_fixture )
+
+		expect {
+			mod2.base( :base_fixture )
+		}.to raise_error( ScriptError, /already have a base fixture.*base_fixture/i )
+	end
+
+
+	it "can be reset, removing all of its registered fixture modules and their factory methods" do
+		mod1 = Module.new
+		mod1.extend( collection )
+
+		mod2 = Module.new
+		mod2.extend( collection )
+
+		mod1.base( :fixture1 )
+		mod2.base( :fixture2 )
+
+		expect( collection.modules ).to include( fixture1: mod1, fixture2: mod2 )
+		expect( collection ).to respond_to( :fixture1 )
+		expect( collection ).to respond_to( :fixture2 )
+
+		collection.reset!
+
+		expect( collection.modules ).to be_empty
+		expect( collection ).to_not respond_to( :fixture1 )
+		expect( collection ).to_not respond_to( :fixture2 )
+	end
+
+
+	it "can load fixtures by name" do
+		# Mocking Kernel.require via the class under test
+		expect( collection ).to receive( :require ).
+			with( "fixtures/foo" ).and_return( false )
+		expect( collection ).to receive( :require ).
+			with( "fixtures/bar" ).and_return( false )
+
+		collection.load( :foo, :bar )
+	end
+
+
+	it "can load all fixtures" do
+		expect( Gem ).to receive( :find_files ).with( "fixtures/*.rb" ).and_return([
+			"fixtures/foo.rb",
+			"fixtures/bar.rb",
+			"fixtures/baz.rb"
+		])
+
+		# Mocking Kernel.require via the class under test
+		expect( collection ).to receive( :require ).
+			with( "fixtures/foo" ).and_return( false )
+		expect( collection ).to receive( :require ).
+			with( "fixtures/bar" ).and_return( false )
+		expect( collection ).to receive( :require ).
+			with( "fixtures/baz" ).and_return( false )
+
+		collection.load_all
+	end
+
+
+	it "allows the loading prefix to be customized" do
+		collection.fixture_path_prefix( 'acme/fixtures' )
+		expect( collection ).to receive( :require ).
+			with( "acme/fixtures/foo" ).and_return( false )
+
+		collection.load( :foo )
+	end
+
+
+	describe "fixture extension" do
+
+		let( :extending_module ) do
+			mod = Module.new do
+				def self::name ; "CollectionTests"; end
+			end
+			mod.extend( collection )
+			mod
+		end
+
+
+		it "adds instance data to its fixture modules" do
+			expect( extending_module.decorators ).to be_a( Hash )
+		end
+
+	end
+
+
+end
+