From 77f3ef436b9ccb4cb3e3adb180beb24f72a327cb Mon Sep 17 00:00:00 2001
From: Roland Swingler <roland.swingler@gmail.com>
Date: Thu, 18 Jun 2009 09:34:05 +0100
Subject: [PATCH] Adding information about sessions being disabled in the test environment to the documentation

---
 configuration.markdown |    5 ++++-
 testing.markdown       |   40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 1 deletions(-)

diff --git a/configuration.markdown b/configuration.markdown
index d67f57d..f8e5611 100644
--- a/configuration.markdown
+++ b/configuration.markdown
@@ -102,7 +102,10 @@ are disabled by default. Enable them with:
     set :sessions, true
 
 Sessions are implemented by inserting the [`Rack::Session::Cookie`][c]
-component into the application's middleware pipeline.
+component into the application's middleware pipeline. Note that even if
+sessions are enabled for your application, they will be disabled in the
+`test` environment - see [Testing Sinatra with Rack::Test](testing.html)
+ for more details.
 
 [c]: http://rack.rubyforge.org/doc/classes/Rack/Session/Cookie.html
 
diff --git a/testing.markdown b/testing.markdown
index c4fc97e..040ecc0 100644
--- a/testing.markdown
+++ b/testing.markdown
@@ -171,6 +171,46 @@ module in the `Test::Unit::TestCase` class:
 Now all `TestCase` subclasses will automatically have `Rack::Test`
 available to them.
 
+### Sessions in test cases
+
+Currently Sinatra disables sessions when you are operating in the `test` environment,
+to allow for passing specific session data for your test in the rack environment hash,
+as detailed above. The following test will fail:
+
+    # The application
+    enable :sessions
+
+    post "/greeting" do
+      session[:greeting] = "Hello, world!"
+    end
+
+    get "/greeting" do
+      session[:greeting]
+    end
+
+    # The test case method
+    def test_session_greeting
+      post "/greeting"
+      get "/greeting"
+      assert_equal "Hello, World!", last_response.body
+    end
+
+If you want to test sessions as above (for integration testing), there are several
+ possibilities. The first is to run your tests in a different environment:
+
+    Sinatra::Application.set :environment, :integration
+
+The second is to manually use `Rack::Session::Cookie` in the `app` method of your test
+case:
+
+    def app
+      Rack::Builder.new do
+        use Rack::Session::Cookie
+        run Sinatra::Application
+      end
+    end
+
+
 Test Framework Examples {#frameworks}
 -----------------------
 
-- 
1.6.0.4