sinatra-sessionography 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE.markdown

@@ -0,0 +1,113 @@
+The Don't Be a Dick License
+===========================
+_version 0.2_
+
+**Project:** [Sinatra::Sessionography](http://github.com/SFEley/sinatra-sessionography)   
+**Author:** Stephen Eley (<sfeley@gmail.com>)
+
+This is a proposed draft of the **Don't Be a Dick** license for open source projects.  The purpose of this license is to permit the broadest feasible scope for reuse and modification of creative work, restricted only by the requirement that one is not a dick about it.
+
+1. Legal Parameters
+-------------------
+For legal purposes, the DBAD license is a superset of the [Apache License, Version 2.0][1] and incorporates all terms, conditions, privileges and limitations therein.  The following text is a binding part of this license for this project:
+
+> Copyright 2010 Stephen Eley
+
+> Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+>   <http://www.apache.org/licenses/LICENSE-2.0>
+
+> Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  
+Nothing in the following text should be construed to inhibit, contradict, or override any part of the Apache License, Version 2.0.  
+
+2. Definitions
+--------------
+The following terms and definitions shall be in effect for the rest of this document.
+
+>  **NOTE:** Singular nouns and pronouns are used throughout this License for 
+  grammatical convenience.  However, any of the terms below _may_ refer to a
+  collective work or group of people.  If this pegs your punctiliousness, you
+  are directed to mentally substitute "Person _or persons_," "Dick _or 
+  dicks,_" etc., throughout this license.  Just don't tell us about it.
+
+### A. Project
+
+A creative work of (software | writing | visual art | music) into which significant time and energy have been invested by people who _are not you,_ and which has been released into the world for the benefit of the general public (_including you._)
+
+The **Project** may include, incorporate, derive from, or be inspired by other works.  The Author, being a Reasonable Person, has made use of such source materials only as permitted by their own licenses or applicable law.  The License you are reading applies only to those portions of the Project which are original and distinct to it.  Source materials may be covered by their own licenses or conditions, and should not be assumed to have coverage under this License.  (However, you are strongly encouraged not to be a dick about them either.)
+
+### B. Author
+
+A person who has invested significant time and energy into the Project licensed herein.  Given the Author's release of the Project to the world under a liberal license, the Author is declared a Reasonable Person (at least within this context) and inherits all attributes, freedoms, and responsibilities thereof.  No other assumptions are made about the Author, nor should you make any.
+
+### C. Reasonable Person
+
+A person who respects the time and energy that have been invested in the Project licensed herein, and acts accordingly.  A Reasonable Person is broadly characterized as one who exercises his or her privilege to use, _not_ use, redistribute, modify, improve, worsen, review, report issues upon, participate in the community of, or ignore the work _without_ placing undue demands upon the Author.  I.e., a Reasonable Person is a constituent of the majority of open source users and the population at large who are not Dicks.
+
+### D. Dick
+
+A person who _does not_ respect the time and energy that have been invested in the Project, and acts to punish such effort by giving others associated with the Project -- including, but not limited to, the Author -- a hard time.  A Dick is nearly always selfish, but not necessarily with deliberate intent; some Dicks are merely thoughtless.  The distinguishing characteristic of a Dick is that he or she places burdens upon Reasonable People, reducing their motivation to engage in open source activities.  This damping effect is a significant detriment to the Project, to open source in general, to the production of new intellectual value in the world -- and, ultimately, to the Dick himself or herself.
+
+>  **NOTE:** Despite its original gender association, the word "Dick" is used herein in a _cultural_ context and not a _genital_ context.  This License has chosen to adopt the term for its linguistic force and psychological impact, and sincerely regrets any inference of sexism.  For purposes of the terms and conditions contained herein, it is understood that both men and women are equally capable of being Dicks.  
+  
+>  (But they shouldn't be.)  
+  
+3. Permissions
+--------------
+
+The following privileges are granted explicitly and exclusively to Reasonable People.  Although the Author acknowledges the practical unfeasibility of barring Dicks from enjoying the same privileges, they are nevertheless asked to refrain from any activity related to the Project _and/or_ to reconsider their behavior and stop being Dicks.
+
+1. You are permitted to use the Project or any component of the Project.
+
+2. You are permitted to redistribute the Project or any component of the Project, by itself or as part of a different work, provided that you give fair and reasonable credit back to the Author.
+
+3. You are permitted to change the Project for your own needs or anyone else's.  You may keep your changes to yourself or submit them back to the Author or the community, as you see fit, provided you are not a Dick about it.
+
+4. You are permitted and encouraged to participate in any community related to the Project, or to create new communities.
+
+5. You are permitted to report issues or problems with the Project, and to request that they be addressed, so long as the request is made in a reasonable fashion.  (This privilege does _not_ oblige the Author to respond.)
+
+6. You are permitted to make money from the Project.  No recompense is owed to the Author unless by separate agreement, although sharing opportunities for mutual benefit is by no means discouraged.
+
+7. You are permitted to discuss the Project in any medium, in any positive or negative spirit, so long as criticism is not libelous nor _ad hominem._  (I.e., don't lie, and keep it about the _work_ and not the _people._)
+
+8. You are permitted to ignore the Project completely and make no use of it whatsoever.  This right is irrevocable and absolute, and extended to Dicks and Reasonable People alike.
+
+4. Limitations
+--------------
+
+The following restrictions are imposed explicitly and exclusively upon Dicks.  These limitations are the inverse of the above privileges and are also tautological, as the prohibited actions are those _definitive_ of Dickhood.
+
+1. You may not impede Reasonable People from exercising their privilege to use, redistribute, change, participate in, profit from, discuss, or ignore the Project.
+
+2. You may not withhold the Author's credit for the Project, nor otherwise present the work of anyone else as your own.
+
+3. You may not hold the Author responsible for any use or abuse of the Project by you or anyone else.
+
+4. You may not troll, flame, nor dumb down any community associated with the Project.
+
+5. Barring separate agreements, you may not _demand_ any time or attention on the part of the Author nor anyone else in the community.  You may not hold the Author personally accountable for any issues you discover nor otherwise spread your own problems to other people.
+
+6. You may not attempt to _compel_ time nor money from the Author nor any other community member by any means, including but not limited to legal action, intimidation, or annoyance.  
+
+7. You may not engage in _ad hominem_ (i.e. personal) attacks or criticism of the Author in the course of criticizing the Project.
+
+8. You may not impede the absolute and irrevocable privilege of the Author and other members of the community to ignore you.  
+
+5. Use of This License
+----------------------
+The Don't Be a Dick License is released under the terms of the Don't Be a Dick License. Projects released under this License should remain under the License, and the terms of the License may not be modified by anyone other than the Project's original Author.
+  
+If you wish to make use of the License for your own open work, you may do so without asking permission, provided said work is truly your own, truly open, and you are truly not a Dick. You may modify the terms of the License to suit your own needs, but are strongly advised to annotate said changes.  Modifications may not reduce the freedoms granted to Reasonable People as described in Section 3.
+
+Reasonable People are _invited,_ but not compelled, to visit the Web site at <http://dbad-license.org> and browse or add their project to the repository of works released under the License.
+ 
+
+[1]: http://apache.org/licenses/LICENSE-2.0

data/README.markdown

@@ -0,0 +1,78 @@
+Sessionography
+==============
+
+This is a simple testing helper for Sinatra sessions. It was written because
+having to use [this sort of approach][1] to test sessions made me sad.
+Sessionography replaces Sinatra's `session` helper with a reference to a
+simple hash in a module variable, enabling session calls that maintain state
+across requests without the complexity and limitations of trying to use
+`Rack::Session` with [Rack::Test][2].
+
+It will not help you sing better. It does not make omelettes. And if you're
+testing something that actually _cares_ about how sessions get set (e.g., if
+you're working on Sinatra itself or a low-level Rack component) you won't want
+to use this. But most of us just want to get on with testing our apps.
+
+Setting up
+----------
+    $ gem install sinatra-sessiongraphy
+
+(Or `sudo gem install` if you're the last person on Earth who isn't using [RVM][3] yet.)
+
+Then, in your **test\_helper.rb** file or your **spec\_helper.rb** file, just `require sinatra/sessionography`.  If you're using the **Sinatra::Base** style you'll also need to explicitly include the helper:
+
+    # spec_helper.rb
+    require 'myapp'
+    require 'sinatra/sessionography'
+    
+    MyApp.helpers Sinatra::Sessionography
+
+    
+Testing Tips
+------------
+Your app code can continue to call `session[:whatever]` as it already does.  It'll simply bypass any `Rack::Session` middleware and set a hash in memory.  
+
+If you'd like to access that hash in your test cases, there are module methods available: 
+
+    # This example is in RSpec, because that is how I roll.
+    describe HypotheticalApp do
+      before(:each) do
+        # You should initialize the session every time, with a .clear or
+        # an assignment.  Here, we simulate pre-existing state.
+        Sinatra::Sessionography.session = {:foo => 'bar', :too => 'tar'}
+      end
+      
+      it "should do something to the session" do
+        post "/something", {:hey => :ho}
+        Sinatra::Sessionography.session['hey'].should == 'ho'
+      end
+      
+      it "should pay attention to the session" do
+        Sinatra::Sessionography.session[:user] = User.find_by_name('Tina Fey')
+        get "/something"
+        last_response.body.should =~ /Tina Fey/
+      end
+      
+    end
+
+The session will of course persist across Sinatra requests.  That's the point of a session.  However, it will _also_ persist between test cases, which is probably not what you want, so in your setup or teardown code you should always call `Sinatra::Sessionography.session.clear` or else set it to _nil_ or some other useful value.
+
+Future Enhancements
+-------------------
+I knocked this off quickly because I needed it (for [Sinatra::Flash][4]) but it'd be fairly easy to give it a few other features useful for testing:
+
+* Multiple sessions scoped by name, for simulating interactions between different users;
+* Logging or remembering of changes to session state, so that test cases can trace more complex interactions with the session over time;
+* Generalization to a Rack::Session::Test (or perhaps Rack::MockSession) component for testing Rack applications outside of just Sinatra.
+
+I don't need any of those _today,_ so I'm not going to build them right away.  But if you'd like to see them, feel free to leave an issue here and let me know.  (Or just build it and contribute back, of course.  The source, it is open like the sky.)
+
+
+License
+-------
+This project is licensed under the [Don't Be a Dick License][5], version 0.2, and is copyright 2010 by Stephen Eley. See the [LICENSE.markdown][5] file for elaboration on not being a dick.
+
+[1]:http://groups.google.com/group/sinatrarb/msg/338ece48db7963cf
+[2]:http://github.com/brynary/rack-test
+[3]:http://rvm.beginrescueend.com
+[4]:http://github.com/SFEley/sinatra-flash

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sinatra-sessionography"
+    gem.summary = %Q{A simple sessions stub for testing Sinatra}
+    gem.description = %Q{Sessionography has only one function: to replace Sinatra's session methods with a basic hash that persists across requests.  Bypassing Rack::Session removes nearly all the complexity of unit and integration testing with session data.}
+    gem.email = "sfeley@gmail.com"
+    gem.homepage = "http://github.com/SFEley/sinatra-sessionography"
+    gem.authors = ["Stephen Eley"]
+    gem.add_dependency "sinatra", ">= 1.0" 
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/sinatra/sessionography.rb

@@ -0,0 +1,45 @@
+require 'sinatra/base'
+
+module Sinatra
+  # Eases testing by overriding Sinatra's #session helper to access a module hash.  Also
+  # provides a direct module method to that hash for test verification.  
+  # 
+  # If your application is using the {Sinatra::Base} style (as you probably should most of the time
+  # you'll also need to include this module as a helper when setting up your test suite:
+  # 
+  # @example (Assuming your app is declared with `class MyApp < Sinatra::Base`)
+  #   require 'myapp'
+  #   require 'sinatra/sessionography'
+  #   MyApp.helpers Sinatra::Sessionography
+  module Sessionography
+    
+    # Use this in your test cases to get or set session variables outside of your application code.
+    #
+    # @return [Hash] A session hash.
+    def self.session
+      @session ||= {}
+    end
+    
+    # Set up the session with a copy of your own hash for testing. (Optional; it'll default to an  
+    # empty hash or to the contents of 'rack.session' if you don't do this.)
+    # 
+    # @param [Hash] val The hash to use as the session. Note that we clone the object; we don't maintain
+    #   a live link to the same hash.
+    def self.session=(val)
+      @session = val.clone
+    end
+    
+    # Replaces Sinatra's #session helper to completely bypass Rack::Session, thus mocking out 
+    # sessions in tests.
+    #
+    # Let's be clear: this session is _global._  Not per-user.  *Using this in production code 
+    # would be bad.* (Important safety tip, thanks Egon.)
+    #
+    # @return [Hash] The same session hash accessible from {Sinatra::Sessionography.session}
+    def session
+      Sessionography.session
+    end
+  end
+  
+  helpers Sessionography
+end

data/sinatra-sessionography.gemspec

@@ -0,0 +1,61 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sinatra-sessionography}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Stephen Eley"]
+  s.date = %q{2010-04-26}
+  s.description = %q{Sessionography has only one function: to replace Sinatra's session methods with a basic hash that persists across requests.  Bypassing Rack::Session removes nearly all the complexity of unit and integration testing with session data.}
+  s.email = %q{sfeley@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.markdown",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE.markdown",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "lib/sinatra/sessionography.rb",
+     "sinatra-sessionography.gemspec",
+     "spec/sessionography_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/SFEley/sinatra-sessionography}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A simple sessions stub for testing Sinatra}
+  s.test_files = [
+    "spec/sessionography_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sinatra>, [">= 1.0"])
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<sinatra>, [">= 1.0"])
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<sinatra>, [">= 1.0"])
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end
+

data/spec/sessionography_spec.rb

@@ -0,0 +1,36 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Sinatra::Sessionography do
+  before(:each) do
+    Sinatra::Sessionography.session.clear
+  end
+  
+  it "shows an empty session when nothing is initialized" do
+    get "/session"
+    last_response.body.should == "{}"
+  end
+
+  it "writes sessions" do
+    post "/session", {:dog => :woof}
+    Sinatra::Sessionography.session[:dog].should == :woof
+  end
+  
+  it "reads sessions" do
+    Sinatra::Sessionography.session[:duck] = :quack
+    get "/session"
+    last_response.body.should == "{:duck=>:quack}"
+  end
+  
+  it "can be set with an initializing hash" do
+    Sinatra::Sessionography.session = {:sheep => :baa}
+    get "/session"
+    last_response.body.should == "{:sheep=>:baa}"
+  end
+  
+  it "persists state across requests" do
+    post "/session", {:snail=>:slurp, :monkey=>:howl, :deer=>'Shoot me!'}
+    post "/session", {:cow=>:moo, :deer=>nil}
+    get "/session"
+    last_response.body.should == "{:snail=>:slurp, :monkey=>:howl, :deer=>nil, :cow=>:moo}"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,32 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'sinatra'
+require 'rack/test'
+require 'spec'
+require 'spec/autorun'
+
+set :environment, :test
+require 'sinatra/sessionography'
+
+# Simple getter for testing
+get '/session' do
+  session.inspect
+end
+
+# Simple setter for testing
+post '/session' do
+  params.each{|k,v| session[k.to_sym] = (v.is_a?(String) ? v.to_sym : v)}
+  session.inspect
+end
+
+# Hook to our application so Rack::Test works; see: http://www.sinatrarb.com/testing.html
+module SinatraApp
+  def app
+    Sinatra::Application
+  end
+end
+
+Spec::Runner.configure do |config|
+  include SinatraApp
+  include Rack::Test::Methods
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: sinatra-sessionography
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Stephen Eley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-26 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: sinatra
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: "Sessionography has only one function: to replace Sinatra's session methods with a basic hash that persists across requests.  Bypassing Rack::Session removes nearly all the complexity of unit and integration testing with session data."
+email: sfeley@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.markdown
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE.markdown
+- README.markdown
+- Rakefile
+- VERSION
+- lib/sinatra/sessionography.rb
+- sinatra-sessionography.gemspec
+- spec/sessionography_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/SFEley/sinatra-sessionography
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A simple sessions stub for testing Sinatra
+test_files: 
+- spec/sessionography_spec.rb
+- spec/spec_helper.rb