resat 0.7.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 RightScale, Inc.
+
+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.

data/README.rdoc

@@ -0,0 +1,321 @@
+= Resat
+
+= DESCRIPTION
+
+== Synopsis
+
+Resat is a script engine which allows grouping web requests into <b>scenarios</b>.
+
+A scenario consists of serie of HTTP requests called <b>steps</b>.
+
+Each step may be associated with <b>guards</b> and/or <b>filters</b> and/or <b>handlers</b>.
+
+The syntax used to defined scenarios is simple and can be used by programmers and
+non-programmers alike. See the WRITING SCENARIOS section below for examples.
+
+* Guards keep making the same request until the response header and/or body
+  satisfy(ies) certain conditions.
+
+* Filters validate the response and may save some of its elements in variables.
+  Variables can be used to define requests, guards and filters.
+
+* Handlers allow writing custom code to handle a request and its response.
+
+Scenarios are defined as YAML documents that must adhere to the Kwalify
+schemas defined in <tt>schemas/scenarios.yaml</tt>. See the comments in this
+file for additional information.
+
+Resat is configured through a YAML configuration file which defines
+default values that applies to all requests including the host name,
+base url, whether to use SSL, common headers and body parameters and
+optionally a username and password to be used with basic authentication.
+This configuration file is located in <tt>config/resat.yaml</tt> by default.
+
+== Why resat?
+
+There are two main use cases for resat:
+
+1. Scripting: Resat can be used to chaing together a serie of REST API calls
+   that can be used to perform repetitive tasks.
+
+2. API testing: For REST API implementors, resat is the ideal automated
+   regression tool. This is the tool we use at RightScale to test our APIs.
+
+== How to use
+
+resat can be used as a ruby library or as an application. Using it as library
+involves instantiating the engine and calling the 'run' method:
+
+ require 'resat'
+
+ options             = OpenStruct.new
+ options.verbose     = false
+ options.quiet       = false
+ options.norecursion = false
+ options.loglevel    = 'info'
+ options.logfile     = 'resat.log'
+ options.configfile  = 'config/resat.yaml'
+ options.schemasdir  = 'schemas'
+
+ Resat::Log.init(options)
+ engine = Resat::Engine.new(options)
+ engine.run('my_scenario.yaml')
+
+ if engine.succeeded?
+   puts engine.summary.dark_blue
+ else
+   puts engine.summary.dark_red
+ end
+ puts "#{engine.requests_count} request(s)."
+ puts "#{engine.ignored_count} scenario(s) ignored."
+ puts "#{engine.skipped_count} YAML file(s) skipped."
+
+See the examples and usage sections below for using resat as an application.
+
+== Examples
+
+Run the scenario defined in scenario.yaml:
+
+ $ resat scenario.yaml
+
+Execute scenarios defined in the 'scenarios' directory and its
+sub-directories:
+
+ $ resat scenarios
+
+Only execute the scenarios defined in the current directory, do not execute
+scenarios found in sub-directories:
+
+ $ resat -n .
+
+== Usage
+
+ resat [options] target
+
+ For help use: resat -h
+
+== Options
+
+ -h, --help Display help message
+ -v, --version Display version, then exit
+ -q, --quiet Output as little as possible, override verbose
+ -V, --verbose Verbose output
+ -n, --norecursion Don't run scenarios defined in sub-directories
+ -d, --define NAME:VAL Define global variable (can appear multiple times,
+                       escape ':' with '::')
+ -f, --failonerror Stop resat from continuing to run if an error occurs
+ -c, --config PATH Config file path (config/resat.yaml by default)
+ -s, --schemasdir DIR Path to schemas directory (schemas/ by default)
+ -l, --loglevel LVL Log level: debug, info, warn, error (info by default)
+ -F, --logfile PATH Log file path (resat.log by default)
+
+= INSTALLATION
+
+* <b>From source</b>: run the following command from the root folder to be able to run resat from anywhere:
+
+ $ sudo ln -s `pwd`/bin/resat /usr/local/bin/resat
+
+* <b>Using the gem</b>: 
+
+ $ sudo gem install resat
+
+= DEVELOPMENT
+
+== Source
+
+The source code of Resat is available via Git: http://github.com/raphael/resat.git
+Fork the project and send pull requests to contribute!
+
+== Dependencies
+
+resat relies on Kwalify for validating YAML files:
+
+ $ sudo gem install kwalify
+
+* http://www.kuwata-lab.com/kwalify/
+
+= WRITING SCENARIOS
+
+At the heart of your resat scripts are the scenarios. A scenario consists of
+one or more steps. A scenario may include other scenarios. A single execution
+of Resat can apply to multiple scenarios (all scenarios in a given folder).
+
+A simple scenario containing a single step is defined below:
+
+ name: List all servers
+ steps:
+   - request:
+       operation: index
+       resource:  servers
+
+The first element of the scenario is its name. The name is used by the command
+line tool for update and error outputs.
+
+The second element is the list of steps. A step must contain a request. A
+request corresponds to one of the REST CRUD operations and applies to a
+resource. CRUD operations are <i>create</i>, <i>show</i>, <i>index</i>, <i>update</i>,
+and <i>destroy</i>.
+
+Operations that apply to a single resource rather than to all resources require
+the <i>id</i> element:
+
+ name: Show server 42
+ steps:
+   - request:
+       operation: show
+       resource:  servers
+       id:        42
+
+Resat also allows defining <i>custom</i> requests for making web requests that
+don't map to a CRUD operation. A custom request is defined by a <i>type</i>
+corresponding to the HTTP verb that the request should use (i.e. <tt>get</tt>, <tt>post</tt>,
+<tt>put</tt> or <tt>delete</tt>) and its name.
+
+ name: Twitter Timelines
+ steps:
+   - request:
+       resource:  statuses
+       custom:                         # Use a custom operation
+         name:    public_timeline.xml  # Operation name
+         type:    get                  # GET request
+
+Requests can then be followed by filters which can validate the response and/or
+extract elements from it.
+
+ name: Get Mephisto ServerTemplate
+ steps:
+   - request:
+       operation:      index
+       resource:       server_templates
+     filters:
+       - name:         get server template href
+         target:       body
+         validators:
+           - field:    server-templates/ec2-server-template[nickname='Mephisto all-in-one v8']/href
+             is_empty: false
+         extractors:
+           - field:    server-templates/ec2-server-template[nickname='Mephisto all-in-one v8']/href
+             variable: server_template_href
+
+Variables that are extracted from a request response can then be used for
+other requests, filters or guards. A variable is used using the <tt>$</tt> sign
+followed by the variable name. A variable may be written to an output file if
+it has the <i>save</i> element and the configuration file defines an output
+file. A variable can also be exported to other scenarios that will get run in
+the same Resat execution (so a scenario can create resources and save their ids
+and a following scenario can reuse the ids to delete or update the resources).
+
+The element to extract can be a response header or a response body field. If it
+is a response body field then an XPATH query is used to identity which part of
+the response body should be extracted.
+
+The value to be extracted can be further defined using a regular expression
+with a capture block. The regular expression is applied to the field matching
+the XPATH associated with the extractor.
+
+<b>Note</b>: Because XPATH is used to define fields in extractors and
+validators, only requests that return XML can be followed by filters.
+
+ name: Create Mephisto Server
+ steps:
+   - request:
+       operation:      create
+       resource:       servers
+       valid_codes:
+         - 201
+       params:
+         - name:       server[nickname]
+           value:      'resat created server'
+         - name:       server[server_template_href]
+           value:      $server_template_href
+         - name:       server[deployment_href]
+           value:      $deployment_href
+     filters:
+       - name:         validate server response
+         target:       body
+         is_empty:     true
+       - name:         extract server id
+         target:       header
+         extractors:
+           - field:    location
+             pattern:  '.*\/(\d+)$'
+             variable: server_id
+
+A scenario request can also use <i>guards</i>. A guard identifies a response
+element similarly to an extractor (response header or body field identified by
+an XPATH and optionally a regular expression). A guard specifies a value that
+the element must match together with a period and a timeout that should be used
+to retry the request until the value matches the guard or the timeout is
+reached.
+
+ name: Wait until server 42 is operational
+ steps:
+   - request:
+       resource:  servers
+       id:        42
+       operation: show
+     guards:
+       - target:  body
+         field:   server/state
+         pattern: 'operational'
+         period:  10
+         timeout: 300
+         name:    server operational
+
+Finally a scenario request can include <i>handlers</i>. Handlers can only be
+included when resat is used as a library. The handler definition lists a unique
+name followed the corresponding ruby module name.
+
+ name: Store servers definitions
+ steps:
+   - request:
+       resource:  servers
+       operation: index
+     handlers:
+       - name:    save results
+         module:  ServersPersister
+
+The ruby module must define a <tt>process</tt> method which accepts two arguments:
+
+  def process(request, response)
+
+* <i>request</i>: an instance of Net::HTTPRequest corresponding to the request associated with this handler.
+* <i>response</i>: an instance of Net::HTTPResponse which contains the associated response.
+
+It should also define a <tt>failures</tt> method which can return a list of errors. 
+The errors will get logged and optionally stop the execution of resat if the 
+<tt>failonerror</tt> option is set to <tt>true</tt>.
+
+= ADDITIONAL RESOURCES
+
+* Refer to the examples (http://github.com/raphael/resat/tree/master/examples)
+  for fully functional and documented scenarios.
+* See the file <tt>schemas/scenarios.yaml</tt>
+  (http://github.com/raphael/resat/blob/master/schemas/scenarios.yaml) for
+  the complete reference on scenarios syntax.
+
+= LICENSE
+
+Resat - Web scripting for the masses
+
+Author:: Raphael Simon (<raphael@rightscale.com>)
+Copyright:: Copyright (c) 2009 RightScale, Inc. 
+
+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.

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+GEM      = 'resat'
+GEM_VER  = '0.7.0'
+AUTHOR   = 'Raphael Simon'
+EMAIL    = 'raphael@rightscale.com'
+HOMEPAGE = 'http://github.com/raphael/resat'
+SUMMARY  = 'Web scripting for the masses'
+
+spec = Gem::Specification.new do |s| 
+  s.name             = GEM
+  s.version          = GEM_VER
+  s.author           = AUTHOR
+  s.email            = EMAIL
+  s.platform         = Gem::Platform::RUBY
+  s.summary          = SUMMARY
+  s.description      = SUMMARY
+  s.homepage         = HOMEPAGE
+  s.files            = %w(LICENSE README.rdoc Rakefile) + FileList["{bin,lib,schemas,examples}/**/*"].to_a
+  s.executables      = ['resat']
+  s.extra_rdoc_files = ["README.rdoc", "LICENSE"]
+  s.add_dependency("kwalify", ">= 0.7.1")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VER}}
+end
+

