rox-client-rspec 0.3.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTNlNmE4ZTM2MjhmZDg1M2VlMWI3NDM1NTE2NzhhYTgzYmZjYTNkNQ==
+  data.tar.gz: !binary |-
+    MjlmNTViYTI1OWMzOTQ1M2QyNzcwOTRiNThhNTM2ZGVhOTdjMTQ2Yg==
+SHA512:
+  metadata.gz: !binary |-
+    N2FjYWE5ZTI3NjRkODM0NGFmNDc5Mjk5OGM5Yjg0MzkyMzY2NTEzMmExYWFm
+    ZmY4ZDk4ZTRjMzBkZDg0YzQ0NjUyZjlkMmYzNWJjYTBkMDFmYzFmNmU3MzQ1
+    NzZmMWIwZGUxMWIwYTg4NWIyZDRmNDhmNTljZWRiMGE5N2RjMDc=
+  data.tar.gz: !binary |-
+    Y2U2OTQ0M2Y2YTE5ODBlYjI3NmM2MDUxMTA3M2RiZTM2M2VhMzhiOTcxZjVh
+    YjQ5YjFjN2EyYjA0MjliZWQ3M2ZlMzQ0YzcwYTZlZjE2OGU4ZDBhYzY1MWNm
+    NzJiY2IzZGM5NTEwZTU0NTQ1YWZlYjZiZmIwMTkxYzFiODRhMGU=

data/Gemfile

@@ -0,0 +1,21 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+gem 'rspec', '~> 2.14'
+gem 'oj', '~> 2.1'
+gem 'httparty', '~> 0.11.0'
+gem 'paint', '~> 0.8.6'
+gem 'rake', '~> 10.1'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'bundler'
+  gem 'jeweler'
+  gem 'geminabox'
+  gem 'rake-version'
+  gem 'simplecov'
+  gem 'fakefs', require: 'fakefs/safe'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2013 Lotaris SA
+
+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.md

