lib/fixture_dependencies/active_record.rb lib/fixture_dependencies/sequel.rb lib/fixture_dependencies/test_unit.rb lib/fixture_dependencies/test_unit/rails.rb lib/fixture_dependencies/test_unit/sequel.rb @@ -1,4 +1,4 @@ -Copyright (c) 2007 Jeremy Evans +Copyright (c) 2007-2008 Jeremy Evans Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal LICENSE @@ -1,31 +1,74 @@ -fixture_dependencies is a plugin that changes the way Rails uses fixtures in -the following ways: - -- Fixtures can specify associations instead of foreign keys -- Supports belongs_to, has_many, has_one, and habtm associations -- Loads a fixture's dependencies (associations with other fixtures) before the - fixture itself so that foreign key constraints aren't violated -- Can specify individual fixtures to load per test or test suite -- Loads fixtures on every test inside a transaction, so fixture information - is never left in your database += fixture_dependencies + +fixture_dependencies is an advanced fixture loader, allowing the loading of +models from YAML fixtures, along with their entire dependency graph. It has +the following features: + +- Fixtures specify association names instead of foreign keys +- Support both Sequel and ActiveRecord +- Supports many_to_one/belongs_to, one_to_many/has_many, + many_to_many/has_and_belongs_to_many, and has_one associations +- Loads a fixture's dependency graph in such a manner that foreign key + constraints aren't violated +- Has a very simple API (FixtureDependencies.load(:model__fixture)) - Handles almost all cyclic dependencies +- Includes Rails and Sequel test helpers for Test::Unit that load fixtures for + every test inside a transaction, so fixture data is never left in your + database -To use, first install the plugin, then add the following to -test/test_helper.rb after "require 'test_help'": +== Installation - require 'fixture_dependencies_test_help' + sudo gem install jeremyevans-fixture_dependencies \ + --source http://gems.github.com + +== Source + +Source is available via github: + + http://github.com/jeremyevans/fixture_dependencies + +You can check it out with git: + + git clone git://github.com/jeremyevans/fixture_dependencies.git + +== Usage + +=== With Rails/ActiveRecord/Test::Unit: + +Add the following to test/test_helper.rb after "require 'test_help'": + + require 'fixture_dependencies/test_unit/rails' This overrides the default test helper to load the fixtures inside transactions and to use FixtureDependencies to load the fixtures. -fixture_dependencies is available via github: +=== With Sequel/Test::Unit: + +Somewhere before the test code is loaded: + + require 'fixture_dependencies/test_unit/sequel' + +Make sure the test case classes use FixtureDependencies::SequelTestCase: + + class ModelTest < FixtureDependencies::SequelTestCase - http://github.com/jeremyevans/fixture_dependencies/tree/master +This runs the test cases inside a Sequel transaction. -Changes to Fixtures: +=== With other testing libraries: + +You can just use FixtureDependencies.load to handle the loading of fixtures. +The use of transactions is up to you. It's fairly easy to add support for +running RSpec examples inside transactions. One thing you must do if you are +not using the rails test helper is to set the fixture path for +FixtureDependencies: + + FixtureDependencies.fixture_path = '/path/to/fixtures' + +== Changes to Rails default fixtures: fixture_dependencies is designed to require the least possible changes to -fixtures. For example, see the following changes: +the default YAML fixtures used by Rails (well, at least Rails 1.2 and earlier). +For example, see the following changes: OLD NEW asset1: asset1: @@ -42,7 +85,7 @@ nx7010, and a vendors fixture with the name lxg_computers. Fixture files still use the table_name of the model. -Changes to the fixtures Class Method: +== Changes to the fixtures Class Method: fixture_dependencies can still use the fixtures class method in your test: @@ -54,12 +97,11 @@ In Rails default testing practices, the arguments to fixtures are table names. fixture_dependencies changes this to underscored model names. If you are using Rails' recommended table practices, this shouldn't make a difference. -Another change is that Rails defaults allow you to specify habtm join tables in -fixtures. That doesn't work with fixture dependencies, as there is no -associated model. Instead, you use a has_and_belongs_to_many association name -in the the appropriate model fixtures (see below). +It is recommended that you do not use the fixtures method, and instead load +individual fixtures as needed (see below). This makes your tests much more +robust, in case you want to add or remove individual fixtures at a later date. -Loading Individual Fixtures with fixtures class method: +== Loading individual fixtures with fixtures class method There is support for loading individual fixtures (and just their dependencies), using the following syntax: @@ -69,9 +111,11 @@ using the following syntax: end This would load just the jeremy fixture and its dependencies. I find this is -much better than loading all fixtures in most of my test suites. +much better than loading all fixtures in most of my test suites. Even better +is loading just the fixtures you want instead every test method (see below). +This leads to the most robust testing. -Loading Fixtures Inside Test Methods: +== Loading fixtures inside test methods I find that it is often better to skip the use of the fixtures method entirely, and load the fixtures I want manually in each test method. This provides for @@ -86,7 +130,7 @@ the loosest coupling possible. Here's an example: def test_award_statistics # Load all fixtures in both tables - load(:employee_awards, :awards) + load(:employee_award__jeremy_first, :award__first) # Test the award_statistics method # (which pulls data from the tables loaded above) end @@ -95,7 +139,7 @@ the loosest coupling possible. Here's an example: Don't worry about loading the same fixture twice, if a fixture is already loaded, it won't attempt to load it again. -has_* Assocations in Fixtures: +== one_to_many/many_to_many/has_many/has_and_belongs_to_many assocations Here's an example of using has_one (logon_information), has_many (assets), and has_and_belongs_to_many (groups) associations. @@ -120,7 +164,14 @@ groups in the order specified (and their dependencies...). Note that there is only a load order inside a specific association, associations are stored in the same hash as attributes and are loaded in an arbitrary order. -Cyclic Dependencies: +== many_to_many/has_and_belongs_to_many join table fixtures + +Another change is that Rails defaults allow you to specify habtm join tables in +fixtures. That doesn't work with fixture dependencies, as there is no +associated model. Instead, you use a has_and_belongs_to_many association name +in the the appropriate model fixtures (see above). + +== Cyclic dependencies fixture_dependencies handles almost all cyclic dependencies. It handles all has_many, has_one, and habtm cyclic dependencies. It handles all @@ -145,9 +196,9 @@ division belongs_to head_of_division when the employee is a member of the division and also the head of the division), even that approach is not possible. -Known Issues: +== Known issues -Currently, the plugin only supports yaml fixtures, but other types of fixtures +Currently, the plugin only supports YAML fixtures, but other types of fixtures would be fairly easy to add (send me a patch if you add support for another fixture type). @@ -161,32 +212,31 @@ was rolled back in r2730 due to speed issues. See ticket #2404 on Rails' trac. Instantiated fixtures are not available with this plugin. Instead, you should use load(:model__fixture_name). -Troubleshooting: +== Troubleshooting If you run into problems with loading your fixtures, it can be difficult to see where the problems are. To aid in debugging an error, add the following to test/test_helper.rb: - FixtureDependencies.verbose = 2 + FixtureDependencies.verbose = 3 This will give a verbose description of the loading and saving of fixtures for -every test, including the recursive loading of all dependencies. +every test, including the recursive loading of the dependency graph. + +== Similar Ideas -Similar Ideas: +Rails now supports something similar by default. Honestly, I'm not sure what +the differences are. fixture_references is a similar plugin. It uses erb inside yaml, and uses the foreign key numbers inside of the association names, which leads me to believe it doesn't support has_* associations. -Ticket #6424 on the Rails' trac also implements a similar idea, but it parses -the associations and changes them to foreign keys, which leads me to believe it -doesn't support has_* associations either. - -License: +== License fixture_dependencies is released under the MIT License. See the LICENSE file for details. -Author: +== Author Jeremy Evans <code@jeremyevans.net> README @@ -2,12 +2,14 @@ require 'rake' require 'rake/clean' require 'rake/rdoctask' +CLEAN.include ["rdoc"] + Rake::RDocTask.new do |rdoc| rdoc.rdoc_dir = "rdoc" rdoc.options += ["--quiet", "--line-numbers", "--inline-source"] rdoc.main = "README" rdoc.title = "fixture_dependencies: Rails fixture loading that works with foreign keys" - rdoc.rdoc_files.add ["README", "LICENSE", "lib/fixture_dependencies.rb", "lib/fixture_dependencies_test_help.rb"] + rdoc.rdoc_files.add ["README", "LICENSE", "lib/**/*.rb"] end desc "Package fixture_dependencies" Rakefile @@ -1,11 +1,11 @@ spec = Gem::Specification.new do |s| s.name = "fixture_dependencies" - s.version = "1.0.0" + s.version = "1.1.0" s.author = "Jeremy Evans" s.email = "code@jeremyevans.net" s.platform = Gem::Platform::RUBY - s.summary = "Rails fixture loading that works with foreign keys" - s.files = ["README", "LICENSE", "lib/fixture_dependencies.rb", "lib/fixture_dependencies_test_help.rb"] + s.summary = "Sequel/ActiveRecord fixture loader that handles dependency graphs" + s.files = ["README", "LICENSE", "lib/fixture_dependencies.rb", "lib/fixture_dependencies_test_help.rb", "lib/fixture_dependencies/sequel.rb", "lib/fixture_dependencies/active_record.rb", "lib/fixture_dependencies/test_unit.rb", "lib/fixture_dependencies/test_unit/rails.rb", "lib/fixture_dependencies/test_unit/sequel.rb"] s.extra_rdoc_files = ["LICENSE"] s.require_paths = ["lib"] s.has_rdoc = true fixture_dependencies.gemspec @@ -2,156 +2,183 @@ class FixtureDependencies @fixtures = {} @loaded = {} @verbose = 0 - class << self - attr_reader :fixtures, :loaded - attr_accessor :verbose - # Load all record arguments into the database. If a single argument is - # given and it corresponds to a single fixture, return the the model - # instance corresponding to that fixture. If a single argument if given - # and it corresponds to a model, return all model instances corresponding - # to that model. If multiple arguments are given, return a list of - # model instances (for single fixture arguments) or list of model instances - # (for model fixture arguments). If no arguments, return the empty list. - # - # This will load the data from the yaml files for each argument whose model - # is not already in the fixture hash. - def load(*records) - ret = records.collect do |record| - model_name, name = split_name(record) - if name - use(record.to_sym) - else - model_name = model_name.singularize - unless loaded[model_name.to_sym] - puts "loading #{model_name}.yml" if verbose > 0 - load_yaml(model_name) - end - fixtures[model_name.to_sym].keys.collect{|name| use("#{model_name}__#{name}".to_sym)} + + # Load all record arguments into the database. If a single argument is + # given and it corresponds to a single fixture, return the the model + # instance corresponding to that fixture. If a single argument if given + # and it corresponds to a model, return all model instances corresponding + # to that model. If multiple arguments are given, return a list of + # model instances (for single fixture arguments) or list of model instances + # (for model fixture arguments). If no arguments, return the empty list. + # + # This will load the data from the yaml files for each argument whose model + # is not already in the fixture hash. + def self.load(*records) + ret = records.collect do |record| + model_name, name = split_name(record) + if name + use(record.to_sym) + else + model_name = model_name.singularize + unless loaded[model_name.to_sym] + puts "loading #{model_name}.yml" if verbose > 0 + load_yaml(model_name) end + fixtures[model_name.to_sym].keys.collect{|name| use("#{model_name}__#{name}".to_sym)} end - records.length == 1 ? ret[0] : ret end + records.length == 1 ? ret[0] : ret + end +end + +require 'fixture_dependencies/active_record' if defined?(ActiveRecord::Base) +require 'fixture_dependencies/sequel' if defined?(Sequel::Model) + + +class << FixtureDependencies + attr_reader :fixtures, :loaded + attr_accessor :verbose, :fixture_path + + private - private - # Add a fixture to the fixture hash (does not add to the database, - # just makes it available to be add to the database via use). - def add(model_name, name, attributes) - (fixtures[model_name.to_sym]||={})[name.to_sym] = attributes - end - - # Get the model instance that already exists in the database using - # the fixture name. - def get(record) - model_name, name = split_name(record) - model = model_name.camelize.constantize - model.find(fixtures[model_name.to_sym][name.to_sym][model.primary_key.to_sym]) - end - - # Adds all fixtures in the yaml fixture file for the model to the fixtures - # hash (does not add them to the database, see add). - def load_yaml(model_name) - YAML.load(File.read(File.join(Test::Unit::TestCase.fixture_path, "#{model_name.camelize.constantize.table_name}.yml"))).each do |name, attributes| - symbol_attrs = {} - attributes.each{|k,v| symbol_attrs[k.to_sym] = v} - add(model_name.to_sym, name, symbol_attrs) - end - loaded[model_name.to_sym] = true - end - - # Split the fixture name into the name of the model and the name of - # the individual fixture. - def split_name(name) - name.to_s.split('__', 2) - end - - # Load the individual fixture into the database, by loading all necessary - # belongs_to dependencies before saving the model, and all has_* - # dependencies after saving the model. If the model already exists in - # the database, return it. Will check the yaml file for fixtures if no - # fixtures yet exist for the model. If the fixture isn't in the fixture - # hash, raise an error. - def use(record, loading = [], procs = {}) - spaces = " " * loading.length - puts "#{spaces}using #{record}" if verbose > 0 - puts "#{spaces}load stack:#{loading.inspect}" if verbose > 1 - loading.push(record) - model_name, name = split_name(record) - model = model_name.camelize.constantize - unless loaded[model_name.to_sym] - puts "#{spaces}loading #{model.table_name}.yml" if verbose > 0 - load_yaml(model_name) - end - raise ActiveRecord::RecordNotFound, "Couldn't use fixture #{record.inspect}" unless attributes = fixtures[model_name.to_sym][name.to_sym] - # return if object has already been loaded into the database - if existing_obj = model.send("find_by_#{model.primary_key}", attributes[model.primary_key.to_sym]) - return existing_obj - end - obj = model.new - many_associations = [] - attributes.each do |attr, value| - if reflection = model.reflect_on_association(attr.to_sym) - if reflection.macro == :belongs_to - dep_name = "#{reflection.klass.name.underscore}__#{value}".to_sym - if dep_name == record - # Self referential record, use primary key - puts "#{spaces}#{record}.#{attr}: belongs_to self-referential" if verbose > 1 - attr = reflection.options[:foreign_key] || reflection.klass.table_name.classify.foreign_key - value = attributes[model.primary_key.to_sym] - elsif loading.include?(dep_name) - # Association cycle detected, set foreign key for this model afterward using procs - # This is will fail if the column is set to not null or validates_presence_of - puts "#{spaces}#{record}.#{attr}: belongs-to cycle detected:#{dep_name}" if verbose > 1 - (procs[dep_name] ||= []) << Proc.new do |assoc| - m = model.find(attributes[model.primary_key.to_sym]) - m.send("#{attr}=", assoc) - m.save! - end - value = nil - else - # Regular assocation, load it - puts "#{spaces}#{record}.#{attr}: belongs_to:#{dep_name}" if verbose > 1 - use(dep_name, loading, procs) - value = get(dep_name) - end - elsif - many_associations << [attr, reflection, reflection.macro == :has_one ? [value] : value] - next + # Add a fixture to the fixture hash (does not add to the database, + # just makes it available to be add to the database via use). + def add(model_name, name, attributes) + (fixtures[model_name.to_sym]||={})[name.to_sym] = attributes + end + + # Get the model instance that already exists in the database using + # the fixture name. + def get(record) + model_name, name = split_name(record) + model = model_name.camelize.constantize + model_method(:model_find, model_type(model), model, fixtures[model_name.to_sym][name.to_sym][model.primary_key.to_sym]) + end + + # Adds all fixtures in the yaml fixture file for the model to the fixtures + # hash (does not add them to the database, see add). + def load_yaml(model_name) + raise(ArgumentError, "No fixture_path set. Use FixtureDependencies.fixture_path = ...") unless fixture_path + YAML.load(File.read(File.join(fixture_path, "#{model_name.camelize.constantize.table_name}.yml"))).each do |name, attributes| + symbol_attrs = {} + attributes.each{|k,v| symbol_attrs[k.to_sym] = v} + add(model_name.to_sym, name, symbol_attrs) + end + loaded[model_name.to_sym] = true + end + + # Delegate to the correct method based on mtype + def model_method(meth, mtype, *args, &block) + send("#{meth}_#{mtype}", *args, &block) + end + + # A symbol representing the base class of the model, currently + # ActiveRecord::Base and Sequel::Model are supported. + def model_type(model) + if model.ancestors.map{|x| x.to_s}.include?('ActiveRecord::Base') + :AR + elsif model.ancestors.map{|x| x.to_s}.include?('Sequel::Model') + :S + else + raise TypeError, 'not ActiveRecord or Sequel model' + end + end + + # Split the fixture name into the name of the model and the name of + # the individual fixture. + def split_name(name) + name.to_s.split('__', 2) + end + + # Load the individual fixture into the database, by loading all necessary + # belongs_to dependencies before saving the model, and all has_* + # dependencies after saving the model. If the model already exists in + # the database, return it. Will check the yaml file for fixtures if no + # fixtures yet exist for the model. If the fixture isn't in the fixture + # hash, raise an error. + def use(record, loading = [], procs = {}) + spaces = " " * loading.length + puts "#{spaces}using #{record}" if verbose > 0 + puts "#{spaces}load stack:#{loading.inspect}" if verbose > 1 + loading.push(record) + model_name, name = split_name(record) + model = model_name.camelize.constantize + unless loaded[model_name.to_sym] + puts "#{spaces}loading #{model.table_name}.yml" if verbose > 0 + load_yaml(model_name) + end + mtype = model_type(model) + model_method(:raise_model_error, mtype, "Couldn't use fixture #{record.inspect}") unless attributes = fixtures[model_name.to_sym][name.to_sym] + # return if object has already been loaded into the database + if existing_obj = model_method(:model_find_by_pk, mtype, model, attributes[model.primary_key.to_sym]) + puts "#{spaces}using #{record}: already in database" if verbose > 2 + return existing_obj + end + obj = model.new + many_associations = [] + attributes.each do |attr, value| + if reflection = model_method(:reflection, mtype, model, attr.to_sym) + if [:belongs_to, :many_to_one].include?(model_method(:reflection_type, mtype, reflection)) + dep_name = "#{model_method(:reflection_class, mtype, reflection).name.underscore}__#{value}".to_sym + if dep_name == record + # Self referential record, use primary key + puts "#{spaces}#{record}.#{attr}: belongs_to self-referential" if verbose > 1 + attr = model_method(:reflection_key, mtype, reflection) + value = attributes[model.primary_key.to_sym] + elsif loading.include?(dep_name) + # Association cycle detected, set foreign key for this model afterward using procs + # This is will fail if the column is set to not null or validates_presence_of + puts "#{spaces}#{record}.#{attr}: belongs-to cycle detected:#{dep_name}" if verbose > 1 + (procs[dep_name] ||= []) << Proc.new do |assoc| + m = model_method(:model_find, mtype, model, attributes[model.primary_key.to_sym]) + m.send("#{attr}=", assoc) + model_method(:model_save, mtype, m) end + value = nil + else + # Regular assocation, load it + puts "#{spaces}#{record}.#{attr}: belongs_to:#{dep_name}" if verbose > 1 + use(dep_name, loading, procs) + value = get(dep_name) end - obj.send("#{attr}=", value) - end - puts "#{spaces}saving #{record}" if verbose > 1 - obj.save! - loading.pop - # Update the circular references - if procs[record] - procs[record].each{|p| p.call(obj)} - procs.delete(record) + elsif + many_associations << [attr, reflection, model_method(:reflection_type, mtype, reflection) == :has_one ? [value] : value] + next end - # Update the has_many and habtm associations - many_associations.each do |attr, reflection, values| - proxy = obj.send(attr) - values.each do |value| - dep_name = "#{reflection.klass.name.underscore}__#{value}".to_sym - if dep_name == record - # Self referential, add association - puts "#{spaces}#{record}.#{attr}: #{reflection.macro} self-referential" if verbose > 1 - reflection.macro == :has_one ? (proxy = obj) : (proxy << obj) - elsif loading.include?(dep_name) - # Cycle Detected, add association to this object after saving other object - puts "#{spaces}#{record}.#{attr}: #{reflection.macro} cycle detected:#{dep_name}" if verbose > 1 - (procs[dep_name] ||= []) << Proc.new do |assoc| - reflection.macro == :has_one ? (proxy = assoc) : (proxy << assoc unless proxy.include?(assoc)) - end - else - # Regular association, add it - puts "#{spaces}#{record}.#{attr}: #{reflection.macro}:#{dep_name}" if verbose > 1 - assoc = use(dep_name, loading, procs) - reflection.macro == :has_one ? (proxy = assoc) : (proxy << assoc unless proxy.include?(assoc)) - end + end + puts "#{spaces}#{record}.#{attr} = #{value.inspect}" if verbose > 2 + obj.send("#{attr}=", value) + end + puts "#{spaces}saving #{record}" if verbose > 1 + model_method(:model_save, mtype, obj) + loading.pop + # Update the circular references + if procs[record] + procs[record].each{|p| p.call(obj)} + procs.delete(record) + end + # Update the has_many and habtm associations + many_associations.each do |attr, reflection, values| + values.each do |value| + dep_name = "#{model_method(:reflection_class, mtype, reflection).name.underscore}__#{value}".to_sym + rtype = model_method(:reflection_type, mtype, reflection) if verbose > 1 + if dep_name == record + # Self referential, add association + puts "#{spaces}#{record}.#{attr}: #{rtype} self-referential" if verbose > 1 + model_method(:add_associated_object, mtype, reflection, attr, obj, obj) + elsif loading.include?(dep_name) + # Cycle Detected, add association to this object after saving other object + puts "#{spaces}#{record}.#{attr}: #{rtype} cycle detected:#{dep_name}" if verbose > 1 + (procs[dep_name] ||= []) << Proc.new do |assoc| + model_method(:add_associated_object, mtype, reflection, attr, obj, assoc) end + else + # Regular association, add it + puts "#{spaces}#{record}.#{attr}: #{rtype}:#{dep_name}" if verbose > 1 + model_method(:add_associated_object, mtype, reflection, attr, obj, use(dep_name, loading, procs)) end - obj end + end + obj end end lib/fixture_dependencies.rb @@ -1,34 +1 @@ -module Test - module Unit - class TestCase - class << self - alias_method :stupid_method_added, :method_added - end - def self.method_added(x) - end - - # Load fixtures using FixtureDependencies inside a transaction - def setup_with_fixtures - ActiveRecord::Base.send :increment_open_transactions - ActiveRecord::Base.connection.begin_db_transaction - load_fixtures - end - alias_method :setup, :setup_with_fixtures - - class << self - alias_method :method_added, :stupid_method_added - end - - private - # Load fixtures named with the fixtures class method - def load_fixtures - load(*fixture_table_names) - end - - # Load given fixtures using FixtureDependencies - def load(*fixture) - FixtureDependencies.load(*fixture) - end - end - end -end +require 'fixture_dependencies/test_unit/rails' lib/fixture_dependencies_test_help.rb init.rb bda31cc0049276df463b860a879bfaa5d3cf20c8 Jeremy Evans code@jeremyevans.net http://github.com/jeremyevans/fixture_dependencies/commit/63025e78b19cfc0970a443f97f22cf6ac82dfdce 63025e78b19cfc0970a443f97f22cf6ac82dfdce 2008-08-25T15:03:11-07:00 2008-08-25T15:03:11-07:00 Allow use of Sequel in addition to ActiveRecord - Allow fixture_path to be set, only set by default when using rails helper - Update README, use better RDoc format - Add rdoc directory to clean task - Add 2008 to copyright year - Bump version to 1.1.0 345b8bc59ff8d4193520648960c8e18ef0705e83 Jeremy Evans code@jeremyevans.net