Rewrite `activerecord/RUNNING_UNIT_TESTS`

`RUNNING_UNIT_TESTS` is written in an unclear and confusing manner. This commit
attempts to correct that.

Thanks to zzak and vipulnsward for feedback.

1 files changed, 27 insertions, 15 deletions

diff --git a/activerecord/RUNNING_UNIT_TESTS.rdoc b/activerecord/RUNNING_UNIT_TESTS.rdoc
index 2f3d516c43..c3ee34da55 100644
--- a/activerecord/RUNNING_UNIT_TESTS.rdoc
+++ b/activerecord/RUNNING_UNIT_TESTS.rdoc
@@ -1,31 +1,43 @@
 == Setup
 
-If you don't have the environment set make sure to read
-
-    http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#testing-active-record
+If you don't have an environment for running tests, read
+http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#setting-up-a-development-environment
 
 == Running the Tests
 
-You can run a particular test file from the command line, e.g.
+To run a specific test:
+
+  $ ruby -Itest test/cases/base_test.rb -n method_name
+
+To run a set of tests:
 
   $ ruby -Itest test/cases/base_test.rb
 
-To run a specific test:
+You can also run tests that depend upon a specific database backend. For
+example:
 
-  $ ruby -Itest test/cases/base_test.rb -n test_something_works
+  $ bundle exec rake test_sqlite3
 
-You can run with a database other than the default you set in test/config.yml, using the ARCONN
-environment variable:
+Simply executing <tt>bundle exec rake test</tt> is equivalent to the following:
 
-  $ ARCONN=postgresql ruby -Itest test/cases/base_test.rb
+  $ bundle exec rake test_mysql
+  $ bundle exec rake test_mysql2
+  $ bundle exec rake test_postgresql
+  $ bundle exec rake test_sqlite3
 
-You can run all the tests for a given database via rake:
+There should be tests available for each database backend listed in the {Config
+File}[rdoc-label:label-Config+File]. (the exact set of available tests is
+defined in +Rakefile+)
 
-  $ rake test_mysql
+== Config File
 
-The 'rake test' task will run all the tests for mysql, mysql2, sqlite3 and postgresql.
+If +test/config.yml+ is present, it's parameters are obeyed. Otherwise, the
+parameters in +test/config.example.yml+ are obeyed.
 
-== Custom Config file
+You can override the +connections:+ parameter in either file using the +ARCONN+
+(Active Record CONNection) environment variable:
+
+  $ ARCONN=postgresql ruby -Itest test/cases/base_test.rb
 
-By default, the config file is expected to be at the path test/config.yml. You can specify a
-custom location with the ARCONFIG environment variable.
+You can specify a custom location for the config file using the +ARCONFIG+
+environment variable.