Skip to content
This repository
Browse code

Syntax fixes plus some modification and additions in multiple section…

…s of testing guide.
  • Loading branch information...
commit c492288d1660f016f4b2cd1ed299e31786886a9b 1 parent fd9d92a
Akshay Surve startupjockey authored
137 railties/doc/guides/testing_rails_applications/testing_rails_applications.txt
@@ -2,15 +2,18 @@ A Guide to Testing Rails Applications
2 2 =====================================
3 3
4 4 This guide covers built-in mechanisms offered by Rails to test your application. By referring to this guide, you will be able to:
  5 +
5 6 * Understand Rails testing terminologies
6 7 * Write unit, functional and integration tests for your application
7 8 * Read about other popular testing approaches and plugins
8 9
9 10 Assumptions:
  11 +
10 12 * You have spent more than 15 minutes in building your first application
11 13 * The guide has been written for Rails 2.1 and above
12 14
13   -== Why write tests for your Rails applications?
  15 +== Why write tests for your Rails applications? ==
  16 +
14 17 * Since Ruby code that you write in your Rails application is interpreted, you may only find that its broken when you actually run your application server and use it through the browser. Writing tests is a clean way of running through your code and catching syntactical and logic errors.
15 18 * Rails tests can also simulate browser requests and thus you can test your applications response without having to test it through your browser.
16 19 * By simply running your Rails tests you can ensure your code adheres to the desired functionality even after some major code refactoring.
@@ -63,7 +66,7 @@ The 'unit' folder is meant to hold tests for your models, 'functional' folder is
63 66
64 67 ==== What They Are ====
65 68
66   -Fixtures is a fancy word for 'sample data'. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent and assume one of two formats: *YAML* or *CSV*.
  69 +Fixtures is a fancy word for sample data. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent and assume one of two formats: *YAML* or *CSV*.
67 70
68 71 You'll find fixtures under your 'test/fixtures' directory. When you run `script/generate model` to create a new model, fixture stubs will be automatically created and placed in this directory.
69 72
@@ -92,7 +95,7 @@ Each fixture is given a 'name' followed by an indented list of colon-separated k
92 95
93 96 ==== Comma Seperated ====
94 97
95   -Fixtures can also be described using the all-too-familiar comma-separated value 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').
  98 +Fixtures can also be described using the all-too-familiar comma-separated value 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').
96 99
97 100 A CSV fixture looks like this:
98 101
@@ -111,7 +114,7 @@ The first line is the header. It is a comma-separated list of fields. The rest o
111 114 * don't use blank lines
112 115 * nulls can be achived by just placing a comma, for example, (1,sclaus,,false,) minus the parenthesis of course.
113 116
114   -Unlike the YAML format where you give each fixture a name, CSV fixture names are automatically generated. They follow a pattern of ``model-name''-''counter''. In the above example, you would have:
  117 +Unlike the YAML format where you give each fixture a name, CSV fixture names are automatically generated. They follow a pattern of ``model-name-counter''. In the above example, you would have:
115 118
116 119 --------------------------------------------------------------
117 120 celebrity-holiday-figures-1
@@ -497,7 +500,11 @@ You would get to see the usage of some of these assertions in the next chapter.
497 500
498 501 == Functional tests for your Controllers ==
499 502
500   -In Rails, testing various actions of a single controller is termed as writing functional tests for that controller. Controllers handle the incoming web requests to your application and eventually respond with a rendered view. Thus, you should test for things such as:
  503 +In Rails, testing various actions of a single controller is termed as writing functional tests for that controller. Controllers handle the incoming web requests to your application and eventually respond with a rendered view.
  504 +
  505 +=== What to include in your Functional Tests ===
  506 +
  507 +You should test for things such as:
501 508
502 509 * was the web request successful?
503 510 * were we redirected to the right page?
@@ -569,7 +576,7 @@ For those of you familiar with HTTP protocol, you'll know that get is a type of
569 576 * head
570 577 * delete
571 578
572   -All of request types are methods that you can use, however, you'll probably end up using the first two more ofter than the others.
  579 +All of request types are methods that you can use, however, you'll probably end up using the first two more often than the others.
