diff options
Diffstat (limited to 'activerecord/lib/active_record/fixtures.rb')
| -rw-r--r-- | activerecord/lib/active_record/fixtures.rb | 103 |
1 files changed, 46 insertions, 57 deletions
diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb index 0131d9fac5..c6501113bf 100644 --- a/activerecord/lib/active_record/fixtures.rb +++ b/activerecord/lib/active_record/fixtures.rb @@ -21,13 +21,17 @@ else end end -# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavors: +# Fixtures are a way of organizing data that you want to test against; in short, sample data. +# +# = Fixture formats +# +# Fixtures come in 3 flavors: # # 1. YAML fixtures # 2. CSV fixtures # 3. Single-file fixtures # -# = YAML fixtures +# == YAML fixtures # # This type of fixture is in YAML format and the preferred default. YAML is a file format which describes data structures # in a non-verbose, human-readable format. It ships with Ruby 1.8.1+. @@ -65,9 +69,9 @@ end # parent_id: 1 # title: Child # -# = CSV fixtures +# == CSV fixtures # -# Fixtures can also be kept in the Comma Separated Value format. Akin to YAML fixtures, CSV fixtures are stored +# Fixtures can also be kept in the Comma Separated Value (CSV) format. Akin to YAML fixtures, CSV fixtures are stored # in a single file, but instead end with the <tt>.csv</tt> file extension # (Rails example: <tt><your-rails-app>/test/fixtures/web_sites.csv</tt>). # @@ -90,7 +94,7 @@ end # Most databases and spreadsheets support exporting to CSV format, so this is a great format for you to choose if you # have existing data somewhere already. # -# = Single-file fixtures +# == Single-file fixtures # # This type of fixture was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats. # Fixtures for this format are created by placing text files in a sub-directory (with the name of the model) to the directory @@ -113,65 +117,53 @@ end # name => Ruby on Rails # url => http://www.rubyonrails.org # -# = Using Fixtures +# = Using fixtures in testcases # # Since fixtures are a testing construct, we use them in our unit and functional tests. There are two ways to use the # fixtures, but first let's take a look at a sample unit test: # -# require 'web_site' +# require 'test_helper' # # class WebSiteTest < ActiveSupport::TestCase -# def test_web_site_count +# test "web_site_count" do # assert_equal 2, WebSite.count # end # end # -# As it stands, unless we pre-load the web_site table in our database with two records, this test will fail. Here's the -# easiest way to add fixtures to the database: -# -# ... -# class WebSiteTest < ActiveSupport::TestCase -# fixtures :web_sites # add more by separating the symbols with commas -# ... -# -# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here though), we trigger -# the testing environment to automatically load the appropriate fixtures into the database before each test. +# By default, the <tt>test_helper module</tt> will load all of your fixtures into your test database, so this test will succeed. +# The testing environment will automatically load the all fixtures into the database before each test. # To ensure consistent data, the environment deletes the fixtures before running the load. # -# In addition to being available in the database, the fixtures are also loaded into a hash stored in an instance variable -# of the test case. It is named after the symbol... so, in our example, there would be a hash available called -# <tt>@web_sites</tt>. This is where the "fixture name" comes into play. -# -# On top of that, each record is automatically "found" (using <tt>Model.find(id)</tt>) and placed in the instance variable of its name. -# So for the YAML fixtures, we'd get <tt>@rubyonrails</tt> and <tt>@google</tt>, which could be interrogated using regular Active Record semantics: +# In addition to being available in the database, the fixture's data may also be accessed by +# using a special dynamic method, which has the same name as the model, and accepts the +# name of the fixture to instantiate: # -# # test if the object created from the fixture data has the same attributes as the data itself -# def test_find -# assert_equal @web_sites["rubyonrails"]["name"], @rubyonrails.name +# test "find" do +# assert_equal "Ruby on Rails", web_sites(:rubyonrails).name # end # -# As seen above, the data hash created from the YAML fixtures would have <tt>@web_sites["rubyonrails"]["url"]</tt> return -# "http://www.rubyonrails.org" and <tt>@web_sites["google"]["name"]</tt> would return "Google". The same fixtures, but loaded -# from a CSV fixture file, would be accessible via <tt>@web_sites["web_site_1"]["name"] == "Ruby on Rails"</tt> and have the individual -# fixtures available as instance variables <tt>@web_site_1</tt> and <tt>@web_site_2</tt>. +# Alternatively, you may enable auto-instantiation of the fixture data. For instance, take the following tests: # -# If you do not wish to use instantiated fixtures (usually for performance reasons) there are two options. +# test "find_alt_method_1" do +# assert_equal "Ruby on Rails", @web_sites['rubyonrails']['name'] +# end # -# - to completely disable instantiated fixtures: -# self.use_instantiated_fixtures = false +# test "find_alt_method_2" do +# assert_equal "Ruby on Rails", @rubyonrails.news +# end # -# - to keep the fixture instance (@web_sites) available, but do not automatically 'find' each instance: -# self.use_instantiated_fixtures = :no_instances +# In order to use these methods to access fixtured data within your testcases, you must specify one of the +# following in your <tt>ActiveSupport::TestCase</tt>-derived class: # -# Even if auto-instantiated fixtures are disabled, you can still access them -# by name via special dynamic methods. Each method has the same name as the -# model, and accepts the name of the fixture to instantiate: +# - to fully enable instantiated fixtures (enable alternate methods #1 and #2 above) +# self.use_instantiated_fixtures = true # -# fixtures :web_sites +# - create only the hash for the fixtures, do not 'find' each instance (enable alternate method #1 only) +# self.use_instantiated_fixtures = :no_instances # -# def test_find -# assert_equal "Ruby on Rails", web_sites(:rubyonrails).name -# end +# Using either of these alternate methods incurs a performance hit, as the fixtured data must be fully +# traversed in the database to create the fixture hash and/or instance variables. This is expensive for +# large sets of fixtured data. # # = Dynamic fixtures with ERb # @@ -194,21 +186,17 @@ end # = Transactional fixtures # # TestCases can use begin+rollback to isolate their changes to the database instead of having to delete+insert for every test case. -# They can also turn off auto-instantiation of fixture data since the feature is costly and often unused. # # class FooTest < ActiveSupport::TestCase # self.use_transactional_fixtures = true -# self.use_instantiated_fixtures = false -# -# fixtures :foos # -# def test_godzilla +# test "godzilla" do # assert !Foo.find(:all).empty? # Foo.destroy_all # assert Foo.find(:all).empty? # end # -# def test_godzilla_aftermath +# test "godzilla aftermath" do # assert !Foo.find(:all).empty? # end # end @@ -220,24 +208,25 @@ end # access to fixture data for every table that has been loaded through fixtures (depending on the value of +use_instantiated_fixtures+) # # When *not* to use transactional fixtures: -# 1. You're testing whether a transaction works correctly. Nested transactions don't commit until all parent transactions commit, -# particularly, the fixtures transaction which is begun in setup and rolled back in teardown. Thus, you won't be able to verify -# the results of your transaction until Active Record supports nested transactions or savepoints (in progress). -# 2. Your database does not support transactions. Every Active Record database supports transactions except MySQL MyISAM. -# Use InnoDB, MaxDB, or NDB instead. +# +# 1. You're testing whether a transaction works correctly. Nested transactions don't commit until all parent transactions commit, +# particularly, the fixtures transaction which is begun in setup and rolled back in teardown. Thus, you won't be able to verify +# the results of your transaction until Active Record supports nested transactions or savepoints (in progress). +# 2. Your database does not support transactions. Every Active Record database supports transactions except MySQL MyISAM. +# Use InnoDB, MaxDB, or NDB instead. # # = Advanced YAML Fixtures # # YAML fixtures that don't specify an ID get some extra features: # -# * Stable, autogenerated ID's +# * Stable, autogenerated IDs # * Label references for associations (belongs_to, has_one, has_many) # * HABTM associations as inline lists # * Autofilled timestamp columns # * Fixture label interpolation # * Support for YAML defaults # -# == Stable, autogenerated ID's +# == Stable, autogenerated IDs # # Here, have a monkey fixture: # @@ -292,7 +281,7 @@ end # # Add a few more monkeys and pirates and break this into multiple files, # and it gets pretty hard to keep track of what's going on. Let's -# use labels instead of ID's: +# use labels instead of IDs: # # ### in pirates.yml # |