stella 0.7.0.006 → 0.7.0.012

data/CHANGES.txt

@@ -8,6 +8,7 @@ NOTE: Complete rewrite
 * New internal architecture. 
 * Improved stability and output for high thread loads. 
 * Updated test plan DSL
+* Granular reporting via Benelux
 
 
 #### 0.6.0 (2009-03-15) ###############################

data/bin/stella

@@ -59,7 +59,7 @@ class Stella::CLI::Definition
   about "Run a functional test"
   usage "stella verify http://stellaaahhhh.com/"
   usage "stella verify -p path/2/testplan.rb http://stellaaahhhh.com/"
-  option :b, :benchmark, "Benchmark mode (ignore wait times)"
+  option :w, :nowait, "Ignore wait times"
   option :p, :testplan, String, "Path to testplan" 
   command :verify => Stella::CLI
   
@@ -68,7 +68,7 @@ class Stella::CLI::Definition
   usage "stella load http://stellaaahhhh.com:3114/"
   usage "stella load --clients=10 --repetitions=2 http://stellaaahhhh.com/"
   usage "stella load -p path/2/testplan.rb -u 100 -r 5 http://stellaaahhhh.com/"
-  option :b, :benchmark, "Benchmark mode (ignore wait times)"
+  option :w, :nowait, "Ignore wait times"
   option :c, :clients, Integer, "Number of virtual clients"
   option :r, :repetitions, Integer, "Number of times to repeat the testplan (per vclient)"
   option :t, :time, String, "Max duration to run test"

data/examples/cookies/plan.rb

@@ -0,0 +1,18 @@
+desc "Maintain Your Cookies"
+
+usecase 65, "Simple search" do
+  
+  get "/", "Homepage"
+  
+  get "/search", "Search Results" do
+    param :what  => random(['Big', 'Beads'])
+    param :where => 'Toronto'
+  end
+  
+  get "/", "Homepage" do
+    response 200 do
+      puts doc.css('ul#history').first
+    end
+  end
+  
+end

data/examples/essentials/plan.rb

@@ -1,26 +1,165 @@
-# 4f61ac3d5607139350b50335ca59a34d04b34ec7
+# Stella - Example Test Plan
+# 
+#
+# 1. INTRODUCTION
+#
+# A test plan is a group of one or more user 
+# scenarios. This allows you to simulate the
+# kind of traffic your application is exposed
+# to in the wild. Realistic tests are really
+# important because they give you a much more
+# accurate view of how your application is
+# performing. 
+#
+# A scenario (or "usecase") is a group a 
+# requests that represents a typical path
+# that a real person would take through 
+# your site. 
+#
+# This plan contains 3 scenarios:
+# 
+# - Simple Search (60%)
+# - YAML API (30%)
+# - Self-serve API (10%)
+#
+# The percentages represent the relative amount 
+# of traffic to be generated for each scenario.
+# In a test with 100 virtual users, 60 would 
+# follow the Simple Search usecase, 30 the YAML
+# API, and 10 would following the Self-Serve API.
+#
+#
+# 2. THE CONFIGURATION LANGUAGE
+# 
+# Test plans are defined in a streamlined version
+# of the Ruby programming language. Using a "real"
+# languages gives you a lot of power to specify 
+# complex operations. 
+#
+#
+# 3. START THE EXAMPLE APPLICATION
+# 
+# You need to start the example web application before
+# running this testplan. You can do this in one of the
+# following ways:
+# 
+# $ ruby examples/example_webapp.rb
+#
+#     OR
+#
+# $ thin -R examples/example_webapp.ru start
+#
+# You can check that it's running by going to:
+# http://127.0.0.1:3000/
+#
+#
+# 4. RUNNING THE TEST PLAN
+#
+# You run this test plan from the command line.
+# First you verify that the plan and application
+# are running correctly:
+#
+# $ stella verify -p examples/essentials/plan.rb http://127.0.0.1:3114/
+# 
+# The "verify" command executes the plan with a 
+# single user and provides more detailed output.
+#
+# "load" tests are run in a similar way:
+# 
+# $ stella load -c 50 -r 10 -p examples/essentials/plan.rb http://127.0.0.1:3114/
+#
+# where "c" is the number of concurrent users and
+# "r" is the number of times to repeat the plan. 
+#
+# 
+# 5. WRITING A TEST PLAN
+#
+# The following is an example of a working test plan. 
+# I put a lot of effort into keeping the syntax simple
+# but feel free to contact me if you have any questions
+# or problems.
+#
+# Happy Testing!
+#
+# Delano (@solutious.com) 
+#
 
 desc "Business Finder Testplan"
 
 usecase 65, "Simple search" do
