It's said that Rails promotes testing. But it lacks in properly documentation.
I'm trying to learn how to write test units in Rails 2.1, but the documentation is unusable.
Take for instance, this case:
In API, it is stated that: " ActionController::Integration::Session get(path, parameters = nil, headers = nil)
Performs a GET request with the given parameters. The parameters may be nil, a Hash, or a string that is appropriately encoded (application/x-www-form-urlencoded or multipart/form-data). The headers should be a hash. The keys will automatically be upcased, with the prefix ?HTTP_? added if needed."
Note that nothing is said about the "path" parameter. And that is exactly my doubt!
continuing reading the API:
"ActionController::IntegrationTest ... # get the login page get "/login" ... # post the login and follow through to the home page post "/login", ... "
Note that all examples use a string as the "path". Ok, that works...
The problem is that the scaffolded integration tests generated and a lot of tutorial on the Net point to another usage: "get :index", using a symbol, instead. Here is an extract from scaffold: "script/generate scaffold sample field1:string field2:integer" test/functional/samples_controller_test.rb:
"class SamplesControllerTest < ActionController::TestCase def test_should_get_index get :index assert_response :success assert_not_nil assigns(:samples) end"
That also works... but wait! Not always! This works for the scaffold generated controller, but doesn't work on my actual application. I guess the cause is that the scaffold generates RESTfull controllers and routes and my own controllers aren't RESTful. Besides that, these tests inherits ActionController::TestCase, instead of IntegrationTest. But it is just a guest from my experience. Nor even the source code helped in this case. Ruby is a too powerful language, which has also some drawbacks. It's too powerful that it is difficult to find the implementation for some methods if you don't know the implementation overall. Methods can be overridden in any file and modules can be included in any file either.
First, note that SamplesControllerTest inherits ActionController::TestCase, which has no documentation at all.
Thankfully to ruby_debug "step" method, I could realize that these are the relevant codes: actionpack/lib/action_controller/test_process.rb:359: " module TestProcess def self.included(base) # execute the request simulating a specific HTTP method and set/volley the response %w( get post put delete head ).each do |method| base.class_eval <<-EOV, __FILE__, __LINE__ def #{method}(action, parameters = nil, session = nil, flash = nil) @request.env['REQUEST_METHOD'] = "#{method.upcase}" if defined (@request) process(action, parameters, session, flash) end EOV end end # execute the request and set/volley the response def process(action, parameters = nil, session = nil, flash = nil) # Sanity check for required instance variables so we can give an # understandable error message. %w(@controller @request @response).each do |iv_name| if !(instance_variable_names.include?(iv_name) || instance_variable_name s.include?(iv_name.to_sym)) || instance_variable_get(iv_name).nil? raise "#{iv_name} is nil: make sure you set it in your test's setup me thod." end end
@request.recycle!
@html_document = nil @request.env['REQUEST_METHOD'] ||= "GET" debugger @request.action = action.to_s
parameters ||= {} @request.assign_parameters(@controller.class.controller_path, action.to_s, parameters) @request.session = ActionController::TestSession.new(session) unless session.nil? @request.session["flash"] = ActionController::Flash::FlashHash.new.update(flash) if flash build_request_uri(action, parameters) @controller.process(@request, @response) end ... "
Very clean, don't you agree? That's what I am talking about. The ActionController::TestCase is just an example of the lack of documentation in Rails, as a whole. There are a lot of methods and classes that lack documentation in Rails.
I think Rails is one of the greatest frameworks I've known, but the lack of good documentation and good internationalization support still sets me down...
Finally, I would like to know, how am I supposed to learn about Testing in Rails, without citing non-free books? I think there should be, at least, a good API on the subject. Am I missing something?
Thanks in advance...
Sorry for boring you, but I'm pretty upset after 2 days digging on the subject, trying to search for documentation in the API and finally, trying to understand the source-code...
Rodrigo.
The guides are stored in .txt files
in the Rails source repository. We have a documentation wishlist at