From e884f2b8325cbca9ca829d93b5b11aad1c9f7346 Mon Sep 17 00:00:00 2001 From: Mike Gunderloy Date: Tue, 4 Nov 2008 10:00:40 -0600 Subject: Regenerate recently-changed guides. --- .../guides/html/debugging_rails_applications.html | 74 ++++++++-------------- railties/doc/guides/html/finders.html | 45 +++++-------- .../guides/html/testing_rails_applications.html | 67 +++++++------------- 3 files changed, 63 insertions(+), 123 deletions(-) (limited to 'railties/doc/guides/html') diff --git a/railties/doc/guides/html/debugging_rails_applications.html b/railties/doc/guides/html/debugging_rails_applications.html index d3a3180842..95f5b39e4c 100644 --- a/railties/doc/guides/html/debugging_rails_applications.html +++ b/railties/doc/guides/html/debugging_rails_applications.html @@ -340,10 +340,7 @@ http://www.gnu.org/software/src-highlite -->

You'll see something like this:

-
+
--- !ruby/object:Post
 attributes:
   updated_at: 2008-09-05 22:55:47
@@ -355,8 +352,8 @@ attributes:
 attributes_cache: {}
 
 
-Title: Rails debugging guide
-
+Title: Rails debugging guide +

1.2. to_yaml

Displaying an instance variable, or any other object or method, in yaml format can be achieved this way:

@@ -373,10 +370,7 @@ http://www.gnu.org/software/src-highlite -->

The to_yaml method converts the method to YAML format leaving it more readable, and then the simple_format helper is used to render each line as in the console. This is how debug method does its magic.

As a result of this, you will have something like this in your view:

-
+
--- !ruby/object:Post
 attributes:
 updated_at: 2008-09-05 22:55:47
@@ -387,8 +381,8 @@ id: "1"
 created_at: 2008-09-05 22:55:47
 attributes_cache: {}
 
-Title: Rails debugging guide
-
+Title: Rails debugging guide +

1.3. inspect

Another useful method for displaying object values is inspect, especially when working with arrays or hashes. This will print the object value as a string. For example:

@@ -404,14 +398,11 @@ http://www.gnu.org/software/src-highlite -->

Will be rendered as follows:

-
+
[1, 2, 3, 4, 5]
 
-Title: Rails debugging guide
-
+Title: Rails debugging guide +

1.4. Debugging Javascript

Rails has built-in support to debug RJS, to active it, set ActionView::Base.debug_rjs to true, this will specify whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it).

To enable it, add the following in the Rails::Initializer do |config| block inside environment.rb:

@@ -529,11 +520,8 @@ http://www.gnu.org/software/src-highlite -->

Here's an example of the log generated by this method:

-
-
Processing PostsController#create (for 127.0.0.1 at 2008-09-08 11:52:54) [POST]
+

