Rails Testing Framework lacking documentation

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 documentation is being worked on. See
http://izumi.plan99.net/manuals/testing_rails_applications.html for a
preview.

Rodrigo Rosenfeld Rosas wrote:

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!

Read /Agile Web Development with Rails/, by the Daves. The "Agile" part is all about these kinds of tests, and that book has more than enough to get you started. Then the documentation for the hard stuff, on all the blogs, ass-u-me-s you have read that book already.

Hongli Lai wrote:

The documentation is being worked on. See
http://izumi.plan99.net/manuals/testing_rails_applications.html
for a preview.

Excellent! Let me know offlist if you could use my help.

Best regards,
Bill
bill dot walton at charter dot net

Hongli Lai wrote:

The documentation is being worked on. See
http://izumi.plan99.net/manuals/testing_rails_applications.html for a
preview.

Yes, I've already read it before posting, but please note that it doesn't
mention Integration Tests...

Thank you for pointing it, anyway...

Rodrigo.

Phlip wrote:

Rodrigo Rosenfeld Rosas wrote:

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!

Read /Agile Web Development with Rails/, by the Daves. The "Agile" part is
all about these kinds of tests, and that book has more than enough to get
you started. Then the documentation for the hard stuff, on all the blogs,
ass-u-me-s you have read that book already.

Being used to OpenSource development model from other projects (wxWidgets,
PostgreSQL, MySQL, Firebird, Bacula, Linux, etc), I'm used to think I don't
need any book to get the information from the API. Books are good to fasten
or easy the learning, not to document a framework... Actually, being open
or not, every framework should have a complete API documentation, even if
not that good, but at least a description of the parameters of each
function/method intended to the end user. Usually, in Free Software, one is
not expected to have read any kind of book... I'm not telling that this
book is not a good one, since I've not read it, but I don't agree that I
should be forced to buy it for understanding how Rails work...

I mean, I could help writing this lacking documentation if I just knew how
to write it and how do these methods actually work.

Rodrigo.

Phlip wrote:

Rodrigo Rosenfeld Rosas wrote:

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!

Read /Agile Web Development with Rails/, by the Daves. The "Agile" part is
all about these kinds of tests, and that book has more than enough to get
you started. Then the documentation for the hard stuff, on all the blogs,
ass-u-me-s you have read that book already.

Being used to OpenSource development model from other projects (wxWidgets,
PostgreSQL, MySQL, Firebird, Bacula, Linux, etc), I'm used to think I don't
need any book to get the information from the API. Books are good to fasten
or easy the learning, not to document a framework... Actually, being open
or not, every framework should have a complete API documentation, even if
not that good, but at least a description of the parameters of each
function/method intended to the end user. Usually, in Free Software, one is
not expected to have read any kind of book... I'm not telling that this
book is not a good one, since I've not read it, but I don't agree that I
should be forced to buy it for understanding how Rails work...

I mean, I could help writing this lacking documentation if I just knew how
to write it and how do these methods actually work.

Rodrigo.

Help would be much appreciated. :slight_smile: The guides are stored in .txt files
in the Rails source repository. We have a documentation wishlist at
http://github.com/rails/rails/wikis/guides-wishlist. If you'd like to
help, please pick an item from the wishlist and let us know.