dockerspec 0.2.0 → 0.3.0

data/lib/dockerspec/runner/docker.rb

@@ -0,0 +1,302 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015-2016 Xabier de Zuazo
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'dockerspec/docker_gem'
+require 'dockerspec/exceptions'
+require 'dockerspec/helper/multiple_sources_description'
+require 'dockerspec/docker_exception_parser'
+require 'dockerspec/runner/base'
+
+module Dockerspec
+  #
+  # Contains the classes related to creating and starting docker containers.
+  #
+  module Runner
+    #
+    # This class runs a docker image (without using Serverspec for that).
+    #
+    # This class is used mainly when you are not using Serverspec to run the
+    # tests.
+    #
+    class Docker < Base
+      include Dockerspec::Helper::MultipleSourcesDescription
+
+      #
+      # @return [Symbol] The option key to set when you pass a string instead
+      #   of a hash of options.
+      #
+      OPTIONS_DEFAULT_KEY = :tag
+
+      #
+      # The internal {Docker::Container} object.
+      #
+      # @return [Docker::Container] The container.
+      #
+      attr_reader :container
+
+      #
+      # Constructs a Docker runner class to run Docker images.
+      #
+      # @example From a Running Docker Image
+      #   Dockerspec::Runner::Docker.new('debian:8')
+      #     #=> #<Dockerspec::Runner::Docker:0x0124>
+      #
+      # @example From a Running Docker Container ID
+      #   # This does not start any new container
+      #   Dockerspec::Runner::Docker.new(id: 'c51f86c28340')
+      #     #=> #<Dockerspec::Runner::Docker:0x0124>
+      #
+      # @example From a Running Docker Container Image Name
+      #   Dockerspec::Runner::Docker.new('my-debian')
+      #     #=> #<Dockerspec::Runner:0x0125>
+      #
+      # @param opts [String, Hash] The `:tag` or a list of options.
+      #
+      # @option opts [String] :tag The Docker image tag name to run.
+      # @option opts [String] :id The Docker container ID to use instead of
+      #   starting a new container.
+      # @option opts [Boolean] :rm (calculated) Whether to remove the Docker
+      #   container afterwards.
+      # @option opts [String] :path The environment `PATH` value of the
+      #   container.
+      # @option opts [Hash, Array] :env Some `ENV` instructions to add to the
+      #   container.
+      # @option opts [Integer] :wait Time to wait before running the tests.
+      #
+      # @return [Dockerspec::Runner::Docker] Runner object.
+      #
+      # @raise [Dockerspec::DockerRunArgumentError] Raises this exception when
+      #   some required options are missing.
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @api public
+      #
+      def initialize(*opts)
+        super
+        send("setup_from_#{source}", options[source])
+      end
+
+      #
+      # Gets the Docker image ID.
+      #
+      # @example
+      #   builder = Dockerspec::Builder.new('.').build
+      #   runner = Dockerspec::Runner::Docker.new(builder)
+      #   runner.image_id #=> "c51f86c28340[...]"
+      #
+      # @return [String] Image ID.
+      #
+      # @api public
+      #
+      def image_id
+        return @build.id unless @build.nil?
+        super
+      end
+
+      #
+      # Gets a descriptions of the object.
+      #
+      # @example Running from a Container Image ID
+      #   r = Dockerspec::Runner::Docker.new('debian')
+      #   r.to_s #=> "Docker Run from tag: \"debian\""
+      #
+      # @example Attaching to a Running Container ID
+      #   r = Dockerspec::Runner::Docker.new(id: '92cc98ab560a')
+      #   r.to_s #=> "Docker Run from id: \"92cc98ab560a\""
+      #
+      # @return [String] The object description.
+      #
+      # @api public
+      #
+      def to_s
+        description('Docker Run from')
+      end
+
+      protected
+
+      #
+      # Gets the source to start the container from.
+      #
+      # Possible values: `:tag`, `:id`.
+      #
+      # @example Start the Container from an Image Tag
+      #   self.source #=> :tag
+      #
+      # @example Attach to a Running Container ID
+      #   self.source #=> :id
+      #
+      # @return [Symbol] The source.
+      #
+      # @api private
+      #
+      def source
+        return @source unless @source.nil?
+        @source = %i(tag id).find { |from| options.key?(from) }
+      end
+
+      #
+      # Generates a description from Docker tag name.
+      #
+      # @example
+      #   self.description_from_tag('debian') #=> "debian"
+      #   self.description_from_tag('92cc98ab560a92cc98ab560[...]')
+      #     #=> "92cc98ab560a"
+      #
+      # @return [String] The description, shortened if necessary.
+      #
+      # @see Dockerspec::Helper::MultipleSourceDescription
+      #   #description_from_docker
+      #
+      # @api private
+      #
+      alias description_from_tag description_from_docker
+
+      #
+      # Ensures that the passed options are correct.
+      #
+      # Currently this only checks that you passed the `:tag` or the `:id`
+      # argument.
+      #
+      # @return void
+      #
+      # @raise [Dockerspec::DockerRunArgumentError] Raises this exception when
+      #   the required fields are missing.
+      #
+      # @api private
+      #
+      def assert_options!(opts)
+        return if opts[:tag].is_a?(String) || opts[:id].is_a?(String)
+        raise DockerRunArgumentError, 'You need to pass the `:tag` or the '\
+          '`:id` option to the #docker_run method.'
+      end
+
+      #
+      # Generates the build object from the Docker image tag.
+      #
+      # Saves the build internally.
+      #
+      # @param tag [String] The image name or ID.
+      #
+      # @return void
+      #
+      # @api private
+      #
+      def setup_from_tag(tag)
+        @build = Builder.new(id: tag).build
+      end
+
+      #
+      # Generates the container object from a running Docker container.
+      #
+      # Saves the container internally.
+      #
+      # @param id [String] The container ID or name.
+      #
+      # @return void
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @api private
+      #
+      def setup_from_id(id)
+        @container = ::Docker::Container.get(id)
+      rescue ::Docker::Error::DockerError => e
+        DockerExceptionParser.new(e)
+      end
+
+      #
+      # Ensures that the Docker container has a correct `CMD`.
+      #
+      # @param opts [Hash] {Docker::Container} options.
+      #
+      # @return [Hash] {Docker::Container} options.
+      #
+      # @api private
+      #
+      def add_container_cmd_option(opts)
+        opts['Cmd'] = %w(/bin/sh) if @build.cmd.nil?
+        opts
+      end
+
+      #
+      # Adds some `ENV` options to the Docker container.
+      #
+      # @param opts [Hash] {Docker::Container} options.
+      #
+      # @return [Hash] {Docker::Container} options.
+      #
+      # @api private
+      #
+      def add_container_env_options(opts)
+        opts['Env'] = opts['Env'].to_a << "PATH=#{path}" if options.key?(:path)
+        env = options[:env].to_a.map { |v| v.join('=') }
+        opts['Env'] = opts['Env'].to_a.concat(env)
+        opts
+      end
+
+      #
+      # Generates the Docker container options for {Docker::Container}.
+      #
+      # @return [Hash] The container options.
+      #
+      # @api private
+      #
+      def container_options
+        opts = { 'Image' => image_id, 'OpenStdin' => true }
+
+        add_container_cmd_option(opts)
+        add_container_env_options(opts)
+        opts
+      end
+
+      #
+      # Creates the Docker container.
+      #
+      # *Note: Based on Specinfra `:docker` backend code.*
+      #
+      # @return void
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @api private
+      #
+      def create_container
+        return @container unless @container.nil?
+        @container = ::Docker::Container.create(container_options)
+      rescue ::Docker::Error::DockerError => e
+        DockerExceptionParser.new(e)
+      end
+
+      #
+      # Creates and runs the Docker container.
+      #
+      # @return void
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @api private
+      #
+      def run_container
+        create_container
+        super
+      end
+    end
+  end
+end