+  
+  # An important factor in simulating traffic
+  # is using real, dynamic data. You can load
+  # data from a file using the resource method.
+  # Here is an example which reads a list of 
+  # search terms ("restaurant", "hotel", ...)
+  # into an array called :search_terms. The 
+  # colon is Ruby's way of defining a symbol.
+  #
   resource :search_terms, list('search_terms.csv')
   
+  # Requests are defined with one of the 
+  # following methods: get, post, head, delete.
+  # Here we define a simple get request for the
+  # homepage ("/").
+  #
   get "/", "Homepage" do
+    # This tells Stella to wait between 1 and 5
+    # seconds before moving to the next request.
     wait 1..5
-    response 200 do
-      status                       # => 200
-      headers['Content-Type']      # => ['text/html']
-      body                         # => <html>...
-      doc                          # => Nokigiri::HTML::Document
-    end
   end
   
+  # In this request, the user has entered a simple
+  # what and where search. You'll notice that we
+  # aren't specifying a hostname or port number for
+  # these requests. We do that so you use the same
+  # test plan to run tests on machines with different
+  # hostnames. However, this is optional. You can
+  # also specify absolute URIs like this:
+  #
+  #     get "http://example.com:8000/search"
+  #
   get "/search", "Search Results" do
     wait 2..5
+    
+    # Two URI parameters will be included with this
+    # request. Notice that the values for the what 
+    # and where parameters come from the resources
+    # we defined. We've specified for random values
+    # to be used, but we could also specify sequential
+    # or reverse sequential values (see XML API).
+    #
     param :what  => random(:search_terms)
-    param :where => random(['Toronto', 'Montreal'])
+    param :where => random(['Toronto', 'Vancouver', 'Montreal'])
+    
+    # Each request can also include one or more 
+    # optional response blocks. These blocks determine
+    # what should happen when the specified HTTP
+    # status code is returned by the web server. 
+    # 
+    # For successful responses, we want to parse out
+    # some data from the page. For 404 (Not Found)
+    # responses, we simply want the virtual user to
+    # quit the usecase altogether. 
+    #
     response 200 do
+      
+      # If the response contains HTML, it will
+      # automatically be parsed using the Ruby
+      # library Nokogiri. See the following link
+      # for more information:
+      # http://nokogiri.rubyforge.org/nokogiri/
+      #
+      # The important thing to note is that you 
+      # don't need to write complex regular 
+      # expressions to grab data from the page. 
+      # 
       listing = doc.css('div.listing').first
+      
+      # Here we grab the first listing ID on the
+      # page and store it in a variable called
+      # :lid. This is similar to a resource. 
+      #
       set :lid, listing['id'].match(/(\d+)/)[0]
     end
     response 404 do 
@@ -28,37 +167,66 @@ usecase 65, "Simple search" do
     end
   end
   
-  get "/listing/:lid" do           # URIs can contain variables.
-    desc "Selected listing"        # This one will be replaced by
-    wait 1..8                      # the one stored in the previous
-  end                              # request.
+  # Notice the special variable in this URI path. 
+  # Since we have defined a variable with the same
+  # name in the previous request, the variable in 
+  # the request will automatically be replaced with 
+  # that value. This value is unique for each virtual
+  # user.
+  #
+  get "/listing/:lid" do 
+    desc "Selected listing"
+    wait 1..8       
+  end               
   
 end
 
-xusecase 10, "Self-serve" do
-  post "/listing/add", "Add a listing" do
-    wait 1..4 
-    param :name => random(8)
-    param :city => sequential("Montreal", "Toronto", "Vancouver")
-    param :logo => file('logo.png')
-    response 302 do
-      repeat 3
-    end
-  end
-end
-
-usecase "Listing API" do
+usecase 25, "YAML API" do
   
   get '/listings.yaml', "View All" do
     response 200 do
