# Rails Testing Framework lacking documentation

**URL:** <https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790>\
**Category:** Rails\
**Created:** [August 23, 2008, 8:31pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790 "2008-08-23T20:31:19Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 23, 2008, 8:31pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/1 "2008-08-23T20:31:19Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 24, 2008, 11:22am UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/2 "2008-08-24T11:22:12Z")

</div>

The documentation is being worked on. See  
[http://izumi.plan99.net/manuals/testing\_rails\_applications.html](http://izumi.plan99.net/manuals/testing_rails_applications.html) for a  
preview.

On Aug 23, 8:30 pm, Rodrigo Rosenfeld R. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 24, 2008, 3:32pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/3 "2008-08-24T15:32:18Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 24, 2008, 5:36pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/4 "2008-08-24T17:36:58Z")

</div>

Hongli L. wrote:

> The documentation is being worked on. See  
> [http://izumi.plan99.net/manuals/testing\_rails\_applications.html](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

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 25, 2008, 2:59pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/5 "2008-08-25T14:59:08Z")

</div>

Hongli L. wrote:

> The documentation is being worked on. See  
> [http://izumi.plan99.net/manuals/testing\_rails\_applications.html](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.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 26, 2008, 8:19pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/6 "2008-08-26T20:19:54Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 25, 2008, 3:00pm UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/7 "2008-08-25T15:00:53Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [August 27, 2008, 1:35am UTC](https://www.ruby-forum.com/t/rails-testing-framework-lacking-documentation/196790/8 "2008-08-27T01:35:11Z")

</div>

On Aug 24, 5:35 pm, “Bill W.” [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> Hongli L. wrote:
> 
> > The documentation is being worked on. See  
> > [http://izumi.plan99.net/manuals/testing\_rails\_applications.html](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. 🙂 The guides are stored in .txt files  
in the Rails source repository. We have a documentation wishlist at  
[GitHub - rails/rails: Ruby on Rails](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.