@@ -0,0 +1,148 @@
+# RSpec ROX Client
+
+**RSpec client for [ROX Center](https://github.com/lotaris/rox-center).**
+
+[![Gem Version](https://badge.fury.io/rb/rox-client-rspec.png)](http://badge.fury.io/rb/rox-client-rspec)
+
+## Requirements
+
+* RSpec 2.14
+
+## Installation
+
+In your Gemfile:
+
+```rb
+gem 'rox-client-rspec', '~> 0.3.0'
+```
+
+Manually:
+
+    gem install rox-client-rspec
+
+## Usage
+
+If you haven't done it already, follow the [setup procedure](#setup) below.
+
+To track a test, you must assign it a ROX test key generated from your ROX Center server.
+
+**NOTE: currently, all the tests in your test suite must be assigned a test key for the client to work.**
+
+Test keys are assigned to test using RSpec metadata:
+
+```rb
+it "should work", rox: { key: 'abcdefghijkl' } do
+  expect(true).to be_true
+end
+
+it(nil, rox: { key: 'bcdefghijklm' }){ should validate_presence_of(:name) }
+```
+
+<a name="setup"></a>
+## Setup
+
+ROX clients use [YAML](http://yaml.org) files for configuration.
+To use the RSpec ROX Client, you need two configuration files and you must set up the client in your spec helper file.
+
+In your home folder, you must create the `~/.rox/config.yml` configuration file.
+
+```yml
+# List of ROX Center servers you can submit test results to.
+servers:
+  - name: rox.example.com                 # A custom name for your ROX Center server.
+                                          # You will use this in the client configuration file.
+                                          # We recommend using the domain name where you deployed it.
+
+    apiUrl: https://rox.example.com/api   # The URL of your ROX Center server's API.
+                                          # This is the domain where you deployed it with /api.
+
+    apiKeyId: 39fuc7x85lsoy9c0ek2d        # Your user credentials on this server.
+    apiKeySecret: mwpqvvmagzoegxnqptxdaxkxonjmvrlctwcrfmowibqcpnsdqd
+
+# If true, test results will be uploaded to ROX Center.
+# Set to false to temporarily disable publishing.
+# You can change this at runtime from the command line by setting the
+# ROX_PUBLISH environment variable to 0 (false) or 1 (true).
+publish: true
+```
+
+In the project directory where you run RSpec, you must add the `rox.yml` client configuration file:
+
+```yml
+# Configuration specific to your project.
+project:
+  name: My Project
+  version: 1.2.3
+  apiId: 154sic93pxs0   # The API key of your project in the ROX Center server.
+
+# Where the client should store its temporary files.
+# The client will work without it but it is required for some advanced features.
+workspace: tmp/rox
+
+# Client advanced features.
+payload:
+  
+  # Saves a copy of the test payload sent to the ROX Center server for debugging.
+  # The file will be saved in rspec/servers/<SERVER_NAME>/payload.json.
+  save: false
+
+  # If you track a large number of tests (more than a thousand), enabling this
+  # will reduce the size of the test payloads sent to ROX Center server by caching
+  # test information that doesn't change often such as the name.
+  cache: false
+
+  # Prints a copy of the test payload sent to the ROX Center server for debugging.
+  # Temporarily enable at runtime by setting the ROX_PRINT_PAYLOAD environment variable to 1.
+  print: false
+
+# The name of the ROX Center server to upload test results to.
+# This name must be one of the server names in the ~/.rox/config.yml file.
+# You can change this at runtime from the command line by setting the
+# ROX_SERVER environment variable.
+server: rox.example.com
+```
+
+Finally, you must enable the client in your spec helper file (usually `spec/spec_helper.rb`).
+
+```yml
+RoxClient::RSpec.configure do |config|
+
+  # Optional ROX Center category to add to all the tests sent with this client.
+  config.project.category = 'RSpec'
+end
+```
+
+The next time you run your test suite, the RSpec ROX Client will send the results to your ROX Center server.
+
+## Contributing
+
+* [Fork](https://help.github.com/articles/fork-a-repo)
+* Create a topic branch - `git checkout -b my_feature`
+* Push to your branch - `git push origin my_feature`
+* Create a [pull request](http://help.github.com/pull-requests/) from your branch
+
+Please add a changelog entry with your name for new features and bug fixes.
+
+## License
+
+The RSpec ROX Client is licensed under the [MIT License](http://opensource.org/licenses/MIT).
+
+    Copyright (c) 2012-2013 Lotaris SA
+
+    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/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/rox-client-rspec.rb

@@ -0,0 +1,14 @@
+# encoding: UTF-8
+require 'rspec'
+
+module RoxClient
+
+  module RSpec
+    VERSION = '0.3.0'
+
+    class Error < StandardError; end
+    class PayloadError < Error; end
+  end
+end
+
+Dir[File.join File.dirname(__FILE__), File.basename(__FILE__, '.*'), '*.rb'].each{ |lib| require lib }

data/lib/rox-client-rspec/cache.rb

@@ -0,0 +1,60 @@
+
+module RoxClient::RSpec
+
+  class Cache
+
+    class Error < RoxClient::RSpec::Error; end
+
+    def initialize options = {}
+      @tests = {}
+      @workspace, @server_name, @project_api_id = options[:workspace], options[:server_name], options[:project_api_id]
+    end
+
+    def save test_run
+      validate!
+
+      @tests = { @project_api_id => @tests[@project_api_id] || {} }
+      test_run.results.each{ |r| @tests[@project_api_id][r.key] = test_result_hash(r) }
+
+      FileUtils.mkdir_p File.dirname(cache_file)
+      File.open(cache_file, 'w'){ |f| f.write Oj.dump(@tests, mode: :strict) }
+
+      self
+    end
+
+    def load
+      validate!
+
+      @tests = if File.exists? cache_file
+        Oj.load(File.read(cache_file), mode: :strict) rescue {}
+      else
+        {}
+      end
+      self
+    end
+
+    def known? test_result
+      @tests[@project_api_id] && !!@tests[@project_api_id][test_result.key]
+    end
+
+    def stale? test_result
+      @tests[@project_api_id] && test_result_hash(test_result) != @tests[@project_api_id][test_result.key]
+    end
+
+    private
+
+    def validate!
+      required = { "workspace" => @workspace, "server name" => @server_name, "project API identifier" => @project_api_id }
+      missing = required.keys.select{ |k| !required[k] }
+      raise Error.new("Missing cache options: #{missing.join ', '}") if missing.any?
+    end
+
+    def test_result_hash r
+      Digest::SHA2.hexdigest "#{r.name} || #{r.category} || #{r.tags.collect(&:to_s).sort.join(' ')} || #{r.tickets.collect(&:to_s).sort.join(' ')}"
+    end
+
+    def cache_file
+      @cache_file ||= File.join(@workspace, 'rspec', 'servers', @server_name, 'cache.json')
+    end
+  end
+end

data/lib/rox-client-rspec/client.rb

@@ -0,0 +1,119 @@
+
+module RoxClient::RSpec
+
+  class Client
+
+    def initialize server, options = {}
+
+      @server = server
+      @publish, @local_mode, @workspace = options[:publish], options[:local_mode], options[:workspace]
+      @cache_payload, @print_payload, @save_payload = options[:cache_payload], options[:print_payload], options[:save_payload]
+      
+      cache_options = { workspace: @workspace }
+      cache_options.merge! server_name: @server.name, project_api_id: @server.project_api_id if @server
+      @cache = Cache.new cache_options
+
+      @uid = UID.new workspace: @workspace
+    end
+
+    def process test_run
+
+      puts
+      return fail "No server to publish results to" if !@server
+
+      test_run.uid = @uid.load_uid
+
+      payload_options = @server.payload_options
+
+      cache_enabled = @cache_payload && load_cache
+      payload_options[:cache] = @cache if cache_enabled
+
+      return false unless payload = build_payload(test_run, payload_options)
+
+      published = if !@publish
+        puts Paint["ROX - Publishing disabled", :yellow]
+        false
+      elsif publish_payload payload
+        @cache.save test_run if cache_enabled
+        true
+      else
+        false
+      end
+
+      save_payload payload if @save_payload
+      print_payload payload if @print_payload
+
+      published
+    end
+
+    private
+
+    def build_payload test_run, options = {}
+      begin
+        TestPayload.new(test_run).to_h options
+      rescue PayloadError => e
+        fail e.message
+      end
+    end
+
+    def fail msg, type = :error
+      styles = { warning: [ :yellow ], error: [ :bold, :red ] }
+      warn Paint["ROX - #{msg}", *styles[type]]
+      false
+    end
+
+    def load_cache
+      begin
+        @cache.load
+      rescue Cache::Error => e
+        warn Paint["ROX - #{e.message}", :yellow]
+        false
+      end
+    end
+
+    def print_payload payload
+      puts Paint['ROX - Printing payload...', :yellow]
+      begin
+        puts JSON.pretty_generate(payload)
+      rescue
+        puts payload.inspect
+      end
+    end
+
+    def save_payload payload
+
+      missing = { "workspace" => @workspace, "server" => @server }.inject([]){ |memo,(k,v)| !v ? memo << k : memo }
+      return fail "Cannot save payload without a #{missing.join ' and '}" if missing.any?
+
+      FileUtils.mkdir_p File.dirname(payload_file)
+      File.open(payload_file, 'w'){ |f| f.write Oj.dump(payload, mode: :strict) }
+    end
+
+    def payload_file
+      @payload_file ||= File.join(@workspace, 'rspec', 'servers', @server.name, 'payload.json')
+    end
+
+    def publish_payload payload
+
+      puts Paint["ROX - Sending payload to #{@server.api_url}...", :magenta]
+
+      begin
+        if @local_mode
+          puts Paint['ROX - LOCAL MODE: not actually sending payload.', :yellow]
+        else
+          @server.upload payload
+        end
+        puts Paint["ROX - Done!", :green]
+        true
+      rescue Server::Error => e
+        warn Paint["ROX - Upload failed!", :red, :bold]
+        warn Paint["ROX - #{e.message}", :red, :bold]
+        if e.response
+          warn Paint["ROX - Dumping response body...", :red, :bold]
+          warn e.response.body
+        end
+        false
+      end
+    end
+  end
+end

data/lib/rox-client-rspec/config.rb

@@ -0,0 +1,178 @@
+require 'yaml'
+
+# Utilities to send test results to ROX Center.
+module RoxClient::RSpec
+
+  def self.config
+    @config ||= Config.new.tap(&:load)
+  end
+
+  def self.configure options = {}
+    yield config if block_given?
+    config.load_warnings.each{ |w| warn Paint["ROX - #{w}", :yellow] }
+    config.setup! if options[:setup] != false
+    config
+  end
+
+  class Config
+    # TODO: add silent/verbose option(s)
+    class Error < RoxClient::RSpec::Error; end
+    attr_writer :publish, :local_mode, :cache_payload, :print_payload, :save_payload
+    attr_reader :project, :server, :workspace, :load_warnings
+
+    def initialize
+      @servers = []
+      @project = Project.new
+      @publish, @local_mode, @cache_payload, @print_payload, @save_payload = false, false, false, false, false
+      @load_warnings = []
+    end
+
+    def workspace= dir
+      @workspace = dir ? File.expand_path(dir) : nil
+    end
+
+    def servers
+      @servers.dup
+    end
+
+    # Plugs ROX utilities into RSpec.
+    def setup!
+      ::RSpec.configure do |c|
+        c.add_formatter Formatter
+      end
+    end
+
+    %w(publish local_mode cache_payload print_payload save_payload).each do |name|
+      define_method("#{name}?"){ instance_variable_get("@#{name}") }
+    end
+
+    def client_options
+      {
+        publish: @publish,
+        local_mode: @local_mode,
+        workspace: @workspace,
+        cache_payload: @cache_payload,
+        print_payload: @print_payload,
+        save_payload: @save_payload
+      }.select{ |k,v| !v.nil? }
+    end
+
+    def load
+
+      @load_warnings = []
+      return unless config = load_config_files
+
+      @publish = parse_env_flag :publish, !!config[:publish]
+      @server_name = parse_env_option(:server) || config[:server]
+      @local_mode = parse_env_flag(:local) || !!config[:local]
+
+      self.workspace = parse_env_option(:workspace) || config[:workspace]
+      @cache_payload = parse_env_flag :cache_payload, !!config[:payload][:cache]
+      @print_payload = parse_env_flag :print_payload, !!config[:payload][:print]
+      @save_payload = parse_env_flag :save_payload, !!config[:payload][:save]
+
+      @servers, @server = build_servers config
+
+      if @servers.empty?
+        @load_warnings << "No server defined"
+      elsif !@server_name
+        @load_warnings << "No server name given"
+      elsif !@server
+        @load_warnings << "Unknown server '#{@server_name}'"
+      end
+
+      project_options = config[:project]
+      project_options.merge! api_id: @server.project_api_id if @server and @server.project_api_id
+      @project.update project_options
+
+      self
+    end
+
+    private
+
+    def build_servers config
+
+      servers = {}
+
+      default_server_options = { project_api_id: config[:project][:api_id] }
+      config[:servers].each do |server_options|
+
+        name = server_options[:name].to_s.strip
+        if name.empty?
+          @load_warnings << "Ignoring unnamed server"
+          next
+        elsif servers[name]
+          servers[name].merge! server_options
+          next
+        end
+
+        servers[name] = server_options
+      end
+
+      servers.each_key{ |name| servers[name] = Server.new default_server_options.merge(servers[name]) }
+
+      [ servers.values, servers[@server_name.to_s.strip] ]
+    end
+
+    def load_config_files
+
+      configs = [ home_config_file, working_config_file ]
+      actual_configs = configs.select{ |f| File.exists? f }
+
+      if actual_configs.empty?
+        @load_warnings << %|no config file found, looking for:\n     #{configs.join "\n     "}|
+        return false
+      end
+
+      actual_configs.collect!{ |f| YAML.load_file f }
+
+      actual_configs.inject({}) do |memo,yml|
+        memo.merge! parse_general_options(yml)
+        memo[:servers] = (memo[:servers] || []) + (yml['servers'].kind_of?(Array) ? yml['servers'].collect{ |s| parse_server_options s } : [])
+        memo[:payload] = (memo[:payload] || {}).merge parse_payload_options(yml['payload'])
+        memo[:project] = (memo[:project] || {}).merge parse_project_options(yml['project'])
+        memo
+      end
+    end
+
+    def home_config_file
+      File.join File.expand_path('~'), '.rox', 'config.yml'
+    end
+
+    def working_config_file
+      File.expand_path ENV['ROX_CONFIG'] || 'rox.yml', Dir.pwd
+    end
+
+    def parse_env_flag name, default = false
+      val = parse_env_option name
+      val ? !!val.to_s.strip.match(/\A(1|t|true)\Z/i) : default
+    end
+
+    def parse_env_option name
+      var = "ROX_#{name.upcase}"
+      ENV.key?(var) ? ENV[var] : nil
+    end
+
+    def parse_general_options h
+      parse_options h, %w(publish server local workspace)
+    end
+
+    def parse_server_options h
+      parse_options h, %w(name apiUrl apiKeyId apiKeySecret apiVersion projectApiId)
+    end
+
+    def parse_payload_options h
+      parse_options h, %w(save cache print)
+    end
+
+    def parse_project_options h
+      # TODO: remove project name once API v0 is dead
+      parse_options h, %w(name version apiId category tags tickets)
+    end
+
+    def parse_options h, keys
+      return {} unless h.kind_of? Hash
+      keys.inject({}){ |memo,k| memo[k.gsub(/(.)([A-Z])/, '\1_\2').downcase.to_sym] = h[k] if h.key?(k); memo }
+    end
+  end
+end