contributions.rdoc philosophy_and_bugs.rdoc @@ -13,9 +13,34 @@ to omit extraneous details and focus only on the attributes that are important f particular behaviour. It works well with both RSpec[http://rspec.rubyforge.org/] and Test::Unit[http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html]. -=== What's new since 2.0: +== What's new since 2.0: -See the CHANGELOG +* default_* is gone in favor of new_*. +* Cyclic dependencies are no longer an issue. The "overrides hash" (the hash passed to new_* or create_*) can now be processed. + +See CHANGELOG.rdoc + test suite for further changes. + +== Installation + +Install the plugin: + + git://github.com/smtlaissezfaire/fixturereplacement.git + +=== Using it with RSpec + +Add the following to your <tt>spec/spec_helper.rb</tt> file, in the configuration section: + + Spec::Runner.configure do |config| + config.include FixtureReplacement + end + +=== Using it with Test::Unit + +Add the following to your <tt>test/test_helper.rb</tt> file: + + class Test::Unit::TestCase + include FixtureReplacement + end == How to use FixtureReplacement @@ -85,146 +110,6 @@ will assign the field as if it wasn't protected, which is convenient for testing user = create_user(:username => "scott", :admin_status => true) user.admin_status # => true -== Motivation Behind FixtureReplacement - -As Dan Manges has outlined in his blog post, "Fixing Fixtures with Factory" (http://www.dcmanges.com/blog/38), -this approach to generating test data has a number of advantages: - -- The factory provides default values and relationships -- Invalid data will never be loaded into your test database, as it is with the typical YAML fixture. - A record which is created with a create_* method (create_user, create_post, etc.) uses ActiveRecord's - create! behind the scenes, so any invalid data will raise a clear error. This means that you will - spend your time debugging your tests and code, not your test data. -- It's in Ruby, so you won't have to fight with YAML's spacing issues, plus the data is by nature - more dynamic and more agile. -- When a test fails (and they will), someone who hasn't written the test will be able to figure out - the *intention* behind the test. They won't have to go digging through YAML files to figure out - the relevant data to the test. -- No more opening of 5 different YAML files to see the associations and column names of different models - - this is conveniently located in one file (db/example_data.rb) -- If you set use_transactional_fixtures = true in your test_helper or spec_helper (and you *really* should - be using this), the data that is created in each test will be rolled back, meaning no-side effects, - and a consistent database among different developers, and for your self during different test runs. - - -=== Random Data in db/example_data.rb - -The use of random data should also be spoken of. Many may think this to be dangerous, but in fact random -data is often helpful. Consider the following snippets of psudo-code (along with it's test): - - # apps/models/user.rb : - # ---------------------- - - class User < ActiveRecord::Base - validates_uniqueness_of :username - validates_presence_of :password - - after_create :check_password - - private - - def check_password - # ... - end - - public - - def establish_friendship_with(other_user) - # ... - end - - def friends - # ... - end - end - - - # The test: - # --------- - - def test_make_sure_user_can_establish_friendship - @user_one = User.create({ - :username => "foo", - :password => "some password", - :password_confirmation => "some password_confirmation" - }) - @user_two = User.create({ - :username => "bar", - :password => "some password", - :password_confirmation => "some password confirmation" - }) - - @user_one.establish_friendship_with(@user_two) - @user_one.friends.should == [@user_two] - end - -Notice that the above test adds a lot of extra noise in getting valid users into the database; The test, however, doesn't care what the usernames are, that the password is a good one, that the password matches the password confirmation, and so on. The point of the test is not to check those things, but rather that a friendship can be established. - -Here would be a similar test with the FixtureReplacement: - - # The test: - # --------- - - before :each do - @user_one = create_user - @user_two = create_user - end - - def test_make_sure_user_can_establish_friendship - @user_one.establish_friendship_with(@user_two) - @user_one.friends.should == [@user_two] - end - -Once again, the test above doesn't care about usernames, so why should you? But to even store those two users into the database, you will need unique usernames, as well as password which match. Here is where the random data comes in: - - # db/example_data.rb - # ------------------- - - module FixtureReplacement - - attributes_for :user do |u| - password = random_string - - u.username = random_string - u.password = password - u.password_confirmation = password - end - - end - -Now, in a different test case, if you do care about the usernames not being random, it is easy to set them: - - create_user({ - :username => "scott", - :password => "foobar", - :password_confirmation => "foobar" - }) - - - -=== Disadvantages of FixtureReplacement - -The one major disadvantage behind this approach is that it's slow - just as slow as fixtures, if not slower. -One approach that the rspec crowd is using is to use this plugin in integration tests, while using mocks & stubs -in model unit tests. It's not a big deal if your integration tests run slow, since you probably don't run -them very often. - -Another approach is to look to external sources to speed up your test suite: - -- a sqlite3 in-memory database (can cut your test/spec time in half) -- unit-record gem (by Dan Manges), which takes advantage of multi-core processors -- a distributed build system, such as spec_distributed -- running tests individually, or per file -- A faster machine - -If you have other ideas for speeding up your test suite, I'm all ears. - -== Installation - - Install the plugin: - - git://github.com/smtlaissezfaire/fixturereplacement.git - === Using FixtureReplacement within <tt>script/console</tt> $ ./script/console @@ -234,80 +119,16 @@ If you have other ideas for speeding up your test suite, I'm all ears. >> create_user => #<User id: 1, crypted_password: "521faec1c095..." ...> += Philosophy & Disadvantages -=== Using it with RSpec - -Add the following to your <tt>spec/spec_helper.rb</tt> file, in the configuration section: - - Spec::Runner.configure do |config| - config.include FixtureReplacement - end - -=== Using it with Test::Unit - -Add the following to your <tt>test/test_helper.rb</tt> file: - - class Test::Unit::TestCase - include FixtureReplacement - end - -== Running the Specs/Tests for FixtureReplacement - -You will need rspec (version 1.0.8 or later) to run the specs, as well as the sqlite3-ruby gem -(and sqlite3 installed): - - % sudo gem install rspec - % sudo gem install sqlite3-ruby +See philosophy_and_bugs.rdoc -cd into the fixture_replacement plugin directory: - - % cd vendor/plugins/fixture_replacement - -Then run with <tt>rake</tt> += Contributors, Contributions, & BUGS - % rake - -There are also some tests for test/unit. These mainly serve as regressions, but you are free -to run them as well. - -== Specdocs - -Specdocs can be found here[http://replacefixtures.rubyforge.org/specdoc.html] - -The Rcov report can be found here[http://replacefixtures.rubyforge.org/rcov/index.html] - -A flog report can be found here[http://replacefixtures.rubyforge.org/flog.txt] - -== Patches, Contributions: - -Thanks to the following for making this software better: - -- Greg Bluvshteyn (http://www.m001.net), for bugging me about the naming, and making the - wonderful suggestion to use the plugin in the console. -- Simon Peter Nicholls - - default_* methods can take a hash (applied in rev. 11) -- Wincent Colaiuta (http://wincent.com/) - Huge Thanks - - patch for spelling error in comments (applied in revision 31) - - patch for specs with sqlite3 (applied in revision 35) - - patch to ignore attr_protected in mass assignment (applied in revision 57) - - Most of this README Documentation (applied in revision 62) - - patch: silencing sqlite3 in memory creation of table output (applied in revision 72) -- Carl Porth - - patch: classify should be camelize (applied in revision 74) -- LinoJ, JW, Matthew Bass, Andy Watts, Dave Spurr - - bug reports -- Bryan Helmkamp: Feedback on back associating models. -- Pat Nakajima: Wonderful ideas from Fixjour. Elimination of default_* methods in favor - of new_* methods. - -If you would like to change how this software works or request a feature, use -the github issue tracker[http://github.com/smtlaissezfaire/fixturereplacement/issues]. - - - +See contributions.rdoc == License This software is dual licensed under the MIT and the GPLv3 Licenses (it's your pick). -Copyright 2007-2009 Scott Taylor <scott@railsnewbie.com> +Copyright 2007-2009 Scott Taylor / smtlaissezfaire[http://github.com/smtlaissezfaire] (scott@railsnewbie.com) README.rdoc @@ -26,9 +26,17 @@ Rake::RDocTask.new(:rdoc_without_analytics) do |rdoc| rdoc.title = 'FixtureReplacement' rdoc.options << '--line-numbers' << '--inline-source' - rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/' - - ["README.rdoc", "CHANGELOG.rdoc", "GPL_LICENSE", "MIT_LICENSE", "lib/**/*.rb"].each do |file| + rdoc.options << '--webcvs=http://github.com/smtlaissezfaire/fixturereplacement/tree/master/' + + [ + "README.rdoc", + "CHANGELOG.rdoc", + "GPL_LICENSE", + "MIT_LICENSE", + "contributions.rdoc", + "philosophy_and_bugs.rdoc", + "lib/**/*.rb" + ].each do |file| rdoc.rdoc_files.include(file) end end Rakefile 9a5c72ebe0648c74143343ac627e8167613b2afc Scott Taylor scott@railsnewbie.com http://github.com/smtlaissezfaire/fixturereplacement/commit/a4d6bf49a36fed1eea40799bead91dc360a17f8f a4d6bf49a36fed1eea40799bead91dc360a17f8f 2009-09-23T00:34:36-07:00 2009-09-22T22:08:29-07:00 README updates a2e2a5049a203ff05513f3984af8221da7c4b0d6 Scott Taylor scott@railsnewbie.com