+
Processing PostsController#create (for 127.0.0.1 at 2008-09-08 11:52:54) [POST]
   Session ID: BAh7BzoMY3NyZl9pZCIlMDY5MWU1M2I1ZDRjODBlMzkyMWI1OTg2NWQyNzViZjYiCmZsYXNoSUM6J0FjdGl
 vbkNvbnRyb2xsZXI6OkZsYXNoOjpGbGFzaEhhc2h7AAY6CkB1c2VkewA=--b18cd92fba90eacf8137e5f6b3b06c4d724596a4
   Parameters: {"commit"=>"Create", "post"=>{"title"=>"Debugging Rails",
@@ -547,8 +535,8 @@ Post should be valid: true
  'I''m learning how to print in logs!!!', 'f', '2008-09-08 14:52:54')
 The post was saved and now is the user is going to be redirected...
 Redirected to #<Post:0x20af760>
-Completed in 0.01224 (81 reqs/sec) | DB: 0.00044 (3%) | 302 Found [http://localhost/posts]
-
+Completed in 0.01224 (81 reqs/sec) | DB: 0.00044 (3%) | 302 Found [http://localhost/posts] +

Adding extra logging like this makes it easy to search for unexpected or unusual behavior in your logs. If you add extra logging, be sure to make sensible use of log levels, to avoid filling your production logs with useless trivia.

3. Debugging with ruby-debug

@@ -581,12 +569,9 @@ http://www.gnu.org/software/src-highlite -->

If you see the message in the console or logs:

-
-
***** Debugger requested, but was not available: Start server with --debugger to enable *****
-
+
+
***** Debugger requested, but was not available: Start server with --debugger to enable *****
+

Make sure you have started your web server with the option —debugger:

+
set autolist
 set forcestep
-set listsize 25
-
+set listsize 25 +

4. Debugging Memory Leaks

@@ -1046,20 +1028,14 @@ http://www.gnu.org/software/src-highlite -->

Make sure to run a couple hundred requests to get better data samples, then press CTRL-C. The server will stop and Bleak House will produce a dumpfile in /tmp:

-
+
** BleakHouse: working...
 ** BleakHouse: complete
-** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.
-
+** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze. +

To analyze it, just run the listed command. The top 20 leakiest lines will be listed:

-
+
  191691 total objects
   Final heap size 191691 filled, 220961 free
   Displaying top 20 most common line/class pairs
@@ -1071,8 +1047,8 @@ http://www.gnu.org/software/src-highlite -->
    951 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:111:String
    935 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:String
    834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array
-  ...
-
+ ... +

This way you can find where your application is leaking memory and fix it.

If BleakHouse doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter. In that case, try using Valgrind to investigate further.

4.2. Valgrind

diff --git a/railties/doc/guides/html/finders.html b/railties/doc/guides/html/finders.html index f8396bb517..18bc32306f 100644 --- a/railties/doc/guides/html/finders.html +++ b/railties/doc/guides/html/finders.html @@ -373,27 +373,21 @@ http://www.gnu.org/software/src-highlite --> 
SELECT * FROM +clients+ WHERE (+clients+.+id+ IN (1,2))
-
+
>> Client.find(1,2)
 => [#<Client id: 1, name: => "Ryan", locked: false, orders_count: 2,
   created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50">,
   #<Client id: 2, name: => "Michael", locked: false, orders_count: 3,
-  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">]
-
+ created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">] +

Note that if you pass in a list of numbers that the result will be returned as an array, not as a single Client object.

If you wanted to find the first client you would simply type Client.first and that would find the first client created in your clients table:

-
+
>> Client.first
 => #<Client id: 1, name: => "Ryan", locked: false, orders_count: 2,
-  created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50">
-
+ created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"> +

If you were running script/server you might see the following output:

Indicating the query that Rails has performed on your database.

To find the last client you would simply type Client.find(:last) and that would find the last client created in your clients table:

-
+
>> Client.find(:last)
 => #<Client id: 2, name: => "Michael", locked: false, orders_count: 3,
-  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">
-
+ created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"> +

To find all the clients you would simply type Client.all and that would find all the clients in your clients table:

-
+
>> Client.all
 => [#<Client id: 1, name: => "Ryan", locked: false, orders_count: 2,
   created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50">,
   #<Client id: 2, name: => "Michael", locked: false, orders_count: 3,
-  created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">]
-
+ created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40">] +

As alternatives to calling Client.first, Client.last, and Client.all, you can use the class methods Client.first, Client.last, and Client.all instead. Client.first, Client.last and Client.all just call their longer counterparts: Client.find(:first), Client.find(:last) and Client.find(:all) respectively.

Be aware that Client.first/Client.find(:first) and Client.last/Client.find(:last) will both return a single object, where as Client.all/Client.find(:all) will return an array of Client objects, just as passing in an array of ids to find will do also.

@@ -510,12 +498,9 @@ http://www.gnu.org/software/src-highlite -->

This could possibly cause your database server to raise an unexpected error, for example MySQL will throw back this error:

-
-
Got a packet bigger than 'max_allowed_packet' bytes: _query_
-
+
+
Got a packet bigger than 'max_allowed_packet' bytes: _query_
+

Where query is the actual query used to get that error.

In this example it would be better to use greater-than and less-than operators in SQL, like so:

diff --git a/railties/doc/guides/html/testing_rails_applications.html b/railties/doc/guides/html/testing_rails_applications.html index 73634ef328..666d1dff85 100644 --- a/railties/doc/guides/html/testing_rails_applications.html +++ b/railties/doc/guides/html/testing_rails_applications.html @@ -233,7 +233,7 @@ ul#navMain {
  • What to include in your Functional Tests
    • -
  • Available Request Types for Functional Tests===
    • +
  • Available Request Types for Functional Tests
  • The 4 Hashes of the Apocalypse
    • @@ -398,15 +398,12 @@ steve:

    Fixtures can also be described using the all-too-familiar comma-separated value (CSV) file format. These files, just like YAML fixtures, are placed in the test/fixtures directory, but these end with the .csv file extension (as in celebrity_holiday_figures.csv).

    A CSV fixture looks like this:

    -
    +
    id, username, password, stretchable, comments
 1, sclaus, ihatekids, false, I like to say ""Ho! Ho! Ho!""
 2, ebunny, ihateeggs, true, Hoppity hop y'all
-3, tfairy, ilovecavities, true, "Pull your teeth, I will"
-
    +3, tfairy, ilovecavities, true, "Pull your teeth, I will" +

    The first line is the header. It is a comma-separated list of fields. The rest of the file is the payload: 1 record per line. A few notes about this format:

    When you create a model using script/generate, among other things it creates a test stub in the test/unit folder, as well as a fixture for the model:

    -
    +
    $ script/generate model Post
 ...
 create  app/models/post.rb
 create  test/unit/post_test.rb
 create  test/fixtures/posts.yml
-...
-
    +... +

    The default test stub in test/unit/post_test.rb looks like this:

    +
    $ ruby unit/post_test.rb -n test_truth
 
 Loaded suite unit/post_test
@@ -648,8 +639,8 @@ Started
 .
 Finished in 0.023513 seconds.
 
-1 tests, 1 assertions, 0 failures, 0 errors
-
    +1 tests, 1 assertions, 0 failures, 0 errors +

    The . (dot) above indicates a passing test. When a test fails you see an F; when a test throws an error you see an E in its place. The last line of the output is the summary.

    To see how a test failure is reported, you can add a failing test to the post_test.rb test case:

    @@ -664,10 +655,7 @@ http://www.gnu.org/software/src-highlite -->

    If you haven't added any data to the test fixture for posts, this test will fail. You can see this by running it:

    -
    +
    $ ruby unit/post_test.rb
 Loaded suite unit/post_test
 Started
@@ -681,8 +669,8 @@ test_should_have_atleast_one_post(PostTest)
      /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `run']:
 <nil> expected to not be nil.
 
-2 tests, 2 assertions, 1 failures, 0 errors
-
    +2 tests, 2 assertions, 1 failures, 0 errors +

    In the output, F denotes a failure. You can see the corresponding trace shown under 1) along with the name of the failing test. The next few lines contain the stack trace followed by a message which mentions the actual value and the expected value by the assertion. The default assertion messages provide just enough information to help pinpoint the error. To make the assertion failure message more readable every assertion provides an optional message parameter, as shown here:

    Running this test shows the friendlier assertion message:

    -
    +
    $ ruby unit/post_test.rb
 Loaded suite unit/post_test
 Started
@@ -714,8 +699,8 @@ test_should_have_atleast_one_post(PostTest)
 Should not be nil as Posts table should have atleast one post.
 <nil> expected to not be nil.
 
-2 tests, 2 assertions, 1 failures, 0 errors
-
    +2 tests, 2 assertions, 1 failures, 0 errors +

    To see how an error gets reported, here's a test containing an error:

    Now you can see even more output in the console from running the tests:

    -
    +
    $ ruby unit/post_test.rb
 Loaded suite unit/post_test
 Started
@@ -756,8 +738,8 @@ NameError: undefined local variable or method `some_undefined_variable' for #<
     /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `__send__'
     /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `run'
 
-3 tests, 2 assertions, 1 failures, 1 errors
-
    +3 tests, 2 assertions, 1 failures, 1 errors +

    Notice the E in the output. It denotes a test with error.

    @@ -1160,7 +1142,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    get(:view, {'id' => '12'}, nil, {'message' => 'booya!'})
    -

    4.2. Available Request Types for Functional Tests===

    +

    4.2. Available Request Types for Functional Tests

    If you're familiar with the HTTP protocol, you'll know that get is a type of request. There are 5 request types supported in Rails functional tests:

    • @@ -1638,16 +1620,13 @@ http://www.gnu.org/software/src-highlite -->

      In this test, @expected is an instance of TMail::Mail that you can use in your tests. It is defined in ActionMailer::TestCase. The test above uses @expected to construct an email, which it then asserts with email created by the custom mailer. The invite fixture is the body of the email and is used as the sample content to assert against. The helper read_fixture is used to read in the content from this file.

      Here's the content of the invite fixture:

      -
      +
      Hi friend@example.com,
 
 You have been invited.
 
-Cheers!
-
      +Cheers! +

    This is the right time to understand a little more about writing tests for your mailers. The line ActionMailer::Base.delivery_method = :test in config/environments/test.rb sets the delivery method to test mode so that email will not actually be delivered (useful to avoid spamming your users while testing) but instead it will be appended to an array (ActionMailer::Base.deliveries).

    However often in unit tests, mails will not actually be sent, simply constructed, as in the example above, where the precise content of the email is checked against what it should be.

    6.3. Functional Testing

    -- cgit v1.2.3