data/bin/resat

@@ -0,0 +1,223 @@
+#!/usr/bin/env ruby
+
+# === Synopsis 
+#   resat - RightScale API Tester
+#   
+#   This application allows making automated REST requests optionally followed 
+#   by validation. It reads scenarios defined in YAML files and executes the
+#   corresponding steps. A step consist of a REST request followed by any 
+#   number of filters.
+#
+#   Scenarios are defined as YAML documents that must adhere to the Kwalify
+#   schemas defined in schemas/scenarios.yaml. See the comments in this
+#   file for additional information.
+#
+#   resat is configured through a YAML configuration file which defines
+#   information that applies to all requests including the host name,
+#   base url, whether to use SSL, common headers and body parameters and
+#   optionally a username and password to be used with basic authentication.
+#   This configuration file should be located in config/resat.yaml by default.
+#
+# === Examples
+#   Run the scenario defined in scenario.yaml:
+#     resat scenario.yaml
+#
+#   Execute scenarios defined in the 'scenarios' directory and its
+#   sub-directories:
+#     resat scenarios
+#
+#   Only execute the scenarios defined in the current directory, do not execute
+#   scenarios found in sub-directories:
+#     resat -n .
+#
+# === Usage 
+#   resat [options] target
+#
+#   For help use: resat -h
+#
+# === Options
+#   -h, --help            Display help message
+#   -v, --version         Display version, then exit
+#   -q, --quiet           Output as little as possible, override verbose
+#   -V, --verbose         Verbose output
+#   -n, --norecursion     Don't run scenarios defined in sub-directories
+#   -d, --define NAME:VAL Define global variable (can appear multiple times,
+#                         escape ':' with '::')
+#   -f, --failonerror     Stop resat from continuing to run if an error occurs
+#   -c, --config PATH     Config file path (config/resat.yaml by default)
+#   -s, --schemasdir DIR  Path to schemas directory (schemas/ by default)
+#   -l, --loglevel LVL    Log level: debug, info, warn, error (info by default)
+#   -F, --logfile PATH    Log file path (resat.log by default)
+#   -D, --dry-run         Print requests, don't actually make them
+#
+
+require 'rubygems'
+require 'optparse' 
+require 'ostruct'
+require 'date'
+require 'benchmark'
+THIS_FILE = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
+require File.expand_path(File.join(File.dirname(THIS_FILE), '..', 'lib', 'rdoc_patch'))
+require File.expand_path(File.join(File.dirname(THIS_FILE), '..', 'lib', 'engine'))
+
+module Resat
+  class App
+    VERSION = '0.7.0'
+
+    def initialize(arguments)
+      @arguments = arguments
+
+      # Set defaults
+      @options = OpenStruct.new
+      @options.verbose = false
+      @options.quiet = false
+      @options.norecursion = false
+      @options.failonerror = false
+      @options.variables = {}
+      @options.config = nil
+      @options.schemasdir =  File.join(File.dirname(THIS_FILE), 'schemas')
+      @options.loglevel = "info"
+      @options.logfile = "/tmp/resat.log"
+      @options.dry_run = false
+    end
+
+    # Parse options, check arguments, then run tests
+    def run
+      if parsed_options? && arguments_valid?
+        begin
+          tms = Benchmark.measure { run_tests }
+          Log.info tms.format("\t\tUser\t\tSystem\t\tReal\nDuration:\t%u\t%y\t%r")
+        rescue Exception => e
+          puts "Error: #{e.message}"
+        end
+      else
+        output_usage
+        @return_value = 1
+      end
+      exit @return_value
+    end
+
+    protected
+
+    def parsed_options?
+      opts = OptionParser.new
+      opts.on('-h', '--help')           { output_help }
+      opts.on('-v', '--version')        { output_version; exit 0 }
+      opts.on('-q', '--quiet')          { @options.quiet = true }
+      opts.on('-V', '--verbose')        { @options.verbose = true }
+      opts.on('-n', '--norecursion')    { @options.norecursion = true }
+      opts.on('-f', '--failonerror')    { @options.failonerror = true }
+      opts.on('-d', '--define VAR:VAL') { |v| @options.variables.merge!(var_hash(v)) }
+      opts.on('-c', '--config PATH')    { |cfg| @options.config = cfg }
+      opts.on('-s', '--schemasdir DIR') { |dir| @options.schemasdir = dir }
+      opts.on('-l', '--loglevel LEVEL') { |level| @options.loglevel = level }
+      opts.on('-F', '--logfile LOG')    { |log| @options.logfile = log }
+      opts.on('-D', '--dry-run')        { @options.dry_run = true }
+
+      opts.parse!(@arguments) rescue return false
+
+      process_options
+      true
+    end
+
+    # Build variable hash from command line option
+    def var_hash(var)
+      parts = var.split('::')
+      key = value = ''
+      key_built = false
+      parts.each_index do |idx|
+        part = parts[idx]
+        if key_built
+          value = value + ':' + (part || '')
+        else
+          if part.include?(':')
+            subparts = part.split(':')
+            part = subparts[0]
+            value = subparts[1] || ''
+            key_built = true
+          end
+          key = key + ':' if idx > 0
+          key = key + (part || '')
+        end
+      end
+      { key => value }
+    end
+
+    # Post-parse processing of options
+    def process_options
+      @options.verbose = false if @options.quiet
+      @options.loglevel.downcase!
+      @options.target = ARGV[0] unless ARGV.empty? # We'll catch that later
+    end
+
+    # Check arguments
+    def arguments_valid?
+      valid = ARGV.size == 1
+      if valid
+        unless %w{ debug info warn error }.include? @options.loglevel
+          Log.error "Invalid log level '#{@options.loglevel}'"
+          valid = false
+        end
+        unless File.directory?(@options.schemasdir)
+          Log.error "Non-existent schemas directory '#{@options.schemasdir}'"
+          valid = false
+        end
+        unless File.exists?(ARGV[0])
+          Log.error "Non-existent target '#{ARGV[0]}'"
+          valid = false
+        end
+      end
+      valid
+    end
+
+    def output_help
+      output_version
+      RDoc::usage_from_file(__FILE__)
+      exit 0
+    end
+
+    def output_usage
+      RDoc::usage_from_file(__FILE__, 'usage')
+      exit 0
+    end
+
+    def output_version
+      puts "#{File.basename(__FILE__)} - RightScale Automated API Tester v#{VERSION}\n".blue
+    end
+
+    def run_tests
+      Log.init(@options)
+      opts = "-" * 80 +  "\nOptions:"
+      @options.marshal_dump.each do |name, val|
+        opts += "\n  #{name} = #{val.inspect}"
+      end
+      Log.info opts
+      engine = Engine.new(@options)
+      engine.run
+      if engine.succeeded?
+        puts engine.summary.dark_blue
+        @return_value = 0
+      else
+        puts engine.summary.dark_red
+        @return_value = 1
+      end
+      unless @options.quiet
+        msg = ""
+        msg << "#{engine.requests_count} API call#{'s' if engine.requests_count > 1}*"
+        if engine.ignored_count > 1
+          msg << "*#{engine.ignored_count} scenario#{'s' if engine.ignored_count > 1} ignored*"
+        end
+        if engine.skipped_count > 1
+          msg << "*#{engine.skipped_count} YAML file#{'s' if engine.skipped_count >1} skipped" 
+        end
+        msg.gsub!('**', ', ')
+        msg.delete!('*')
+        puts msg.dark_blue
+      end
+    end
+  end
+end
+
+# Create and run the app
+app = Resat::App.new(ARGV)
+app.run