rtrail 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZmEzZWQxZWViOTUwZWJhZjEwNDJmYmU3ODBlY2E3ODkxMjViM2Y3OQ==
+  data.tar.gz: !binary |-
+    ZjhkODIwMmY3ZWE0MDE4ODk4ZWNjZGJhOTQwNDFmYTMwNWJkOTkwMA==
+SHA512:
+  metadata.gz: !binary |-
+    Yzg0NDgxZDA1NWM2ZTkzMTc4ZTkwOWFlYTAzMTRjMmUxYWZjOTU3YTBmZjVl
+    NDhlNDM2YmViMWUxMmI1NjM5ZTNmYTQ2NzEzNmM5YWFlZGU5MDQ1MTc5MjFk
+    YzYzOTkzNzM4MWRhYmRmZjcwNDBjYjk5ZDI0NmVlMDcwNWNkNWM=
+  data.tar.gz: !binary |-
+    MzIzYWRkOWRiOTg4MjI2MTM0NzE3YWJjYmJiYWY2OGMwYTA5ZTVmNWUyN2I0
+    NmY5MjViOTcwZGUwZjkzMDAxNmM2MTIzY2M2YmQzMmM0ZTYxN2EwNTA1NDBl
+    M2RmMDE5NTRiYTBiYzc0OTEwODk2OTNjMDRlMWRhMzk3Zjc1NjY=

data/.gitignore

