Skip to main content

Rails: Tests vs. Docs

I've been accused before of relying too heavily on documentation and not heavily enough on tests. I wrote the following in my README_FOR_APP:
==== Unnecessary Files

You probably should not need to create files in any of these directories, and
you should not commit any autogenerated files to these directories. Each of
these directories has a README explaining why and what we're using instead::

* app/views/layouts
* test/fixtures
* test/functional
* test/integration
* test/unit
* test/unit/helpers
(I'm using RSpec, factory_girl, etc., so a lot of those directories are unnecessary. I only have one layout.)

I thought to myself, how would a TDD person solve this problem with tests instead of documentation? Hence, I created spec/hieararchy_spec.rb:
require File.expand_path(File.dirname(__FILE__) + '/spec_helper')

context "the file hierarchy in this Rails app" do
directories = {
"app/views/layouts" => ["main.html.erb"],
"test/fixtures" => [],
"test/functional" => [],
"test/integration" => [],
"test/unit" => ["helpers"],
"test/unit/helpers" => []
directories.each do |directory, expected|
it "should have no unexpected files in #{directory} (see the README)" do
Dir["#{File.dirname(__FILE__)}/../#{directory}/*"].each do |f|
(expected + ["README"]).should include(File.basename(f))
Now, I can get rid of the documentation. The test itself will tell the user what he did wrong and which README to look at.