Peter Marklund

Peter Marklund's Home


Rails Tip: Use the Unit Tests as Documentation

If you are looking for authoritative answers on how to use the Rails API, look no further than the Rails unit tests. Those tests provide excellent documentation on what's supported by the API and what isn't, how the API is intended to be used, the kind of use cases and domain specific problems that drove the API, and also what API usage is most likely to work in future versions of Rails.

Let me give you a concrete example. In my code I had the equivalent of a Tag class connected through a Tagging join model with two different classes, say Post and Comment. What I was trying to do was say in the Tag class something like "has_many :posts, :through => :taggings, :source => :taggable" or maybe "has_many :taggables, :through => :taggings". However, Rails refused to let me do this and kept throwing an ActiveRecord::HasManyThroughAssociationPolymorphicError. At this point I wasn't sure if I was misusing the API or if I had come across a Rails bug (although I knew that the former was more likely).

I turned first to the most authoritative documentation such as the API doc, the Agile Web Development with Rails book, and the Rails Recipes book (Recipe 22: "May-to-Many Relationships with Extra Data", and Recipe 23: "Polymorphic Associations - has_many :whatevers"). However, none of that documentation seemed to address my specific problem. Through Google I found the wiki page HowToUsePolymorphicAssociations which did address my problem. However, the solution there seemed clumsy, and I didn't know how authoritative and up-to-date it was.

It's usually a good idea to debug a problem by following the stack trace into the Rails code and try to figure out what's going on right there. However, in this particular case I found that reading the clean but complex ActiveRecord code didn't give me any easy answers. It then hit me that what I really should be doing was read the ActiveRecord unit tests. Luckily for us application developers David and the rest of the core team has provided us with a nice suite of unit tests. Once I looked at the join model test case the whole picture cleared up - the fog lifted and there was bright sunlight. Laid out right there in front of me were excellent and authoritative examples of how to use ActiveRecord associations with classes such as Tag, Tagging, Post, Comment, Category, and Categorization. I also found the particular assertion that said that the ActiveRecord::HasManyThroughAssociationPolymorphicError should be raised in my case...

One could speculate that Rails really should provide a way to do has_many through a polymorphic association, and surely there is a way to hack Rails into doing something like that. What's important though is that now I know that the approach is not officially supported or intended and that's fine with me. I like to stay on the unit tested golden Rails path and I recommend you to do the same.