data/lib/dockerspec/runner/serverspec.rb

@@ -0,0 +1,21 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015-2016 Xabier de Zuazo
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'dockerspec/runner/serverspec/docker'
+require 'dockerspec/runner/serverspec/compose'

data/lib/dockerspec/runner/serverspec/base.rb

@@ -0,0 +1,185 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015-2016 Xabier de Zuazo
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'serverspec'
+require 'dockerspec/runner/docker'
+require 'dockerspec/helper/docker'
+require 'dockerspec/docker_exception_parser'
+require 'dockerspec/runner/serverspec/rspec'
+
+#
+# Silence error: No backend type is specified. Fall back to :exec type.
+#
+Specinfra.configuration.backend(:base)
+
+module Dockerspec
+  module Runner
+    #
+    # Contains the classes used to start docker containers using Serverspec.
+    #
+    module Serverspec
+      #
+      # Base class to be included by Serverspec runners.
+      #
+      # @example
+      #   module Dockerspec
+      #     module Runner
+      #       module Serverspec
+      #         class MyRunner
+      #           include Base
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      module Base
+        #
+        # The Specinfra backend name to use.
+        #
+        # @return [Symbol] The backend name.
+        #
+        attr_reader :backend_name
+
+        #
+        # Stops and deletes the Docker Container.
+        #
+        # Actually does nothing. Do no delete anything, lets Specinfra do that.
+        #
+        # @return void
+        #
+        # @api public
+        #
+        def finalize
+          # Do not stop the container
+        end
+
+        #
+        # Generates a description of the object.
+        #
+        # @example Running Against a Container Image Tag
+        #   self.description #=> "Serverspec on tag: \"debian\""
+        #
+        # @example Running Against a Running Container ID
+        #   self.description #=> "Serverspec on id: \"92cc98ab560a\""
+        #
+        # @return [String] The object description.
+        #
+        # @api private
+        #
+        def to_s
+          description('Serverspec on')
+        end
+
+        protected
+
+        #
+        # Gets the default options configured using `RSpec.configuration`.
+        #
+        # @example
+        #   self.rspec_options #=> { :family => :debian }
+        #
+        # @return [Hash] The configuration options.
+        #
+        # @api private
+        #
+        def rspec_options
+          config = ::RSpec.configuration
+          super.tap do |opts|
+            opts[:family] = config.family if config.family?
+          end
+        end
+
+        #
+        # Generates the correct Specinfra backend name to use from a name.
+        #
+        # @example
+        #   self.generate_docker_backend_name(:docker, :docker) #=> :docker
+        #   self.generate_docker_backend_name(:lxc, :docker) #=> :docker_lxc
+        #   self.generate_docker_backend_name(:docker_lxc, :docker)
+        #     #=> :docker_lxc
+        #   self.generate_docker_backend_name(:native, :docker) #=> :docker
+        #
+        # @param name [String, Symbol] The backend short (without the `docker`
+        #   prefix) or long name.
+        # @param prefix [Symbol, String] The prefix to use: `:docker` or
+        #   `:docker_compose`.
+        #
+        # @return [Symbol] The backend name.
+        #
+        # @api private
+        #
+        def generate_docker_backend_name(name, prefix)
+          return name.to_s.to_sym if name.to_s.start_with?(prefix)
+          return prefix.to_sym if name.to_s.to_sym == :native
+          "#{prefix}_#{name}".to_sym
+        end
+
+        #
+        # Calculates and saves the correct docker Specinfra backend to use on
+        # the system.
+        #
+        # Returns the LXC driver instead of the native driver when required.
+        #
+        # Reads the driver from the configuration options if set.
+        #
+        # @example Docker with Native Execution Driver
+        #   self.calculate_docker_backend_name(:docker) #=> :docker
+        #
+        # @example Docker with LXC Execution Driver
+        #   self.calculate_docker_backend_name(:docker) #=> :docker_lxc
+        #
+        # @example Compose with LXC Execution Driver
+        #   self.calculate_docker_backend_name(:compose) #=> :docker_compose_lxc
+        #
+        # @param prefix [Symbol, String] The prefix to use: `:docker` or
+        #   `:docker_compose`.
+        #
+        # @return [Symbol] The backend name.
+        #
+        # @api private
+        #
+        def calculate_docker_backend_name(prefix)
+          @backend_name =
+            if options.key?(:backend)
+              generate_docker_backend_name(options[:backend], prefix)
+            elsif Helper::Docker.lxc_execution_driver?
+              "#{prefix}_lxc".to_sym
+            else
+              prefix.to_sym
+            end
+        end
+
+        #
+        # Starts the Docker container.
+        #
+        # @return void
+        #
+        # @raise [Dockerspec::DockerError] For underlaying docker errors.
+        #
+        # @api private
+        #
+        def run_container
+          Specinfra.configuration.backend(@backend_name)
+        rescue ::Docker::Error::DockerError => e
+          DockerExceptionParser.new(e)
+        end
+      end
+    end
+  end
+end