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.

On Aug 23, 8:30 pm, Rodrigo Rosenfeld R. [email protected]

Rodrigo Rosenfeld R. wrote:

Note that nothing is said about the “path” parameter. And that is exactly my
doubt!

Read /Agile Web D. 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.


Phlip

Hongli L. 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 L. 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:

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 D. 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:

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 D. 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.

On Aug 24, 5:35 pm, “Bill W.” [email protected] wrote:

Hongli L. 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.

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.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs