sinatra-cache 0.2.3 → 0.3.0

data/lib/sinatra/output.rb

@@ -0,0 +1,147 @@
+
+# :stopdoc:
+unless Object.new.respond_to?(:blank?)
+  
+  class Object
+    def blank?
+      respond_to?(:empty?) ? empty? : !self
+    end
+    def present?
+      !blank?
+    end
+  end
+end
+# :startdoc:
+
+
+module Sinatra
+  
+  # Sinatra::Output Extension
+  # 
+  # Provides support for the :cache_fragment() functionality.
+  # 
+  # Thank You very much Nathan. Much appreciated!
+  # 
+  # 
+  # The code within this extension is almost in its interity copied from:
+  # 
+  #   sinatra_more gem [ http://github.com/nesquena/sinatra_more/ ] by Nathan Esquenazi.
+  # 
+  # 
+  # Copyright (c) 2009 Nathan Esquenazi
+  # 
+  # Permission is hereby granted, free of charge, to any person obtaining
+  # a copy of this software and associated documentation files (the
+  # "Software"), to deal in the Software without restriction, including
+  # without limitation the rights to use, copy, modify, merge, publish,
+  # distribute, sublicense, and/or sell copies of the Software, and to
+  # permit persons to whom the Software is furnished to do so, subject to
+  # the following conditions:
+  # 
+  # The above copyright notice and this permission notice shall be
+  # included in all copies or substantial portions of the Software.
+  # 
+  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+  # 
+  # 
+  module Output
+    
+    VERSION = Sinatra::Cache::VERSION
+    ##
+    # Returns the version string for this extension
+    # 
+    # ==== Examples
+    # 
+    #   Sinatra::Output.version  => 'Sinatra::Output v0.9.9'
+    # 
+    def self.version; "Sinatra::Output v#{VERSION}"; end
+    
+    
+    module Helpers
+      
+      # Captures the html from a block of template code for erb or haml
+      # capture_html(&block) => "...html..."
+      def capture_html(*args, &block)
+        if self.respond_to?(:is_haml?) && is_haml?
+           block_is_haml?(block) ? capture_haml(*args, &block) : block.call
+        elsif has_erb_buffer?
+          result_text = capture_erb(*args, &block)
+          result_text.present? ? result_text : (block_given? && block.call(*args))
+        else # theres no template to capture, invoke the block directly
+          block.call(*args)
+        end
+      end
+      
+      # Outputs the given text to the templates buffer directly
+      # concat_content("This will be output to the template buffer in erb or haml")
+      def concat_content(text="") 
+        if self.respond_to?(:is_haml?) && is_haml?
+          haml_concat(text)
+        elsif has_erb_buffer?
+          erb_concat(text)
+        else # theres no template to concat, return the text directly
+          text
+        end
+      end
+      
+      # Returns true if the block is from an ERB or HAML template; false otherwise.
+      # Used to determine if html should be returned or concatted to view
+      # block_is_template?(block)
+      def block_is_template?(block) 
+         block && (block_is_erb?(block) || (self.respond_to?(:block_is_haml?) && block_is_haml?(block)))
+      end
+      
+      
+      protected
+        
+        # Used to capture the html from a block of erb code
+        # capture_erb(&block) => '...html...'
+        def capture_erb(*args, &block) 
+          erb_with_output_buffer { block_given? && block.call(*args) }
+        end
+        
+        # Concats directly to an erb template
+        # erb_concat("Direct to buffer")
+        def erb_concat(text) 
+          @_out_buf << text if has_erb_buffer?
+        end
+        
+        # Returns true if an erb buffer is detected
+        # has_erb_buffer? => true
+        def has_erb_buffer? 
+          !@_out_buf.nil?
+        end
+        
+        # Used to determine if a block is called from ERB.
+        # NOTE: This doesn't actually work yet because the variable __in_erb_template 
+        # hasn't been defined in ERB. We need to find a way to fix this.
+        def block_is_erb?(block) 
+          has_erb_buffer? || block && eval('defined? __in_erb_template', block)
+        end
+        
+        # Used to direct the buffer for the erb capture
+        def erb_with_output_buffer(buf = '') #:nodoc: 
+          @_out_buf, old_buffer = buf, @_out_buf
+          yield
+          @_out_buf
+        ensure
+          @_out_buf = old_buffer
+        end
+        
+    end #/ Helpers
+    
+    # def self.registered(app)
+    #   app.helpers Sinatra::Output::Helpers
+    # end #/ self.registered
+    
+  end #/ Output
+  
+  helpers Sinatra::Output::Helpers
+  
+end #/ Sinatra

data/lib/sinatra/templates.rb

@@ -0,0 +1,55 @@
+
+module Sinatra 
+  
+  ##
+  # Sinatra::Templates
+  # 
+  # Monkey-patches the private <tt>#render</tt> method, 
+  # in order to support 'auto-magic' cache functionality.
+  # 
+  # 
+  module Templates 
+    
+    private
+      
+      def render(engine, data, options={}, locals={}, &block) 
+        # merge app-level options
+        options = settings.send(engine).merge(options) if settings.respond_to?(engine)
+        
+        # extract generic options
+        locals = options.delete(:locals) || locals || {}
+        views = options.delete(:views) || settings.views || "./views"
+        layout = options.delete(:layout)
+        layout = :layout if layout.nil? || layout == true
+        
+        # set the cache related options
+        cache_enabled = settings.respond_to?(:cache_enabled) ? settings.send(:cache_enabled) : false
+        cache_output_dir = settings.send(:cache_output_dir)  if settings.respond_to?(:cache_output_dir)
+        # raise Exception, "The Sinatra::Cache cache_output_dir variable is pointing to a non-existant directory cache_output_dir=[#{cache_output_dir}]" unless test(?d, cache_output_dir)
+        cache_option = options.delete(:cache)
+        cache_option = true if cache_option.nil?
+        
+        # compile and render template
+        template = compile_template(engine, data, options, views)
+        output = template.render(self, locals, &block)
+        
+        # render layout
+        if layout
+          begin
+            options = options.merge(:views => views, :layout => false)
+            output = render(engine, layout, options, locals) { output }
+            # Cache the content or just return it
+            (cache_enabled && settings.send(:environment) == settings.cache_environment) ? 
+                cache_write_file(cache_file_path, output.gsub(/\n\r?$/,"")) : output
+          rescue Errno::ENOENT
+          end
+        end
+        
+        # rendering without a layout
+        (cache_enabled && cache_option && settings.send(:environment) == settings.cache_environment) ? 
+            cache_write_file(cache_file_path, output.gsub(/\n\r?$/,"") ) : output
+      end
+      
+  end #/module Templates
+  
+end #/module Sinatra 

data/sinatra-cache.gemspec

