JoinFix

A reflection-based solution to the fixture join problem.

Description

Making fixtures for models with complex joins can be a redundant, error-prone process. JoinFix provides a solution to this problem by letting you reference and/or define child entries inline with their parents.

[users.yml]
john_doe:
full_name: John Doe
groups: 
  - admin_group           # => entry reference
  - devel_group:          # => inline definition
      name: Developers
  
[groups.yml]
admin_group:                # => referenced entry
name: Administrators

JoinFix uses reflection on ActiveRecord associations to determine how to perform joins so no configuration is required. Simply require joinfix and begin writing entries.

Info

Developer: Simon Chiang, Biomolecular Structure Program, Hansen Lab
Support: UC Denver School of Medicine Deans Academic Enrichment Fund
Licence: MIT-Style

Installation

Tap is available as a gem on RubyForge. Use:

% gem install joinfix

Usage

Consider the following data model:

class User < ActiveRecord::Base
has_many :user_groups
has_many :groups, :through => :user_groups
end

class Group < ActiveRecord::Base
has_many :user_groups
has_many :users, :through => :user_groups
end

class UserGroup < ActiveRecord::Base
belongs_to :user
belongs_to :group
end

Write your fixtures using the naming scheme you lay out in your models. Entries can be referenced across multiple fixture files or defined inline:

[users.yml]
john_doe:
full_name: John Doe
groups: admin_group       # => reference to the 'admin_group' entry

jane_doe:
full_name: Jane Doe
groups:                   # => you can specify an array of entries if needed
  - admin_group
  - worker_group:         # => inline definition of the 'worker_group' entry
      name: Workers
   
[groups.yml]
admin_group:                # => the referenced 'admin_group' entry
id: 3                     # => you can (but don't have to) specify ids 
name: Administrators

Join entries implied in your definition, as in a has_and_belongs_to_many association, will be created and named by joining together the names of the parent and child, ordered by the '<' operator. For example, the users.yml and groups.yml fixtures produce these entries:

[users]
john_doe:
id: 1                     # => primary keys are assigned to all entries (see note)
full_name: John Doe
jane_doe:
id: 2
full_name: Jane Doe

[groups]
admin_group:                
id: 3                     
name: Administrators
worker_group:
id: 1
name: Workers

[user_groups]
admin_group_john_doe  
id: 1
user_id: 1                # => references are resolved to their foreign keys
group_id: 3               # => explicitly set primary keys are respected  
admin_group_jane_doe    
id: 2
user_id: 2                
group_id: 3   
jane_doe_worker_group       # => Notice the '<' operator in action
id: 3
user_id: 2                
group_id: 1

Note: Primary keys are assigned to entries based on the way the entry names are hashed, ie 'john_doe' will not necessarily have id '1'. If you need a specific id for an entry, then you must explicitly set it as in the 'admin_group' entry.

If you need to add additional fields to an implied entry, simply define them in their fixture file. All fields across all fixtures will be merged into one entry (JoinFix raises an error in the event of a collision).

[user_groups.yml]
admin_group_john_doe:
date_added: 2007-06-12

Nesting is allowed. This will make the same entries as above:

[users.yml]
john_doe:
full_name: John Doe
groups:    
  admin_group:
    id: 3
    name: Administrators
    users:
      jane_doe:
        full_name: Jane Doe
        groups:
          worker_group:
            name: Workers

In your tests, require joinfix and use the fixtures exactly as you would normally.
One gotcha -- you must be sure to name all the tables for which your fixtures create entries.
In fact this is no different than normal, but it's easy to forget if you lump joins into one file.

require 'joinfix'

class UserTest < Test::Unit::TestCase
fixtures :users, :groups, :user_groups  # => got to name them all!!!

def test_joinfix
  assert_equal "Administrators", users(:john_doe).groups.first.name
  assert_equal 2, User.find_by_full_name("jane_doe").groups.count
  assert_equal 3, UserGroup.find(user_groups(:admin_group_jane_doe).id).group.id
end
end

Command line options

JoinFix allows some command line options through the ENV variables. Setting these variables is easy if you're using rake to run your test suite:

% rake test key=value         # => sets ENV['key'] = 'value'

Available options:

format_joinfix_errors: Unless 'false', JoinFix will simplify the console output when a JoinFixError occurs.
joinfix_dump: Prints all entries for tables matching the value to STDOUT. Prints entries for all tables if 'true'.