Add some comments on testing Authlogic, with a link to Authlogic::Tes…

…tCase section of the documentation.

CHANGELOG.rdoc

@@ -5,6 +5,7 @@
 * Added option check_passwords_against_database for Authlogic::ActsAsAuthentic::Password to toggle between checking the password against the database value or the object value. Also added the same functionality to the instance method: valid_password?("password", true), where the second argument tells Authlogic to check the password against the database value. The default for this new feature is true.
 * Add a maintain_sessions configuration option to Authlogic::ActsAsAuthentic::SessionMaintenance as a "clearer" option to disable automatic session maintenance.
 * single_access_allowed_request_types can also be equal to :all instead of just [:all].
+* Refactor params_enabled? so that the single_access_allowed? method in controllers takes precedence.
 
 == 2.0.10 release 2009-4-21
 

README.rdoc

@@ -29,14 +29,14 @@ You can also log out / destroy the session:
 *	<b>Documentation:</b> http://authlogic.rubyforge.org
 *	<b>Repository:</b> http://github.com/binarylogic/authlogic/tree/master
 *	<b>Live example with OpenID "add on":</b> http://authlogicexample.binarylogic.com
-*	<b>Live example source with tutorial:</b> http://github.com/binarylogic/authlogic_example/tree/master
+*	<b>Live example repository with tutorial:</b> http://github.com/binarylogic/authlogic_example/tree/master
 *	<b>Tutorial: Reset passwords with Authlogic the RESTful way:</b> http://www.binarylogic.com/2008/11/16/tutorial-reset-passwords-with-authlogic
 * <b>Bugs / feature suggestions:</b> http://binarylogic.lighthouseapp.com/projects/18752-authlogic
 * <b>Google group:</b> http://groups.google.com/group/authlogic
 
-<b>Before contacting me, please read:</b>
+<b>Before contacting me directly, please read:</b>
 
-If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. I will *NOT* respond to emails that should otherwise be in lighthouse or google groups.
+If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.
 
 == Authlogic "add ons"
 
@@ -47,20 +47,20 @@ If you create one of your own, please let me know about it so I can add it to th
 
 == Documentation explanation
 
-You can find anything you want about Authlogic in the documentation, all that you need to do is understand the basic design behind it.
+You can find anything you want about Authlogic in the {documentation}, all that you need to do is understand the basic design behind it.
 
 That being said, there are 2 models involved during authentication. Your Authlogic model and your ActiveRecord model:
 