@@ -5,44 +5,45 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sinatra-cache}
-  s.version = "0.2.3"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["kematzy"]
-  s.date = %q{2010-02-13}
-  s.description = %q{Simple Page Caching for Sinatra [www.sinatrarb.com]}
+  s.date = %q{2010-02-25}
+  s.description = %q{A Sinatra Extension that makes Page and Fragment Caching easy.}
   s.email = %q{kematzy@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.md"
+     "README.rdoc"
   ]
   s.files = [
     ".gitignore",
      "LICENSE",
-     "README.md",
+     "README.rdoc",
      "Rakefile",
-     "VERSION.yml",
+     "VERSION",
      "lib/sinatra/cache.rb",
+     "lib/sinatra/cache/helpers.rb",
+     "lib/sinatra/output.rb",
+     "lib/sinatra/templates.rb",
      "sinatra-cache.gemspec",
-     "test/SPECS.rdoc",
-     "test/cache_test.rb",
-     "test/fixtures/classic.rb",
-     "test/fixtures/myapp.rb",
-     "test/fixtures/myapp_default.rb",
-     "test/fixtures/views/index.erb",
-     "test/helper.rb"
+     "spec/fixtures/apps/base/views/css.sass",
+     "spec/fixtures/apps/base/views/fragments.erb",
+     "spec/fixtures/apps/base/views/fragments_shared.erb",
+     "spec/fixtures/apps/base/views/index.erb",
+     "spec/fixtures/apps/base/views/layout.erb",
+     "spec/fixtures/apps/base/views/params.erb",
+     "spec/sinatra/cache_spec.rb",
+     "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/kematzy/sinatra-cache}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Simple Page Caching for Sinatra [www.sinatrarb.com]}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A Sinatra Extension that makes Page and Fragment Caching easy.}
   s.test_files = [
-    "test/fixtures/myapp_default.rb",
-     "test/fixtures/classic.rb",
-     "test/fixtures/myapp.rb",
-     "test/cache_test.rb",
-     "test/helper.rb"
+    "spec/sinatra/cache_spec.rb",
+     "spec/spec_helper.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -50,9 +51,18 @@ Gem::Specification.new do |s|
     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.a"])
+      s.add_development_dependency(%q<sinatra-tests>, [">= 0.1.6"])
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
     else
+      s.add_dependency(%q<sinatra>, [">= 1.0.a"])
+      s.add_dependency(%q<sinatra-tests>, [">= 0.1.6"])
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
     end
   else
+    s.add_dependency(%q<sinatra>, [">= 1.0.a"])
+    s.add_dependency(%q<sinatra-tests>, [">= 0.1.6"])
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
   end
 end
 

data/spec/fixtures/apps/base/views/css.sass

@@ -0,0 +1,2 @@
+body
+  :color red

data/spec/fixtures/apps/base/views/fragments.erb

@@ -0,0 +1,11 @@
+<h1>FRAGMENTS</h1>
+
+<% cache_fragment(:test_fragment) do %>
+<div id="cache-fragment">
+  <p><%= "Fragment created: #{Time.now.strftime("%Y-%m-%d %H:%M:%S")}" %></p>
+</div>
+<% sleep 1 %>
+<% end %>
+
+<h2>Content After Sleep</h2>
+<p><%= "Time is now: #{Time.now.strftime("%Y-%m-%d %H:%M:%S")}" %></p>

data/spec/fixtures/apps/base/views/fragments_shared.erb

@@ -0,0 +1,11 @@
+<h1>FRAGMENTS - SHARED</h1>
+
+<% cache_fragment(:test_fragment, :shared) do %>
+<div id="cache-fragment">
+  <p><%= "Shared Fragment created: #{Time.now.strftime("%Y-%m-%d %H:%M:%S")}" %></p>
+</div>
+<% sleep 1 %>
+<% end %>
+
+<h2>Content After Sleep</h2>
+<p><%= "Time is now: #{Time.now.strftime("%Y-%m-%d %H:%M:%S")}" %></p>

data/spec/fixtures/apps/base/views/layout.erb

@@ -0,0 +1,9 @@
+<html>
+  <head>
+    <title>Sinatra::Cache</title>
+    <%= cache_timestamp %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/spec/fixtures/apps/base/views/params.erb

@@ -0,0 +1,3 @@
+<h1>PARAMS</h1>
+<p><%=  @captures.join(" | ") %></p>
+<pre><%= params.inspect %></pre>

data/spec/sinatra/cache_spec.rb

@@ -0,0 +1,593 @@
+
+require "#{File.dirname(File.dirname(File.expand_path(__FILE__)))}/spec_helper"
+
+describe "Sinatra" do 
+  
+  before(:each) do 
+    @delete_cached_test_files = true #convenience toggle
+  end
+  describe "Cache" do 
+    
+    class MyDefaultsTestApp < MyTestApp
+      register(Sinatra::Cache)
+    end
+    
+    
+    class MyTestApp 
+      register(Sinatra::Cache)
+      
+      # need to set the root of the app for the default :cache_fragments_output_dir to work
+      set :root, ::APP_ROOT
+      
+      set :cache_enabled, true
+      set :cache_environment, :test
+      set :cache_output_dir, "#{public_fixtures_path}/system/cache"
+      set :cache_fragments_output_dir, "#{public_fixtures_path}/system/cache_fragments"
+      
+      get('/') { erb(:index) }
+      get('/erb/?') { erb(:index, :layout => false) }
+      
+      # complex regex URL, matches
+      get %r{^/params/?([\s\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?} do
+        @captures = params[:captures].nil? ? [] : params[:captures].compact
+        erb(:params)
+      end
+      get('/file-extensions.*') do 
+        @vars = { :framework => "Sinatra", :url => "www.sinatrarb.com" }
+        case params[:splat].first.to_sym
+        when :json
+          erb(@vars.to_json, :layout => false )
+        when :yaml
+          erb(@vars.to_yaml,:layout => false) 
+        else
+          # direct output, should NOT be Cached
+          @vars.inspect
+          # @vars.inspect
+        end
+      end
+      
+      get '/css/screen.css' do 
+        content_type 'text/css'
+        sass(:css, :style => :compact)
+      end
+      get '/css/no/cache.css' do 
+        content_type 'text/css'
+        sass(:css, :style => :compact, :cache => false)
+      end
+      
+      # enable :method_override
+      post('/post/?') { erb("POST", :layout => false) }
+      put('/put/?') { erb('PUT', :layout => false) }
+      delete('/delete/?') { erb('DELETE', :layout => false) }
+      
+      get %r{^/fragments/?([\s\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?} do
+        erb(:fragments, :layout => false, :cache => false) 
+      end
+      get %r{^/sharedfragments/?([\s\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?} do
+        erb(:fragments_shared, :layout => false, :cache => false) 
+      end
+      
+      
+    end
+    
+    
+    it_should_behave_like "MyTestApp"
+    
+    # it_should_behave_like "debug => app.methods"
+    
+    describe "VERSION" do 
+      
+      it "should return the VERSION string" do 
+        Sinatra::Cache::VERSION.should be_a_kind_of(String)
+        Sinatra::Cache::VERSION.should match(/\d\.\d+\.\d+(\.\d)?/)
+      end
+      
+    end #/ VERSION
+    
+    describe "#self.version" do 
+      
+      it "should return a version of the Sinatra::Cache VERSION string" do 
+        Sinatra::Cache.version.should be_a_kind_of(String)
+        Sinatra::Cache.version.should match(/Sinatra::Cache v\d\.\d+\.\d+(\.\d)?/)
+      end
+      
+    end #/ #self.version
+    
+    
+    describe "Configuration" do 
+      
+      describe "with Default Settings" do 
+        
+        it "should set :cache_enabled to false" do 
+          MyDefaultsTestApp.cache_enabled.should == false
+        end
+        
+        it "should set :cache_environment to :production" do 
+          MyDefaultsTestApp.cache_environment.should == :production
+        end
+        
+        it "should set :cache_page_extension to '.html'" do 
+          MyDefaultsTestApp.cache_page_extension.should == '.html'
+        end
+        
+        it "should set :cache_output_dir to '../public'" do 
+          MyDefaultsTestApp.cache_output_dir.should == "#{public_fixtures_path}"
+        end
+        
+        it "should set :cache_fragments_output_dir to '../tmp/cache_fragments'" do 
+          MyDefaultsTestApp.cache_fragments_output_dir.should == "#{fixtures_path}/tmp/cache_fragments"
+        end
+        
+        it "should set :cache_logging to true" do 
+          MyDefaultsTestApp.cache_logging.should == true
+        end
+        
+        it "should set :cache_logging_level to :info" do 
+          MyDefaultsTestApp.cache_logging_level.should == :info
+        end
+        
+      end #/ with Default Settings
+      
+      describe "with Custom Settings" do 
+        
+        it "should set :cache_enabled to true" do 
+          MyTestApp.cache_enabled.should == true
+        end
+        
+        it "should set :cache_environment to :test" do 
+          MyTestApp.cache_environment.should == :test
+        end
+        
+        it "should set :cache_page_extension to '.html'" do 
+          MyTestApp.cache_page_extension.should == '.html'
+        end
+        
+        it "should set :cache_output_dir to '../public/system/cache'" do 
+          MyTestApp.cache_output_dir.should == "#{public_fixtures_path}/system/cache"
+        end
+        
+        it "should set :cache_fragments_output_dir to '../public/system/cache_fragments'" do 
+          MyTestApp.cache_fragments_output_dir.should == "#{public_fixtures_path}/system/cache_fragments"
+        end
+        
+        it "should set :cache_logging to true" do 
+          MyTestApp.cache_logging.should == true
+        end
+        
+        it "should set :cache_logging_level to :info" do 
+          MyTestApp.cache_logging_level.should == :info
+        end
+        
+      end #/ Custom
+      
+    end #/ Configuration
+    
+    
+    describe "Helpers" do 
+      
+      describe "#cache_timestamp" do 
+        
+        it "should return an HTML comment with the current timestamp" do 
+          erb_app "<%= cache_timestamp %>"
+          body.should match(/\<\!-- page cached\: #{Regexp.escape(Time.now.strftime("%Y-%m-%d %H:%M:%S"))} -->/)
+        end
+        
+      end #/ #cache_timestamp
+      
+      module Sinatra::Cache::Helpers
+        public :cache_file_path, :cache_write_file, :cache_file_name, :cache_page_path
+      end
+      
+      describe "#cache_file_path" do 
+        
+        it "should have some tests"
+        
+      end #/ #cache_file_path
+      
+      describe "#cache_write_file" do 
+        
+        it "should have some tests"
+        
+      end #/ #cache_write_file
+      
+      describe "#cache_file_name" do 
+        
+        it "should have some tests"
+        
+      end #/ #cache_file_name
+      
+      describe "#cache_page_path" do 
+        
+        it "should have some tests"
+        
+      end #/ #cache_page_path
+      
+    end #/ Helpers
+    
+    
+    describe "with caching enabled" do 
+      
+      describe "basic Page caching" do 
+        
+        describe "GET requests for" do 
+          
+          describe "the Home page - ['/' => /index.html] (with layout)" do 
+            
+            before(:each) do 
+              @cache_file = "#{public_fixtures_path}/system/cache/index.html"
+              get('/')
+            end
+            
+            after(:each) do
+              FileUtils.rm(@cache_file) if @delete_cached_test_files
+            end
+            
+            it "should render the expected output" do 
+              body.should have_tag('html > head > title', 'Sinatra::Cache') 
+              body.should match(/<!-- page cached: #{Regexp.escape(Time.now.strftime("%Y-%m-%d %H:%M:%S"))} -->/)
+              body.should have_tag('html > body > h1', 'HOME')
+            end
+            
+            it "should create a cached file in the cache output directory" do 
+              test(?f, @cache_file).should == true
+            end
+            
+          end #/ GET ['/' => /index.html]
+          
+          describe "a basic URL without a trailing slash - ['/erb' => /erb.html] (ERB without layout)" do 
+            
+            before(:each) do 
+              @cache_file = "#{public_fixtures_path}/system/cache/erb.html"
+              get('/erb')
+            end
+            
+            after(:each) do 
+              FileUtils.rm(@cache_file) if @delete_cached_test_files
+            end
+            
+            it "should render the expected output" do 
+              body.should == "<h1>HOME</h1>"
+            end
+            
+            it "should create a cached file in the cache output directory" do 
+              test(?f, @cache_file).should == true
+            end
+            
+          end #/ GET ['/erb' => /erb.html]
+          
+          describe "a basic URL with a trailing slash - ['/erb/' => /erb/index.html]" do 
+            
+            before(:each) do 
+              @cache_file = "#{public_fixtures_path}/system/cache/erb/index.html"
+              get('/erb/')
+            end
+            
+            after(:each) do 
+              FileUtils.rm(@cache_file) if @delete_cached_test_files
+            end
+            
+            it "should render the expected output" do 
+              body.should == "<h1>HOME</h1>"
+            end
+            
+            it "should create a cached file at ../cache/< URL >/index.html" do
+              test(?f, @cache_file).should == true
+            end
+            
+          end #/ GET ['/erb/' => /erb/index.html]
+          
+          describe "a URL with file extension - ['/file-extensions.EXT' => /file-extensions.EXT]" do 
+            
+            before(:each) do 
+              ext =  '.yaml'
+              @cache_file = "#{public_fixtures_path}/system/cache/file-extensions#{ext}"
+              get("/file-extensions#{ext}") 
+            end
+            
+            after(:each) do 
+              FileUtils.rm(@cache_file) if @delete_cached_test_files
+            end
+            
+            it "should render the expected output" do 
+              body.should_not == ""
+            end
+            
+            it "should create the cached file with the extension" do 
+              test(?f, @cache_file).should == true
+            end
+            
+          end #/ GET ['/file-extensions.EXT' => /file-extensions.EXT]
+          
+          describe "URLs with multiple levels and/or with ?params attached" do 
+            
+            %w(
+              /params/? /params/1.xml?p=2 /params/page/?page=2 /params/page/?page=99 
+              /params/a/  /params/a/b /params/a/b/c /params/a/b/c/d 
+            ).each do |url| 
+              
+              # does the URL contain a ? or not
+              params_free_url = url =~ /\?/ ? url.split('?').first.chomp('?') : url
+              file_url = (params_free_url[-1,1] =~ /\//) ? "#{params_free_url}index" : params_free_url
+              
+              # create the string for the test output below
+              file_url_str = File.extname(file_url) == '' ? file_url << '.html' : file_url 
+              
+              describe "the URL ['#{url}' => #{file_url_str}]" do 
+                
+                before(:each) do 
+                  @file_url = file_url
+                  @cache_file = "#{public_fixtures_path}/system/cache#{file_url}"
+                  @cache_file << ".html" if File.extname(@file_url) == '' 
+                  # puts "when the URL=[#{url}] the @cache_file=[#{@cache_file}] [#{__FILE__}:#{__LINE__}]"
+                  get(url)
+                end
+                
+                after(:each) do 
+                  FileUtils.remove_dir("#{public_fixtures_path}/system/cache/params") if @delete_cached_test_files
+                end
+                
+                it "should render the expected output" do 
+                  body.should have_tag('html > head > title', 'Sinatra::Cache') 
+                  body.should have_tag('html > body > h1', 'PARAMS')
+                  body.should have_tag('html > body > p' )
+                end
+                
+                it "should create a cached file at [../public/system/cache#{file_url_str}]" do 
+                  test(?f, @cache_file).should == true
+                end
+                
+              end #/ GET 'url' - 
+              
+            end #/ end loop
+            
+          end #/ URLs with multiple levels and/or with ?params attached
+          
+          describe "CSS URLs with dynamic .sass files" do 
+            
+            describe "the URL ['/css/screen.css' => /css/screen.css]" do 
+              
+              before(:each) do 
+                @cache_file = "#{public_fixtures_path}/system/cache/css/screen.css"
+                FileUtils.remove_dir(File.dirname(@cache_file), :force => true )
+                get('/css/screen.css')
+              end
+              
+              after(:each) do 
+                FileUtils.rm(@cache_file) if @delete_cached_test_files
+                FileUtils.remove_dir(File.dirname(@cache_file), :force => true ) if @delete_cached_test_files
+              end
+              
+              it "should output the correct CSS as expected" do 
+                body.should == "body { color: red; }"
+              end
+              
+              it "should automatically create the cache /css output directory" do 
+                test(?d, File.dirname(@cache_file) ).should == true
+              end
+              
+              it "should create a cached file at [../public/system/cache/css/screen.css]" do 
+                test(?f, @cache_file).should == true
+              end
+              
+            end #/ GET ['/css/screen.css' => /css/screen.css]
+            
+            describe "URLs with ':cache => false' - ['/css/no/cache.css' => /css/no/cache.css]" do 
+              
+              before(:each) do 
+                @cache_file = "#{public_fixtures_path}/system/cache/css/no/cache.css"
+                get('/css/no/cache.css')
+              end
+              
+              it "should output the correct CSS as expected" do 
+                body.should == "body { color: red; }\n"
+              end
+              
+              it "should NOT cache the output" do 
+                test(?d, File.dirname(@cache_file) ).should == false  # testing for directory
+                test(?f, @cache_file).should == false
+              end
+              
+            end #/ GET ['/css/no/cache.css' => /css/no/cache.css]
+            
+          end #/ CSS URLs with dynamic .sass files
+          
+        end #/ GET requests
+        
+        describe "POST, PUT, DELETE requests" do 
+          
+          describe "POST '/post'" do 
+            
+            before(:each) do 
+              @cache_file = "#{public_fixtures_path}/system/cache/post.html"
+              post('/post', :test => {:name => "test-#{Time.now.strftime("%Y-%d-%m %H:%M:%S")}", :content => "with content" })
+            end
+            
+            it "should render any output as normal" do 
+              body.should == 'POST'
+            end
+            
+            it "should NOT cache the output" do
+              test(?f, @cache_file).should == false
+            end
+            
+          end #/ POST '/post'
+          
+          describe "PUT '/put'" do 
+            
+            before(:each) do 
+              @cache_file = "#{public_fixtures_path}/system/cache/put.html"
+              put('/put', { :test => { :name => "test" }, :_method => "put" })
+            end
+            
+            it "should render any output as normal" do 
+              body.should == 'PUT'
+            end
+            
+            it "should NOT cache the output" do
+              test(?f, @cache_file).should == false
+            end
+            
+          end #/ PUT '/put'
+          
+          describe "DELETE '/delete'" do 
+            
+            before(:each) do 
+              @cache_file = "#{public_fixtures_path}/system/cache/delete.html"
+              delete('/delete') #, { :test => { :name => "test" }, :_method => "put" })
+            end
+            
+            it "should render any output as normal" do 
+              body.should == 'DELETE'
+            end
+            
+            it "should NOT cache the output" do
+              test(?f, @cache_file).should == false
+            end
+            
+          end #/ DELETE '/delete'
+          
+        end #/ POST, PUT, DELETE requests
+        
+      end #/ basic Page caching
+      
+      describe "and Fragment caching" do 
+        
+        describe "using NOT shared fragments" do 
+          
+          after(:all) do
+            FileUtils.rm_r("#{public_fixtures_path}/system/cache_fragments/fragments") if @delete_cached_test_files
+          end
+          
+          %w(
+            /fragments /fragments/a/b/ /fragments/with/param/?page=1 
+            /fragments/dasherised-urls/works-as-well
+          ).each do |url|
+            
+            params_free_url = url =~ /\?/ ? url.split('?').first.chomp('?') : url
+            dir_structure = params_free_url.gsub(/^\//,'').gsub(/\/$/,'')
+            
+            it "should cache the fragments from the URL [#{url}] as [#{dir_structure}/test_fragment.html]" do
+              get(url)
+              # body.should have_tag(:debug)
+              body.should have_tag('h1','FRAGMENTS', :count => 1)
+              body.should_not match(/<!-- cache fragment:(.+)test_fragment -->/)
+              body.should_not match(/<!-- \/cache fragment: test_fragment cached at \[ \d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\] -->/)
+              
+              # render the page a 2nd time from cache
+              get(url)
+              body.should have_tag('h1','FRAGMENTS', :count => 1)
+              body.should match(/<!-- cache fragment:(.+)test_fragment -->/)
+              body.should match(/<!-- \/cache fragment: test_fragment cached at \[ \d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\] -->/)
+              
+              # the cached fragment has already been found if we get this far, 
+              # but just for good measure do we check for the existence of the fragment file.
+              test(?f, "#{public_fixtures_path}/system/cache_fragments/#{dir_structure}/test_fragment.html").should == true
+            end
+          end
+          
+        end #/ using NOT shared fragments
+        
+        describe "using shared fragments" do 
+          
+          after(:all) do
+            FileUtils.rm_r("#{public_fixtures_path}/system/cache_fragments/sharedfragments") if @delete_cached_test_files
+          end
+          
+          describe "when requesting the first URL" do 
+            
+            #  FIXME:: work out some clever way to split all of these tests into single items instead of in one big blob
+             
+            it "should cache the fragment based on the URL and use it on subsequent requests by URLs sharing the same root URL" do
+              url = '/sharedfragments/2010/02/some-article-01'
+              params_free_url = url =~ /\?/ ? url.split('?').first.chomp('?') : url
+              dir_structure = params_free_url.gsub(/^\//,'').gsub(/\/$/,'')
+              dirs = dir_structure.split('/')
+              dir_structure = dirs.first(dirs.length-1).join('/')
+              
+              get(url)
+              # body.should have_tag(:debug)
+              body.should have_tag('h1','FRAGMENTS - SHARED', :count => 1)
+              body.should_not match(/<!-- cache fragment:(.+)test_fragment -->/)
+              body.should_not match(/<!-- \/cache fragment: test_fragment cached at \[ \d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\] -->/)
+              
+              get(url)
+              body.should have_tag('h1','FRAGMENTS - SHARED', :count => 1)
+              body.should match(/<!-- cache fragment:(.+)test_fragment -->/)
+              body.should match(/<!-- \/cache fragment: test_fragment cached at \[ \d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\] -->/)
+              
+              # the cached fragment has already been found if we get this far, 
+              # but just for good measure do we check for the existence of the fragment file.
+              test(?f, "#{public_fixtures_path}/system/cache_fragments/#{dir_structure}/test_fragment.html").should == true
+              
+              # should use the cached fragment rather than cache a new fragment
+              url = '/sharedfragments/2010/02/another-article-02'
+              get(url)
+              body.should have_tag('h1','FRAGMENTS - SHARED', :count => 1)
+              body.should match(/<!-- cache fragment:(.+)test_fragment -->/)
+              body.should match(/<!-- \/cache fragment: test_fragment cached at \[ \d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\] -->/)
+            end
+            
+          end #/ when requesting the first URL
+          
+        end #/ using shared fragments
+        
+      end #/ and Fragment caching
+      
+      describe "basic Cache Expiring" do 
+        
+        describe "Pages" do 
+          
+          it "should expire the page ['/params/cache/expire/' => ../cache/params/cache/expire/index.html]" do 
+            get('/params/cache/expire/')
+            test(?f,"#{public_fixtures_path}/system/cache/params/cache/expire/index.html" ).should == true
+            lambda { 
+              erb_app "<% cache_expire('/params/cache/expire/') %>"
+            }.should_not raise_error(Exception)
+            
+            test(?f,"#{public_fixtures_path}/system/cache/params/cache/expire/index.html" ).should == false
+            
+          end
+          
+          it "should expire the page ['/params/cache/expired' => ../cache/params/cache/expired.html]" do 
+            get('/params/cache/expired')
+            test(?f,"#{public_fixtures_path}/system/cache/params/cache/expired.html" ).should == true
+            lambda { 
+              erb_app "<% cache_expire('/params/cache/expired') %>"
+            }.should_not raise_error(Exception)
+            
+            test(?f,"#{public_fixtures_path}/system/cache/params/cache/expired.html" ).should == false
+            
+          end
+          
+        end #/ Pages
+        
+        describe "Fragments" do 
+          
+          it "should expire the fragment ['/fragments/cache/expire/' => ../cache_fragments/fragments/cache/expire/test_fragment.html]" do 
+            get('/fragments/cache/expire/')
+            test(?f,"#{public_fixtures_path}/system/cache_fragments/fragments/cache/expire/test_fragment.html" ).should == true
+            lambda { 
+              erb_app "<% cache_expire('/fragments/cache/expire/',:fragment => :test_fragment) %>"
+            }.should_not raise_error(Exception)
+            test(?f,"#{public_fixtures_path}/system/cache/params/cache_fragments/expire/test_fragment.html" ).should == false
+          end
+          
+          it "should expire the fragment ['/fragments/cache/expired' => ../cache_fragments/fragments/cache/expired/test_fragment.html]" do 
+            get('/fragments/cache/expired')
+            test(?f,"#{public_fixtures_path}/system/cache_fragments/fragments/cache/expired/test_fragment.html" ).should == true
+            lambda { 
+              erb_app "<% cache_expire('/fragments/cache/expired',:fragment => :test_fragment) %>"
+            }.should_not raise_error(Exception)
+            test(?f,"#{public_fixtures_path}/system/cache/params/cache_fragments/expired/test_fragment.html" ).should == false
+          end
+          
+        end #/ Pages
+        
+      end #/ basic Cache Expiring
+      
+      
+    end #/ with caching enabled
+    
+  end #/ Cache
+  
+end #/ Sinatra