docs/src/index.markdown

   1 **Doozer** is a simple fixture generation library/plugin that handles all the annoying id management, and association building, allowing you to focus on crafting meaningful test fixtures.
   2
   3 ### Installation
   4
   5 In your rails project directory, run:
   6
   7
   8         ./script/plugin source http://mattmccray.com/svn/rails/plugins/
   9         ./script/plugin install doozer
  10
  11
  12 ### Usage
  13
  14 Doozer scripts are usually ruby files that live in the `RAILS_ROOT/text/fixtures/doozers` directory.
  15
  16 Let's walk through a simple `pages.rb` doozer. At the top of the script, we'll add this:
  17
  18         Doozer.define :page do
  19           field_order :title, :content, :author
  20
  21           defaults :content=>'Content Here',
  22                :author=>'System',
  23                :created_on=>Time.now.to_s(:db)
  24
  25           block_affects :child=>:parent_id
  26         end
  27
  28 That tells Doozer that you are going to generate `page` fixtures. It then generates three macros for you to use: `page`, `page_id`, and `pages`. The first macro is the one you'll use most. It defines, or updates, fixture data.
  29
  30 In the definition block, it maps positional parameters to the fixture data fields. It sets up some default values for the fixture data. And lastly, configures how to handle fixtures defined in a `page` macro block.
  31
  32
  33 Now we can start to write our test data like this:
  34
  35         page :root, "Home Page" do
  36           page :news, "News is always Fun!" do
  37             page :site_launch, "Site launched!", :created_on=>1.week.ago
  38             page :more_news, "More news", :created_on=>3.days.ago
  39           end
  40         end
  41
  42 There are a couple of things to go over here...
  43
  44 First, you'll notice the first parameter sent to the `page` macro is a symbol, it's used as the fixture name. It's optional, if you don't specify a name one will be automatically generated.
  45
  46 We also are mixing positional parameters and named parameters. We specify the `field_order` of the positional parameters, any named parameters are sent straight to the fixture data whether it's defined in the `field_order` or not.
  47
  48 So here's a breakdown of an example `page` macro call:
  49
  50     page :site_launch,   "Site launched!",   :created_on=>1.week.ago
  51          ^ fixture name  ^ field_order[0]    ^ sent straight to the
  52                                :title              fixture data
  53
  54 It will have handled the relationships automatically, as well. Since the `:site_launch` fixture is defined in a block under `:news`, the `:site_launch` fixture will have the appropriate `:parent_id` set.
  55
  56 In the definition above, we used `block_affects :child=>:parent_id` to handle our `acts_as_tree` example. Other options include `:child=>:belongs_to` and `:parent=>:belongs_to`, with more to come.
  57
  58 It's worth noting here that you can reference the same fixture multiple times, each time it will add to the fixture data it's associated with. So you can create partial fixtures and complete them elsewhere in the doozer script.
  59
  60 In our example so far, all of the pages will have the default content of "Content Here" (as defined in the `defaults` hash). Let's change that by calling the `page` macro again with fixture name and the content attribute. Since the content field isn't the first defined in the `field_order` we'll use a named parameter.
  61
  62 These lines go at the bottom of the definition file:
  63
  64         page :root,        :content=><<-EOC
  65         Welcome to this this site, please enjoy yourself!
  66
  67         Multiple lines are good too.
  68         EOC
  69
  70         page :news,        :content=>"I'm the parent page to all of the news!"
  71         page :site_launch, :content=>"Really, it was!"
  72         page :more_news,   :content=>"No Gnus is Good Gnus!"
  73
  74 That's the basics of a doozer script. To generate the fixture(s), just run:
  75
  76     rake doozer:build
  77
  78 Here's the generated fixture from our example above:
  79
  80     root:
  81       created_on: 2007-03-20 15:21:47
  82       title: Home Page
  83       author: System
  84       id: 1
  85       content: |
  86         Welcome to this this site, please enjoy yourself!
  87
  88         Multiple lines are good too.
  89
  90     news:
  91       created_on: 2007-03-20 15:21:47
  92       title: News is always Fun!
  93       author: System
  94       id: 2
  95       content: I'm the parent page to all of the news!
  96       parent_id: 1
  97
  98     site_launch:
  99       created_on: 2007-03-13 15:21:47.096033 -05:00
 100       title: Site launched!
 101       author: System
 102       id: 3
 103       content: Really, it was!
 104       parent_id: 2
 105
 106     more_news:
 107       created_on: 2007-03-17 15:21:47.096100 -05:00
 108       title: More news
 109       author: System
 110       id: 4
 111       content: No Gnus is Good Gnus!
 112       parent_id: 2
 113
 114 That's it, enjoy!
 115