-1. <b>Authlogic::Session</b>, which manages sessions.
-2. <b>Authlogic::ActsAsAuthentic</b>, which adds in functionality to your ActiveRecord model.
+1. <b>Authlogic::Session</b>, your session models that extend Authlogic::Session::Base.
+2. <b>Authlogic::ActsAsAuthentic</b>, which adds in functionality to your ActiveRecord model when you call acts_as_authentic.
 
 Each of the above has its various sub modules that contain common logic. The sub modules are responsible for including *everything* related to it: configuration, class methods, instance methods, etc.
 
 For example, if you want to timeout users after a certain period of inactivity, you would look in <b>Authlogic::Session::Timeout</b>. To help you out, I listed the following "publicly relevant" modules with short descriptions. For the sake of brevity, there are more modules than listed here, the ones not listed are more for internal use, but you can easily read up on them in the {documentation}[http://authlogic.rubyforge.org].
 
 === Authlogic::ActsAsAuthentic sub modules
 
-These modules are for the acts_as_authentic method you call in your model. It contains all code for the "model side" of the authentication.
+These modules are for the ActiveRecord side of things, the models that call acts_as_authentic.
 
 * <b>Authlogic::ActsAsAuthentic::Base</b> - Provides the acts_as_authentic class method and includes all of the submodules.
 * <b>Authlogic::ActsAsAuthentic::Email</b> - Handles everything related to the email field.
@@ -77,7 +77,7 @@ These modules are for the acts_as_authentic method you call in your model. It co
 
 === Authlogic::Session sub modules
 
-These modules are for the "session side" of authentication. They create a new domain for session logic, allowing you to create, destroy, and ultimately manage your sessions.
+These modules are for the models that extend Authlogic::Session::Base.
 
 * <b>Authlogic::Session::BruteForceProtection</b> - Disables accounts after a certain number of consecutive failed logins attempted.
 * <b>Authlogic::Session::Callbacks</b> - Your tools to extend, change, or add onto Authlogic. Lets you hook in and do just about anything you want. Start here if you want to write a plugin or add on for Authlogic
@@ -97,7 +97,7 @@ These modules are for the "session side" of authentication. They create a new do
 
 === Miscellaneous modules
 
-Miscellaneous modules that don't really belong solely to either the session or model aspect.
+Miscellaneous modules that shared across the authentication process and are more "utility" modules and classes.
 
 * <b>Authlogic::AuthenticatesMany</b> - Responsible for allowing you to scope sessions to a parent record. Similar to a has_many and belongs_to relationship. This lets you do the same thing with sessions.
 * <b>Authlogic::CryptoProviders</b> - Contains various encryption algorithms that Authlogic uses, allowing you to choose your encryption method.
@@ -183,6 +183,14 @@ Or you install this as a plugin (for older versions of rails)
 
 See the {authlogic example}[http://github.com/binarylogic/authlogic_example/tree/master] for a detailed setup tutorial. I did this because not only do you have a tutorial to go by, but you have an example app that uses the same tutorial, so you can play around with with the code. If you have problems you can compare the code to see what you are doing differently.
 
+== Testing
+
+I think one of the best aspects of Authlogic is testing. For one, it cuts out <b>a lot</b> of redundant tests in your applications because Authlogic is already thoroughly tested for you. It doesn't include a bunch of tests into your application, because it comes tested, just like any other library.
+
+For example, think about ActiveRecord. You don't test the internals of ActiveRecord, because the creators of ActiveRecord have already tested the internals for you. It wouldn't make sense for ActiveRecord to copy it's hundreds of tests into your applications. The same concept applies to Authlogic. You only need to test code you write that is specific to your application, just like everything else in your application.
+
+That being said, testing your code that uses Authlogic is easy. Since everyone uses a different testing suite, I created a helpful module called Authlogic::TestCase, which is basically a set of tools for testing authlogic. I explain testing Authlogic thoroughly in the {Authlogic::TestCase section of the documentation}[http://authlogic.rubyforge.org/classes/Authlogic/TestCase.html]. It should answer any questions you have in regards to testing Authlogic.
+
 == Tell me quickly how Authlogic works
 
 Interested in how all of this all works? Think about an ActiveRecord model. A database connection must be established before you can use it. In the case of Authlogic, a controller connection must be established before you can use it. It uses that controller connection to modify cookies, the current session, login with HTTP basic, etc. It connects to the controller through a before filter that is automatically set in your controller which lets Authlogic know about the current controller object. Then Authlogic leverages that to do everything, it's a pretty simple design.

lib/authlogic/session/params.rb

@@ -51,7 +51,7 @@ def params_key(value = nil)
         # Specify a list of allowed request types and single access authentication will only be allowed for the ones you specify.
         #
         # * <tt>Default:</tt> ["application/rss+xml", "application/atom+xml"]
-        # * <tt>Accepts:</tt> String of a request type, or :all to allow single access authentication for any and all request types
+        # * <tt>Accepts:</tt> String of a request type, or :all or :any to allow single access authentication for any and all request types
         def single_access_allowed_request_types(value = nil)
           config(:single_access_allowed_request_types, value, ["application/rss+xml", "application/atom+xml"])
         end
@@ -75,7 +75,7 @@ def params_enabled?
             when Array
               single_access_allowed_request_types.include?(controller.request_content_type) || single_access_allowed_request_types.include?(:all)
             else
-              single_access_allowed_request_types == :all
+              [:all, :any].include?(single_access_allowed_request_types)
             end
           end
 

lib/authlogic/test_case.rb

@@ -5,10 +5,25 @@
 require File.dirname(__FILE__) + "/test_case/mock_request"
 
 module Authlogic
-  # This is a collection of methods and classes that help you easily test Authlogic. In fact, I use these same tools
-  # to test the internals of Authlogic.
+  # I get a lot of questions about how to properly test with Authlogic. As a result, I did my due diligence writing this
+  # documentation. I apologize if it is a little wordy, but my intention is to cover every aspect of testing.
   #
-  # Some important things to keep in mind when testing:
+  # To get started, this module is a collection of methods and classes that help you easily test Authlogic. In fact,
+  # I use these same tools to test the internals of Authlogic.
+  #
+  # === Setting up
+  #
+  # Authlogic comes with some simple testing tools. To get these, you need to first require Authlogic's TestCase. If
+  # you are doing this in a rails app, you would require this file at the top of your test_helper.rb file:
+  #
+  #   require "authlogic/test_case"
+  #
+  # If you are using Test::Unit::TestCase, the standard testing library that comes with ruby, then you can skip this part.
+  # If you are not, you need to include the Authlogic::TestCase into your testing suite as follows:
+  #
+  #   include Authlogic::TestCase
+  #
+  # Now that everything is ready to go, let's move onto actually testing. Here is the basic idea behind testing:
   #
   # Authlogic requires a "connection" to your controller to activate it. In the same manner that ActiveRecord requires a connection to
   # your database. It can't do anything until it gets connnected. That being said, Authlogic will raise an
@@ -18,30 +33,38 @@ module Authlogic
   # === Functional tests
   #
   # Activating Authlogic isn't a problem here, because making a request will activate Authlogic for you. The problem is
-  # logging users in so they can access restricted areas. Solvin this is simple, just do this:
+  # logging users in so they can access restricted areas. Solving this is simple, just do this:
   #
   #   setup :activate_authlogic
   #
-  # Now log users in using Authlogic:
+  # For those of you unfamiliar with TestUnit, the setup method bascially just executes a method before any test is ran.
+  # It is essentially "setting up" your tests.
+  #
+  # Once you have done this, just log users in like usual:
   #
   #   UserSession.create(users(:whomever))
+  #   # access my restricted area here
   #
   # Do this before you make your request and it will act as if that user is logged in.
   #
   # === Integration tests
   #
   # Again, just like functional tests, you don't have to do anything. As soon as you make a request, Authlogic will be
-  # conntected.
+  # conntected. If you want to activate Authlogic before making a request follow the same steps described in the
+  # "functional tests" section above. It works in the same manner.
   #
   # === Unit tests
   #
-  # The only time you need to do any trickiness here is if you want to test Authlogic yourself. Maybe you added some custom
-  # code or methods in your Session class. Maybe you are writing a plugin or a library that extends Authlogic. Whatever it is
-  # you need to make sure your code is tested and working properly.
+  # The only time you need to do any trickiness here is if you want to test Authlogic models. Maybe you added some custom
+  # code or methods in your Authlogic models. Maybe you are writing a plugin or a library that extends Authlogic.
   #
-  # That being said, in this environment there is no controller. So you need to "fake" Authlogic into
-  # thinking there is. Don't worry, because the this module takes care of this for you. Just do the following
-  # in your test's setup and you are good to go:
+  # That being said, in this environment there is no controller. So you need to use a "mock" controller. Something
+  # that looks like a controller, acts like a controller, but isn't a "real" controller. You are essentially connecting
+  # Authlogic to your "mock" controller, then you can test off of the mock controller to make sure everything is functioning
+  # properly.
+  # 
+  # I use a mock controller to test Authlogic myself. It's part of the Authlogic library that you can easily use. It's as simple
+  # as functional and integration tests. Just do the following:
   #
   #   setup :activate_authlogic
   #
@@ -52,13 +75,7 @@ module Authlogic
   #   assert UserSession.create(ben)
   #   assert_equal controller.session["user_credentials"], ben.persistence_token
   #
-  # That's it.
-  #
-  # === How to use
-  #
-  # Just require the file in your test_helper.rb file.
-  #
-  #   require "authlogic/test_case"
+  # See how I am checking that Authlogic is interacting with the controller properly? That's the idea here.
   module TestCase
     # Activates authlogic so that you can use it in your tests. You should call this method in your test's setup. Ex:
     #
@@ -74,5 +91,5 @@ def controller
     end
   end
 
-  ::Test::Unit::TestCase.send(:include, TestCase)
+  ::Test::Unit::TestCase.send(:include, TestCase) if defined?(::Test::Unit::TestCase)
 end