573 580
574 581 === The 4 Hashes of the Apocolypse ===
575 582
@@ -577,27 +584,26 @@ After the request has been made by using one of the 5 methods (get, post, etc…
577 584
578 585 They are (starring in alphabetical order):
579 586
580   -assigns
  587 +`assigns`::
581 588 Any objects that are stored as instance variables in actions for use in views.
582 589
583   -cookies
  590 +`cookies`::
584 591 Any objects cookies that are set.
585 592
586   -flash
  593 +`flash`::
587 594 Any objects living in the flash.
588 595
589   -session
  596 +`session`::
590 597 Any object living in session variables.
591 598
592   -
593 599 As is the case with normal Hash objects, you can access the values by referencing the keys by string. You can also reference them by symbol name… except assigns. Check it out:
594 600
595   -flash["gordon"] flash[:gordon]
596   -session["shmession"] session[:shmession]
597   -cookies["are_good_for_u"] cookies[:are_good_for_u]
  601 + flash["gordon"] flash[:gordon]
  602 + session["shmession"] session[:shmession]
  603 + cookies["are_good_for_u"] cookies[:are_good_for_u]
598 604
599 605 # Because you can't use assigns[:something] for historical reasons:
600   -assigns["something"] assigns(:something)
  606 + assigns["something"] assigns(:something)
601 607
602 608 === Instance variables available ===
603 609
@@ -618,14 +624,58 @@ Another example that uses flash, assert_redirected_to, assert_difference
618 624 end
619 625 --------------------------------------------------
620 626
621   -=== Testing Views using assert_select ===
622   -http://api.rubyonrails.org/classes/ActionController/Assertions/SelectorAssertions.html#M000749
  627 +=== Testing Views ===
  628 +
  629 +Testing the response to your request by asserting the presence of key html elements and their content is a good practice. `assert_select` allows you to do all this by using a simple yet powerful syntax.
  630 +
  631 +[NOTE]
  632 +`assert_tag` is now deprecated in favor of `assert_select`
  633 +
  634 +`assert_select(selector, [equality], [message])`::
  635 +Ensures that the equality condition is met on the selected elements through the selector. The selector may be a CSS selector expression (String), an expression with substitution values, or an HTML::Selector object.
  636 +
  637 +`assert_select(element, selector, [equality], [message])`::
  638 +Ensures that the equality condition is met on all the selected elements through the selector starting from the _element_ (instance of HTML::Node) and its descendants.
  639 +
  640 +For example, you could verify the contents on the title element in your response with:
  641 +
  642 +[source,ruby]
  643 +--------------------------------------------------
  644 +assert_select 'title', "Welcome to Rails Testing Guide"
  645 +--------------------------------------------------
  646 +
  647 +You can also use nested `assert_select` blocks. In this case the inner `assert_select` will run the assertion on each element selected by the outer `assert_select` block.
  648 +
  649 +[source,ruby]
  650 +--------------------------------------------------
  651 +assert_select 'ul.navigation' do
  652 + assert_select 'li.menu_item'
  653 +end
  654 +--------------------------------------------------
  655 +
  656 +`assert_select` is really powerful and I would recommend you to go through its http://api.rubyonrails.com/classes/ActionController/Assertions/SelectorAssertions.html#M000749[documentation] for its advanced usage.
623 657
624 658 ==== Additional view based assertions ====
625 659
626   - * assert_select_rjs
627   - * assert_select_email
628   - * assert_select_encoded
  660 +`assert_select_email`::
  661 +Allows you to make assertions on the body of an e-mail.
  662 +
  663 +[source,ruby]
  664 +--------------------------------------------------
  665 +assert_select_email do
  666 + assert_select 'small', 'Please click the "Unsubscribe" link if you want to opt-out.'
  667 +end
  668 +--------------------------------------------------
  669 +
  670 +`assert_select_rjs`::
  671 +Allows you to make assertions on RJS response. `assert_select_rjs` has variants which allow you to narrow down upon the updated element or event a particular operation on an element.
  672 +
  673 +`assert_select_encoded`::
  674 +Allows you to make assertions on encoded HTML. It does this by un-encoding the contents of each element and then calling the block with all the un-encoded elements.
  675 +
  676 +`css_select(selector)`::
  677 +`css_select(element, selector)`::
  678 +Returns an array of all the elements selected by the _selector_. In the second variant it first matches the base _element_ and tries to match the _selector_ expression on any of its children. If there are no matches both variants return an empty array.
629 679
630 680 == Integration Testing ==
631 681
@@ -660,25 +710,30 @@ end
660 710 * You will have to include fixtures explicitly unlike unit and functional tests in which all the fixtures are loaded by default (through test_helper)
661 711 * Additional helpers: https?, https!, host!, follow_redirect!, post/get_via_redirect, open_session, reset
662 712
663   -
664   -== Guide TODO ==
665   - * What to test in unit tests
666   - * Testing views (assert_select)
667   - * Examples for integration test
668   - * Updating Rake tasks
669   - * Update sectino on testing file uploads
670   - * Updating the section on testing mailers
671   -
672   -== Rake tasks related to testing
673   -
674   -rake db:test:*
675   -
676   -rake test
677   -rake test:units
678   -rake test:functionals
679   -rake test:integration
680   -rake test:plugin
681   -
  713 +== Rake Tasks for Testing
  714 +
  715 +The table below lists all rake tasks that come along in the default Rakefile when you initiate a Rail project.
  716 +
  717 +.Default Rake tasks
  718 +[grid="all"]
  719 +-------------------------
  720 +Tasks Description
  721 +-------------------------
  722 +`rake test` Runs all unit, functional and integration tests. You can also simply run `rake` as _test_ target is default.
  723 +`rake test:units` Runs all the unit tests from 'test/unit'
  724 +`rake test:functionals` Runs all the functional tests from 'test/functional'
  725 +`rake test:integration` Runs all the integration tests from 'test/integration'
  726 +`rake test:recent` Tests recent changes
  727 +`rake test:uncommitted` Runs all the tests which are uncommitted. Only supports Subversion
  728 +`rake test:plugins` Run all the plugin tests from vendor/plugins/*/**/test (or specify with `PLUGIN=_name_`)
  729 +`rake db:test:clone` Recreate the test database from the current environment's database schema
  730 +`rake db:test:clone_structure` Recreate the test databases from the development structure
  731 +`rake db:test:load` Recreate the test database from the current schema.rb
  732 +`rake db:test:prepare` Check for pending migrations and load the test schema
  733 +`rake db:test:purge` Empty the test database.
  734 +-------------------------
  735 +
  736 +TIP: You can see all these rake task and their descriptions by running `rake --tasks --describe`
682 737
683 738 == Testing Your Mailers ==
684 739
@@ -877,3 +932,7 @@ class ActionMailer::Base
877 932 end
878 933 ----------------------------------------------------------------
879 934
  935 +== Guide TODO ==
  936 + * Describe _setup_ and _teardown_
  937 + * Examples for integration test
  938 + * Updating the section on testing mailers

0 comments on commit c492288

Please sign in to comment.
Something went wrong with that request. Please try again.