-      # doc contains the parsed YAML object
+    
+      # We showed above how HTML is parsed automatically.
+      # Stella can do the same with XML, YAML, and JSON. 
+      #
+      # A variable called "doc" contains the parsed YAML.
+      # "collect" is a Ruby method that iterates through 
+      # all items in an Array and returns a new Array 
+      # containing the return values from each iteration. 
+      # Each item item is available in the variable 
+      # called 'l'. 
+      #
+      # The variable called "listings" will contain all
+      # listing ids in the YAML document.
+      #
       listings = doc.collect! { |l|; l[:id]; }
-      set :current_listing_ids, listings
+      
+      # And here we store that list of ids. 
+      #
+      set :listing_ids, listings
     end
   end
   
-  get "/listing/:lid.yaml", "Select (sequential)" do
-    param :lid => rsequential(:current_listing_ids)
+  # In the Simple Search usecase we stored a listing
+  # id in a variable called :lid. This time we have
+  # an Array of listing ids but we only want to use
+  # one for each request so we override the automatic
+  # variable replacement by using the param method. 
+  #
+  get "/listing/:lid.yaml", "Select Listing" do
+    
+    # Each request will use a new value from the 
+    # Array and these will be selected sequentially. 
+    # Note that this is _per virtual user_. Each 
+    # vuser will have its own copy of the Array and
+    # iterate through it independently.
+    #
+    param :lid => rsequential(:listing_ids)
+    
+    # We can use response blocks to affect behaviour 
+    # the user. Here we specify that every virtual
+    # user should repeat this request 7 times.
+    #
     response 200 do
       repeat 7
     end
@@ -66,3 +234,22 @@ usecase "Listing API" do
   
 end
 
+usecase 10, "Self-serve API" do
+  
+  # Here is an example of using a POST request. 
+  # Notice that the definition is otherwise 
+  # identical to the ones you've seen above.
+  #
+  post "/listing/add", "Add a listing" do
+    wait 1..4 
+    param :name => random(8)
+    param :city => random(['Toronto', 'Vancouver', 'Montreal'])
+    param :logo => file('logo.png')
+    response 302 do
+      repeat 3
+    end
+  end
+  
+end
+
+# a5689bb64829d2dc1e9ab8901223cc90c975fe3a

data/examples/example_webapp.rb

@@ -73,7 +73,11 @@ post '/listing/add' do
   else
     @listings = options.listings
     if find_name(params[:name], @listings).empty?
-      @listings.shift if @listings.size >= options.max_listings
+      # Limit the number of in memory listings, but we want to keep 
+      # the original listings so we use a slice instead of a shift.
+      if @listings.size >= options.max_listings
+        @listings.slice!(LISTINGS.size) 
+      end
       @listings << { :name => params[:name], :id => rand(100000), :city => params[:city] }
       if params[:logo].is_a?(Hash) && params[:logo][:tempfile]
         p "TODO: Fix uploads"
@@ -130,7 +134,8 @@ before do
   @cookie[:history].unshift params[:what] unless blank?(params[:what])
   @cookie[:history].pop if @cookie[:history].size > 5
   @cookie[:location] = params[:where] unless blank?(params[:where])
-  response.set_cookie "bff-history", :path => '/', :value => @cookie.to_yaml
+  response.set_cookie "bff-history", 
+    :value => @cookie.to_yaml#, :expires => Time.parse('16/02/2012')
 end
 
 helpers do
@@ -177,11 +182,16 @@ __END__
 @@layout
 <html>
 <head>
