probe-dock-rspec 0.5.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTJlNjI0N2E1ZjkzZGZjMzExNWUwZjY1MTlkNDRjZTFjNzZiZjJiMQ==
+  data.tar.gz: !binary |-
+    NmU1M2JjNzY2Y2E5MjE1OWIyOTQ1ZjI4MjcxYTkxODBkZGZiMGVlNg==
+SHA512:
+  metadata.gz: !binary |-
+    OGRhYWU3MjIxMjUxMWNlYTAxNWI3NWEzNDE2MTI4YmY0NDlmMGRjNDY3YTYw
+    ZjhmN2ExZWQ2MTJjMDFkMjNmMDcyN2U5MGU3ZTcwMjIxOTFlMDVjZTM0Zjhj
+    NTM4OGU5MjBiMTQyZTY3MjUxMGU2ZjM3MDNhNDkzMjg2ZTc5MDY=
+  data.tar.gz: !binary |-
+    NGIwZmM2NWJiZjc2MTExMjU3MWFlNDFiM2UxMjVjYjFlZmRhN2U4M2VjZjBi
+    NTI3ODBkMzJjNTg0MGVhMzg2YmZjYTNhNjIxZmU1MzE5ZWQ3MGI3YzI2OWIz
+    ODIyYTE4ZWExODQxOTI3NjBiYTFhODFmYzg1ZmUzYjg5MDU5NjE=

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', '~> 3.1'
+gem 'oj', '~> 2.1'
+gem 'httparty', '~> 0.13'
+gem 'paint', '~> 1.0'
+gem 'rake', '~> 10.1'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'jeweler', '~> 2.0'
+  gem 'rake-version', '~> 0.4'
+  gem 'simplecov', '~> 0.10'
+  gem 'fakefs', '~> 0.6', require: 'fakefs/safe'
+  gem 'rspec-its', '~> 1.2'
+  gem 'rspec-collection_matchers', '~> 1.1'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2015 Probe Dock
+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,69 @@
+# Probe Dock RSpec
+
+**RSpec probe for [Probe Dock](https://github.com/probe-dock/probe-dock).**
+
+[![Gem Version](https://badge.fury.io/rb/probe-dock-rspec.png)](http://badge.fury.io/rb/probe-dock-rspec)
+
+## Requirements
+
+* RSpec 3+
+
+## Installation
+
+In your Gemfile:
+
+```rb
+gem 'probe-dock-rspec', '~> 0.4.1'
+```
+
+Manually:
+
+    gem install probe-dock-rspec
+
+## Usage
+
+If you haven't done it already, follow the [setup procedure](#setup) below.
+
+To track a test with a Probe Dock test key, use RSpec metadata:
+
+```rb
+it "should work", probe_dock: { key: 'abcdefghijkl' } do
+  expect(true).to be(true)
+end
+
+it(nil, probe_dock: { key: 'bcdefghijklm' }){ should validate_presence_of(:name) }
+```
+
+<a name="setup"></a>
+## Setup
+
+You must first set up the configuration file(s) for the project.
+This procedure is described here:
+
+* [Probe Setup Procedure](https://github.com/probe-dock/probe-dock-clients#setup-procedure)
+
+You must then enable the client in your spec helper file (e.g. `spec/spec_helper.rb`).
+
+```yml
+ProbeDockRSpec.configure do |config|
+
+  # Optional 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 probe will send the results to your Probe Dock 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](CHANGELOG.md) entry with your name for new features and bug fixes.
+
+## License
+
+Probe Dock RSpec is licensed under the [MIT License](http://opensource.org/licenses/MIT).
+See [LICENSE.txt](LICENSE.txt) for the full license.

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/lib/probe-dock-rspec.rb

@@ -0,0 +1 @@
+require 'probe_dock_rspec'

data/lib/probe_dock_rspec.rb

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

data/lib/probe_dock_rspec/cache.rb

@@ -0,0 +1,61 @@
+
+module ProbeDockRSpec
+
+  class Cache
+
+    class Error < ProbeDockRSpec::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.select(&:key).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
+      test_result.key && !!@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/probe_dock_rspec/client.rb

@@ -0,0 +1,120 @@
+
+module ProbeDockRSpec
+
+  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
+
+      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["Probe Dock - 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
+
+      puts
+
+      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["Probe Dock - #{msg}", *styles[type]]
+      false
+    end
+
+    def load_cache
+      begin
+        @cache.load
+      rescue Cache::Error => e
+        warn Paint["Probe Dock - #{e.message}", :yellow]
+        false
+      end
+    end
+
+    def print_payload payload
+      puts Paint['Probe Dock - 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["Probe Dock - Sending payload to #{@server.api_url}...", :magenta]
+
+      begin
+        if @local_mode
+          puts Paint['Probe Dock - LOCAL MODE: not actually sending payload.', :yellow]
+        else
+          @server.upload payload
+        end
+        puts Paint["Probe Dock - Done!", :green]
+        true
+      rescue Server::Error => e
+        warn Paint["Probe Dock - Upload failed!", :red, :bold]
+        warn Paint["Probe Dock - #{e.message}", :red, :bold]
+        if e.response
+          warn Paint["Probe Dock - Dumping response body...", :red, :bold]
+          warn e.response.body
+        end
+        false
+      end
+    end
+  end
+end

data/lib/probe_dock_rspec/config.rb

@@ -0,0 +1,173 @@
+require 'yaml'
+
+# Utilities to send test results to Probe Dock.
+module ProbeDockRSpec
+
+  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["Probe Dock - #{w}", :yellow] }
+    config.setup! if options[:setup] != false
+    config
+  end
+
+  class Config
+    # TODO: add silent/verbose option(s)
+    class Error < ProbeDockRSpec::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 Probe Dock 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
+
+      default_server_options = { project_api_id: config[:project][:api_id] }
+      servers = config[:servers].inject({}) do |memo,(name, options)|
+        memo[name] = Server.new default_server_options.merge(options).merge(name: name)
+        memo
+      end
+
+      [ 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({ servers: {} }) do |memo,yml|
+        memo.merge! parse_general_options(yml)
+
+        if yml['servers'].kind_of? Hash
+          yml['servers'].each_pair do |k,v|
+            if v.kind_of? Hash
+              memo[:servers][k] = (memo[:servers][k] || {}).merge(parse_server_options(v))
+            end
+          end
+        end
+
+        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('~'), '.probe-dock', 'config.yml'
+    end
+
+    def working_config_file
+      File.expand_path ENV['PROBE_DOCK_CONFIG'] || 'probe-dock.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 = "PROBE_DOCK_#{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 apiToken apiVersion projectApiId)
+    end
+
+    def parse_payload_options h
+      parse_options h, %w(save cache print)
+    end
+
+    def parse_project_options h
+      parse_options h, %w(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

data/lib/probe_dock_rspec/formatter.rb

@@ -0,0 +1,83 @@
+require 'paint'
+require 'fileutils'
+require 'rspec/core/formatters/base_formatter'
+
+module ProbeDockRSpec
+
+  class Formatter
+
+    RSpec::Core::Formatters.register self, :start, :stop, :close,
+      :example_group_started, :example_started, :example_passed, :example_failed, :example_group_finished
+
+    def initialize output
+
+      config = ProbeDockRSpec.config
+      @client = Client.new config.server, config.client_options
+      @test_run = TestRun.new config.project
+
+      @groups = []
+    end
+
+    def start notification
+      # TODO: measure milliseconds
+      @start_time = Time.now
+    end
+
+    def example_group_started group_notification
+      @groups << group_notification.group
+    end
+
+    def example_group_finished group_notification
+      @groups.pop
+    end
+
+    def example_started example_notification
+      @current_time = Time.now
+    end
+
+    def example_passed example_notification
+      add_result example_notification, true
+    end
+
+    def example_failed example_notification
+      add_result example_notification, false
+    end
+
+    def stop notification
+      end_time = Time.now
+      @test_run.duration = ((end_time - @start_time) * 1000).round
+    end
+
+    def close notification
+      @client.process @test_run
+    end
+
+    private
+
+    def add_result example_notification, successful
+
+      options = {
+        passed: successful,
+        duration: ((Time.now - @current_time) * 1000).round
+      }
+
+      options[:message] = failure_message example_notification unless successful
+
+      @test_run.add_result example_notification.example, @groups, options
+    end
+
+    def failure_message example_notification
+      String.new.tap do |m|
+        m << example_notification.description
+        m << "\n"
+        m << example_notification.message_lines.collect{ |l| "  #{l}" }.join("\n")
+        m << "\n"
+        m << example_notification.formatted_backtrace.collect{ |l| "  # #{l}" }.join("\n")
+      end
+    end
+
+    def full_example_name example
+      (@groups.collect{ |g| g.description.strip } << example.description.strip).join ' '
+    end
+  end
+end

data/lib/probe_dock_rspec/project.rb

@@ -0,0 +1,30 @@
+module ProbeDockRSpec
+
+  class Project
+    attr_accessor :version, :api_id, :category, :tags, :tickets
+
+    def initialize options = {}
+      update options
+    end
+
+    def update options = {}
+      %w(version api_id category).each do |k|
+        instance_variable_set "@#{k}", options[k.to_sym] ? options[k.to_sym].to_s : nil if options.key? k.to_sym
+      end
+      @tags = wrap(options[:tags]).compact if options.key? :tags
+      @tickets = wrap(options[:tickets]).compact if options.key? :tickets
+    end
+
+    def validate!
+      required = { "version" => @version, "API identifier" => @api_id }
+      missing = required.inject([]){ |memo,(k,v)| v.to_s.strip.length <= 0 ? memo << k : memo }
+      raise PayloadError.new("Missing project options: #{missing.join ', '}") if missing.any?
+    end
+
+    private
+
+    def wrap a
+      a.kind_of?(Array) ? a : [ a ]
+    end
+  end
+end

data/lib/probe_dock_rspec/server.rb

@@ -0,0 +1,58 @@
+require 'oj'
+require 'httparty'
+
+module ProbeDockRSpec
+
+  class Server
+    attr_reader :name, :api_url, :api_token, :api_version, :project_api_id
+
+    class Error < ProbeDockRSpec::Error
+      attr_reader :response
+
+      def initialize msg, response = nil
+        super msg
+        @response = response
+      end
+    end
+
+    def initialize options = {}
+      @name = options[:name].to_s.strip
+      @api_url = options[:api_url].to_s if options[:api_url]
+      @api_token = options[:api_token].to_s if options[:api_token]
+      @api_version = options[:api_version] || 1
+      @project_api_id = options[:project_api_id].to_s if options[:project_api_id]
+    end
+
+    def payload_options
+      { version: @api_version }
+    end
+
+    def upload payload
+      validate!
+
+      body = Oj.dump payload, mode: :strict
+      res = HTTParty.post payload_uri, body: body, headers: payload_headers
+
+      if res.code != 202
+        raise Error.new("Expected HTTP 202 Accepted when submitting payload, got #{res.code}", res)
+      end
+    end
+
+    private
+
+    def validate!
+      required = { "apiUrl" => @api_url }
+      required.merge!({ "apiToken" => @api_token, "projectApiId" => @project_api_id }) if @api_version >= 1
+      missing = required.inject([]){ |memo,(k,v)| v.to_s.strip.length <= 0 ? memo << k : memo }
+      raise Error.new("Server #{@name} is missing the following options: #{missing.join ', '}") if missing.any?
+    end
+
+    def payload_headers
+      { 'Authorization' => "Bearer #{@api_token}", 'Content-Type' => 'application/vnd.probe-dock.payload.v1+json' }
+    end
+
+    def payload_uri
+      "#{@api_url}/publish"
+    end
+  end
+end

data/lib/probe_dock_rspec/tasks.rb

@@ -0,0 +1,62 @@
+require 'fileutils'
+require 'rake/tasklib'
+
+module ProbeDockRSpec
+
+  class Tasks < ::Rake::TaskLib
+
+    def initialize
+
+      namespace :spec do
+
+        namespace 'probe-dock' do
+
+          desc "Generate a test run UID to group test results in Probe Dock (stored in an environment variable)"
+          task :uid do
+            trace do
+              uid = uid_manager.generate_uid_to_env
+              puts Paint["Probe Dock - Generated UID for test run: #{uid}", :cyan]
+            end
+          end
+
+          namespace :uid do
+
+            desc "Generate a test run UID to group test results in Probe Dock (stored in a file)"
+            task :file do
+              trace do
+                uid = uid_manager.generate_uid_to_file
+                puts Paint["Probe Dock - Generated UID for test run: #{uid}", :cyan]
+              end
+            end
+
+            desc "Clean the test run UID (file and environment variable)"
+            task :clean do
+              trace do
+                uid_manager.clean_uid
+                puts Paint["Probe Dock - Cleaned test run UID", :cyan]
+              end
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    def trace &block
+      if Rake.application.options.trace
+        block.call
+      else
+        begin
+          block.call
+        rescue UID::Error => e
+          warn Paint["Probe Dock - #{e.message}", :red]
+        end
+      end
+    end
+
+    def uid_manager
+      UID.new ProbeDockRSpec.config.client_options
+    end
+  end
+end

data/lib/probe_dock_rspec/test_payload.rb

@@ -0,0 +1,18 @@
+require 'fileutils'
+require 'digest/sha2'
+
+module ProbeDockRSpec
+
+  class TestPayload
+
+    class Error < ProbeDockRSpec::Error; end
+
+    def initialize run
+      @run = run
+    end
+
+    def to_h options = {}
+      @run.to_h options
+    end
+  end
+end

data/lib/probe_dock_rspec/test_result.rb

@@ -0,0 +1,119 @@
+
+module ProbeDockRSpec
+
+  class TestResult
+    attr_reader :key, :name, :category, :tags, :tickets, :data, :duration, :message
+
+    def initialize project, example, groups = [], options = {}
+
+      @category = project.category
+      @tags = project.tags
+      @tickets = project.tickets
+
+      @grouped = extract_grouped example, groups
+
+      [ :key, :name, :category, :tags, :tickets, :data ].each do |attr|
+        instance_variable_set "@#{attr}".to_sym, send("extract_#{attr}".to_sym, example, groups)
+      end
+
+      @passed = !!options[:passed]
+      @duration = options[:duration]
+      @message = options[:message]
+    end
+
+    def passed?
+      @passed
+    end
+
+    def grouped?
+      @grouped
+    end
+
+    def update options = {}
+      @passed &&= options[:passed]
+      @duration += options[:duration]
+      @message = [ @message, options[:message] ].select{ |m| m }.join("\n\n") if options[:message]
+    end
+
+    def to_h options = {}
+      {
+        'p' => @passed,
+        'd' => @duration
+      }.tap do |h|
+
+        h['k'] = @key if @key
+        h['m'] = @message if @message
+
+        cache = options[:cache]
+        first = !cache || !cache.known?(self)
+        stale = !first && cache.stale?(self)
+        h['n'] = @name if stale or first
+        h['c'] = @category if stale or (first and @category)
+        h['g'] = @tags if stale or (first and !@tags.empty?)
+        h['t'] = @tickets if stale or (first and !@tickets.empty?)
+        h['a'] = @data if @data # FIXME: cache custom data
+      end
+    end
+
+    def self.extract_grouped example, groups = []
+      !!groups.collect{ |g| meta(g)[:grouped] }.compact.last
+    end
+
+    def self.extract_key example, groups = []
+      (groups.collect{ |g| meta(g)[:key] } << meta(example)[:key]).compact.reject{ |k| k.strip.empty? }.last
+    end
+
+    def self.meta holder
+      meta = holder.metadata[:probe_dock] || {}
+      if meta.kind_of? String
+        { key: meta }
+      elsif meta.kind_of? Hash
+        meta
+      else
+        {}
+      end
+    end
+
+    private
+
+    def meta *args
+      self.class.meta *args
+    end
+
+    def extract_grouped *args
+      self.class.extract_grouped *args
+    end
+
+    def extract_key *args
+      self.class.extract_key *args
+    end
+
+    def extract_name example, groups = []
+      parts = groups.dup
+      parts = parts[0, parts.index{ |p| meta(p)[:grouped] } + 1] if @grouped
+      parts << example unless @grouped
+      parts.collect{ |p| p.description.strip }.join ' '
+    end
+
+    def extract_category example, groups = []
+      cat = (groups.collect{ |g| meta(g)[:category] }.unshift(@category) << meta(example)[:category]).compact.last
+      cat ? cat.to_s : nil
+    end
+
+    def extract_tags example, groups = []
+      (wrap(@tags) + groups.collect{ |g| wrap meta(g)[:tags] } + (wrap meta(example)[:tags])).flatten.compact.uniq.collect(&:to_s)
+    end
+
+    def extract_tickets example, groups = []
+      (wrap(@tickets) + groups.collect{ |g| wrap meta(g)[:tickets] } + (wrap meta(example)[:tickets])).flatten.compact.uniq.collect(&:to_s)
+    end
+
+    def extract_data example, groups = []
+      meta(example)[:data]
+    end
+
+    def wrap a
+      a.kind_of?(Array) ? a : [ a ]
+    end
+  end
+end

data/lib/probe_dock_rspec/test_run.rb

@@ -0,0 +1,85 @@
+
+module ProbeDockRSpec
+
+  class TestRun
+    attr_reader :results, :project
+    attr_accessor :duration, :uid
+
+    def initialize project
+      @results = []
+      @project = project
+    end
+
+    def add_result example, groups = [], options = {}
+      if TestResult.extract_grouped(example, groups) and (existing_result = @results.find{ |r| r.grouped? && r.key == TestResult.extract_key(example, groups) })
+        existing_result.update options
+      else
+        @results << TestResult.new(@project, example, groups, options)
+      end
+    end
+
+    def results_without_key
+      @results.select{ |r| !r.key or r.key.to_s.strip.empty? }
+    end
+
+    def results_by_key
+      @results.inject({}) do |memo,r|
+        (memo[r.key] ||= []) << r unless !r.key or r.key.to_s.strip.empty?
+        memo
+      end
+    end
+
+    def to_h options = {}
+      validate!
+
+      {
+        'projectId' => @project.api_id,
+        'version' => @project.version,
+        'duration' => @duration,
+        'results' => @results.collect{ |r| r.to_h options }
+      }.tap do |h|
+        h['reports'] = [ { 'uid' => @uid } ] if @uid
+      end
+    end
+
+    private
+
+    def validate!
+      # TODO: validate duration
+
+      raise PayloadError.new("Missing project") if !@project
+      @project.validate!
+
+      # FIXME: log info/warnings
+      #validate_no_results_without_key
+      #validate_no_duplicate_keys
+    end
+
+    def validate_no_duplicate_keys
+
+      results_with_duplicate_key = results_by_key.select{ |k,r| r.length >= 2 }
+      return if results_with_duplicate_key.none?
+
+      msg = "the following keys are used by multiple test results".tap do |s|
+        results_with_duplicate_key.each_pair do |key,results|
+          s << "\n     - #{key}"
+          results.each{ |r| s << "\n       - #{r.name}" }
+        end
+      end
+
+      raise PayloadError.new(msg)
+    end
+
+    def validate_no_results_without_key
+
+      keyless = results_without_key
+      return if keyless.empty?
+
+      msg = "the following test results are missing a key".tap do |s|
+        keyless.each{ |r| s << "\n     - #{r.name}" }
+      end
+
+      raise PayloadError.new(msg)
+    end
+  end
+end

data/lib/probe_dock_rspec/uid.rb

@@ -0,0 +1,60 @@
+require 'securerandom'
+
+module ProbeDockRSpec
+
+  class UID
+    ENVIRONMENT_VARIABLE = 'PROBE_DOCK_TEST_REPORT_UID'
+
+    class Error < ProbeDockRSpec::Error; end
+
+    def initialize options = {}
+      @workspace = options[:workspace]
+    end
+
+    def load_uid
+      if env_var
+        return env_var
+      elsif @workspace
+        current_uid
+      end
+    end
+
+    def generate_uid_to_file
+      raise Error.new("No workspace specified; cannot save test run UID") if !@workspace
+      generate_uid.tap{ |uid| save_uid uid }
+    end
+
+    def generate_uid_to_env
+      raise Error.new("$PROBE_DOCK_TEST_REPORT_UID is already defined") if env_var
+      ENV[ENVIRONMENT_VARIABLE] = generate_uid
+    end
+
+    def clean_uid
+      ENV.delete ENVIRONMENT_VARIABLE
+      FileUtils.remove_entry_secure uid_file if @workspace and File.exists?(uid_file)
+    end
+
+    private
+
+    def save_uid uid
+      FileUtils.mkdir_p File.dirname(uid_file)
+      File.open(uid_file, 'w'){ |f| f.write uid }
+    end
+
+    def env_var
+      ENV[ENVIRONMENT_VARIABLE]
+    end
+
+    def current_uid
+      File.file?(uid_file) ? File.read(uid_file) : nil
+    end
+
+    def uid_file
+      @uid_file ||= File.join(@workspace, 'uid')
+    end
+
+    def generate_uid
+      "#{Time.now.utc.strftime '%Y%m%d%H%M%S'}-#{SecureRandom.uuid}"
+    end
+  end
+end

metadata

@@ -0,0 +1,221 @@
+--- !ruby/object:Gem::Specification
+name: probe-dock-rspec
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Simon Oulevay (Alpha Hydrae)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-05-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: !binary |-
+          MC4xMw==
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: !binary |-
+          MC4xMw==
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.1'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake-version
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: !binary |-
+          MC40
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: !binary |-
+          MC40
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec-collection_matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: RSpec client to publish test results to Probe Dock, a test tracking and
+  analysis server.
+email: simon.oulevay@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- VERSION
+- lib/probe-dock-rspec.rb
+- lib/probe_dock_rspec.rb
+- lib/probe_dock_rspec/cache.rb
+- lib/probe_dock_rspec/client.rb
+- lib/probe_dock_rspec/config.rb
+- lib/probe_dock_rspec/formatter.rb
+- lib/probe_dock_rspec/project.rb
+- lib/probe_dock_rspec/server.rb
+- lib/probe_dock_rspec/tasks.rb
+- lib/probe_dock_rspec/test_payload.rb
+- lib/probe_dock_rspec/test_result.rb
+- lib/probe_dock_rspec/test_run.rb
+- lib/probe_dock_rspec/uid.rb
+homepage: https://github.com/probe-dock/probe-dock-rspec
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: RSpec client to publish test results to Probe Dock.
+test_files: []