@@ -0,0 +1,4 @@
+.ruby-version
+.ruby-gemset
+Gemfile.lock
+coverage/*

data/.rspec

@@ -0,0 +1 @@
+--format doc --color

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Automation Excellence
+
+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,96 @@
+RTrail
+======
+
+Ruby object wrapper for the TestRail API.
+
+RTrail uses the [TestRail API v2](http://docs.gurock.com/testrail-api2/start),
+which means you must use TestRail 3.x or later.
+
+
+Installation
+------------
+
+Run from a console:
+
+    $ gem install rtrail
+
+Or add to your `Gemfile`:
+
+    gem 'rtrail'
+
+
+Overview
+--------
+
+RTrail provides a hierarchy of Ruby objects, mirroring the data structure
+within TestRail. Here's a rough look:
+
+- Project(s)
+  - Plan(s)
+  - Suite(s)
+    - Case(s)
+    - Section(s)
+  - Run(s)
+    - Test(s)
+      - Result(s)
+
+Within RTrail, each of these things are modeled by a class, with a common base
+class known as `Entity`.
+
+
+Usage
+-----
+
+The top-level interface is through `RTrail::API`; simply provide your TestRail
+server's hostname, username and password:
+
+    > api = RTrail::API.new("http://example.com/", "epierce", "myPa$$w0rd")
+
+Some convenience methods are provided; for example:
+
+    # Get a list of all Projects
+    > api.projects
+    => [#<RTrail::Project ...>, ..., #<RTrail::Project ...>]
+
+    # Get a single Project by name
+    > api.project("Web Applications")
+    => #<RTrail::Project ...>
+
+    # Get a Suite within a Project
+    > api.suite("Web Applications", "Storefront")
+    => #<RTrail::Suite ...>
+
+Each Entity type provides wrappers for some of the API methods you're likely to
+use; for instance:
+
+    > project = api.project("Web Applications")
+    > project.suites        # GET /get_suites/<project_id>
+    > project.plans         # GET /get_plans/<project_id>
+    > project.runs          # GET /get_runs/<project_id>
+
+    > project.runs.count
+    => 4
+
+    > project.runs.each { |run| run.id }
+    => [103, 104, 119, 127]
+
+    > run = project.runs.first
+
+    > run.completed?
+    => true
+    > run.summary
+    => "103: Website Login [completed 2014-07-16 21:45:08 UTC]
+
+
+Development
+-----------
+
+To contribute, please fork this repository, and submit a pull request with your
+changes.
+
+
+License
+-------
+
+MIT License.
+

data/lib/rtrail.rb

@@ -0,0 +1,19 @@
+[
+  'api',
+  'case',
+  'client',
+  'entity',
+  'exceptions',
+  'plan',
+  'project',
+  'result',
+  'run',
+  'suite',
+  'test'
+].each do |file|
+  require_relative "rtrail/#{file}"
+end
+
+module RTrail
+end
+

data/lib/rtrail/api.rb

@@ -0,0 +1,42 @@
+require_relative 'client'
+require_relative 'entity'
+require_relative 'project'
+
+module RTrail
+  # High-level API for TestRail
+  class API
+    def initialize(hostname, user, password)
+      url = hostname.gsub(/\/$/, '') + '/index.php?/api/v2/'
+
+      @client = RTrail::Client.new(url, user, password)
+
+      # FIXME: This is a bit hinky, but works well
+      RTrail::Entity.client = @client
+    end
+    attr_reader :client
+
+    # Convenience methods for commonly-accessed entities
+
+    def projects
+      return Project.all
+    end
+
+    def project(project_name)
+      return Project.by_name(project_name)
+    end
+
+    def suite(project_name, suite_name)
+      return Project.by_name(project_name).suite_by_name(suite_name)
+    end
+
+    def runs(project_name)
+      return project(project_name).runs
+    end
+
+    def cases(project_name, suite_name)
+      return suite(project_name, suite_name).cases
+    end
+
+  end # class API
+end # module RTrail
+

data/lib/rtrail/case.rb

@@ -0,0 +1,8 @@
+require_relative 'entity'
+
+module RTrail
+  class Case < Entity
+    include HasCreateTime
+  end
+end # module RTrail
+

data/lib/rtrail/client.rb

@@ -0,0 +1,113 @@
+require 'net/http'
+require 'net/https'
+require 'uri'
+require 'json'
+require 'hashie'
+
+require_relative 'exceptions'
+
+module RTrail
+  class Client
+    def initialize(base_url, user, password)
+      @base_url = base_url
+      @user = user
+      @password = password
+    end
+    attr_reader :base_url, :user, :password
+
+    # Send a GET request to the API and return a Hashie::Mash (for individual
+    # object requests) or an Array of Hashie::Mash (for requests returning a
+    # list of objects).
+    #
+    # @param [String] path
+    #   The API method to call including parameters (e.g. get_case/1)
+    #
+    def get(path)
+      _request(:get, path)
+    end
+
+    # Send a POST request to the API and return a Hashie::Mash.
+    #
+    # @param [String] path
+    #   The API method to call including parameters (e.g. add_case/1)
+    # @param [Hash] data
+    #   The data to submit as part of the request. Strings must be UTF-8
+    #   encoded.
+    #
+    def post(path, data)
+      _request(:post, path, data)
+    end
+
+    private
+
+    # Send a GET or POST request to the given path, and return a
+    # Hashie::Mash or Array of Hashie::Mash.
+    #
+    # @param [Symbol] method
+    #   :get or :post
+    #
+    def _request(method, path, data=nil)
+      url = URI.parse(@base_url + path)
+      url_with_query = "#{url.path}?#{url.query}"
+
+      if method == :post
+        request = Net::HTTP::Post.new(url_with_query)
+        request.body = JSON.dump(data)
+      else
+        request = Net::HTTP::Get.new(url_with_query)
+      end
+
+      request.basic_auth(@user, @password)
+      request.add_field("Content-Type", "application/json")
+
+      conn = Net::HTTP.new(url.host, url.port)
+      if url.scheme == "https"
+        conn.use_ssl = true
+        conn.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      response = conn.request(request)
+      return _result(response)
+    end
+
+    # Parse a Net::HTTPResponse as JSON, and return a Hashie::Mash,
+    # or an Array of Hashie::Mash.
+    #
+    # @raise [RTrail::Error]
+    #   If the response code is anything but 200 OK, if the response cannot be
+    #   parsed as JSON, or if the parsed JSON is neither a Hash nor Array.
+    #
+    def _result(response)
+      if response.body && !response.body.empty?
+        begin
+          result = JSON.parse(response.body)
+        rescue => ex
+          raise RTrail::Error.new(
+            "Error parsing JSON response: #{ex.message}")
+        end
+      else
+        result = {}
+      end
+
+      if response.code != "200"
+        if result && result.key?("error")
+          error = result["error"]
+        else
+          error = "Unknown error"
+        end
+        raise RTrail::Error.new(
+          "TestRail API returned HTTP #{response.code} (#{error})")
+      end
+
+      if result.is_a?(Hash)
+        return Hashie::Mash.new(result)
+      elsif result.is_a?(Array)
+        return result.map {|h| Hashie::Mash.new(h)}
+      else
+        raise RTrail::Error.new(
+          "Unexpected result type: #{result.class.name}")
+      end
+    end
+
+  end # class Client
+end # module RTrail
+

data/lib/rtrail/entity.rb

@@ -0,0 +1,65 @@
+require_relative 'helpers'
+
+module RTrail
+  # Base class for RTrail objects
+  class Entity
+    include Helpers
+
+    class << self
+      def client=(client)
+        @@client = client
+      end
+
+      def client
+        @@client
+      end
+
+      # Return the plain lowercase name of the derived class,
+      # ex. "project", "suite", "case", suitable for passing
+      # to the `get_*` API methods.
+      def basename
+        return self.name.downcase.gsub(/^.*::/, '')
+      end
+    end
+
+    def client
+      return self.class.client
+    end
+
+    def initialize(id_or_data)
+      if id_or_data.is_a?(Hash) || id_or_data.is_a?(Entity)
+        @data = Hashie::Mash.new(id_or_data)
+      else
+        @data = fetch(id_or_data)
+      end
+    end
+    attr_accessor :data
+
+    # Fetch data for a derived class object.
+    def fetch(id)
+      return client.get("get_#{self.class.basename}/#{id}")
+    end
+
+    # Pass-through to Hashie::Mash for attribute access
+    def method_missing(meth, *args, &block)
+      return data.send(meth, *args, &block)
+    end
+
+    # Return a list of entities retrieved from `get_<thing>s/<id>`.
+    def get_entities(klass, parent_id, params={})
+      path = path_with_params(
+        "get_#{klass.basename}s/#{parent_id}", params)
+
+      return client.get(path).map do |data|
+        klass.new(data)
+      end
+    end
+
+    # Add a new entity by invoking POST `add_<thing>/<id>`.
+    def add_entity(klass, parent_id, params={})
+      path = "add_#{klass.basename}/#{parent_id}"
+      return klass.new(client.post(path, params))
+    end
+  end
+end # module RTrail
+

data/lib/rtrail/exceptions.rb

@@ -0,0 +1,4 @@
+module RTrail
+  class Error < StandardError; end
+  class NotFound < Error; end
+end # module RTrail

data/lib/rtrail/helpers.rb

@@ -0,0 +1,32 @@
+module RTrail
+  module Helpers
+    # Return true if `name_or_id` appears to be a numeric id,
+    # false otherwise.
+    def is_id?(name_or_id)
+      # Use !! to convert regex comparison to boolean
+      return !!(name_or_id.to_s =~ /^[0-9]+$/)
+    end
+
+    # Return an HTTP path with parameters appended in GET syntax.
+    def path_with_params(path, params={})
+      if params.empty?
+        return path
+      else
+        # FIXME: What if value contains a space?
+        param_string = params.map do |k,v|
+          "#{k}=#{v}"
+        end.join("&")
+        return path + "&" + param_string
+      end
+    end
+
+    # Include this in any Entity with a `created_on` attribute
+    # to allow getting creation date as a Time instance.
+    module HasCreateTime
+      def create_time
+        return Time.at(self[:created_on].to_i).utc
+      end
+    end
+  end # module Helpers
+end # module RTrail
+

data/lib/rtrail/plan.rb

@@ -0,0 +1,7 @@
+require_relative 'entity'
+
+module RTrail
+  class Plan < Entity
+  end
+end # module RTrail
+