+<!-- 
+Param: __stella: <%= params['__stella'] %>
+Header: X-Stella-ID: <%= env['HTTP_X_STELLA_ID'] %> 
+-->
 <title><%= @title %></title>
 <style>
 .hilite { background-color: #FEE00B; font-weight: bold; }
 .footer { color: #ccc; font-weight: lighter; font-size: 80%; margin-top: 30px; }
-.footer a { color: #69c;}
+.footer a { color: #69c; }
+body { background: url('http://solutious.com/images/solutious-logo-large.png?1') no-repeat right;}
 </style>
 </head>
 <body>
@@ -194,7 +204,7 @@ __END__
 </em></p>
 <%= yield %>
 <div class="footer">
-A <a href="http://solutious.com/projects/stella/">Stella</a> demo by <a href="http://solutious.com/">Solutious</a>. 
+A <a href="http://solutious.com/">Solutious Inc</a> production.  
 </div>
 </body>
 </html>

data/examples/example_webapp.ru

@@ -1,3 +1,9 @@
+# Stella Demo Rackup
+#
+# Usage:
+# 
+#     $ thin -R examples/example_webapp.ru -p 3114 start
+
 dir = ::File.expand_path(::File.dirname(__FILE__))
 require ::File.join(dir, 'example_webapp.rb')
 run Sinatra::Application

data/examples/exceptions/plan.rb

@@ -3,16 +3,10 @@
 usecase "Exception Handling" do
   
   get "/search", "Search Results" do
-    wait 2..5
-    param :what  => random()
+    param :what  => 'No Such Listing'
     param :where => random('Toronto', 'Montreal', 'Vancouver')
-    response 200 do
-      listing = doc.css('div.listing').first
-      set :lid, listing['id'].match(/(\d+)/)[0]
-      raise NoListingResultFound if listing.nil?
-    end
     response 404 do
-      raise NoSearchResults 
+      raise NoSearchResults
     end
   end
   

data/lib/stella/cli.rb

@@ -15,7 +15,7 @@ class Stella::CLI < Drydock::Command
   def verify
     opts = {}
     opts[:hosts] = @hosts
-    opts[:benchmark] = true if @option.benchmark
+    opts[:nowait] = true if @option.nowait
     ret = Stella::Engine::Functional.run @testplan, opts
     @exit_code = (ret ? 0 : 1)
   end
@@ -27,7 +27,7 @@ class Stella::CLI < Drydock::Command
   def load
     opts = {}
     opts[:hosts] = @hosts
-    [:benchmark, :clients, :repetitions, :delay, :time].each do |opt|
+    [:nowait, :clients, :repetitions, :delay, :time].each do |opt|
       opts[opt] = @option.send(opt) unless @option.send(opt).nil?
     end
     ret = Stella::Engine::Load.run @testplan, opts
@@ -39,7 +39,10 @@ class Stella::CLI < Drydock::Command
     unless @option.testplan.nil? || File.exists?(@option.testplan)
       raise Stella::InvalidOption, "Bad path: #{@option.testplan}" 
     end
-    @hosts = @argv.collect { |uri|; URI.parse uri; }
+    @hosts = @argv.collect { |uri|; 
+      uri = 'http://' << uri unless uri.match /^http:\/\//i
+      URI.parse uri; 
+    }
     if @option.testplan
       @testplan = Stella::Testplan.load_file @option.testplan
     else

data/lib/stella/client/container.rb

@@ -0,0 +1,49 @@
+
+
+class Stella::Client
+  
+  class Container
+    
+    attr_accessor :usecase
+    attr_accessor :response
+    attr_reader :resources
+    def initialize(usecase)
+      @usecase, @resources = usecase, {}
+      @base_path = usecase.base_path
+    end
+    
+    # This is used to handle custom exception in usecases.
+    # See examples/exceptions/plan.rb
+    #
+    def self.const_missing(custom_error)
+      ResponseError.new custom_error
+    end
+    
+    def doc
+      # NOTE: It's important to parse the document on every 
+      # request because this container is available for the
+      # entire life of a usecase. 
+      case @response.header['Content-Type']
+      when ['text/html']
+        Nokogiri::HTML(body)
+      when ['text/yaml']
+        YAML.load(body)
+      end
+    end
+
+    def resource(n)
+      return @usecase.resource(n) if @usecase.resources.has_key? n
+      return @resources[n] if @resources.has_key? n
+    end
+
+    def body; @response.body.content; end
+    def headers; @response.header; end
+      alias_method :header, :headers
+    def status; @response.status; end
+    def set(n, v); @resources[n] = v; end
+    def wait(t); sleep t; end
+    def quit(msg=nil); Quit.new(msg); end
+    def repeat(t=1); Repeat.new(t); end
+  end
+  
+end

data/lib/stella/client/modifiers.rb

@@ -0,0 +1,19 @@
+
+
+class Stella::Client
+  
+  class ResponseModifier; end
+  class Repeat < ResponseModifier; 
+    attr_accessor :times
+    def initialize(times)
+      @times = times
+    end
+  end
+  class Quit < ResponseModifier; 
+    attr_accessor :message
+    def initialize(msg=nil)
+      @message = msg
+    end
+  end
+  
+end