class Dockerspec::Runner::Docker

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.

Constants

OPTIONS_DEFAULT_KEY

@return [Symbol] The option key to set when you pass a string instead

of a hash of options.

Attributes

container[R]

The internal {Docker::Container} object.

@return [Docker::Container] The container.

Public Class Methods

new(*opts) click to toggle source

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

Calls superclass method Dockerspec::Runner::Base::new
# File lib/dockerspec/runner/docker.rb, line 91
def initialize(*opts)
  super
  send("setup_from_#{source}", options[source])
end

Public Instance Methods

image_id() click to toggle source

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

Calls superclass method Dockerspec::Runner::Base#image_id
# File lib/dockerspec/runner/docker.rb, line 108
def image_id
  return @build.id unless @build.nil?
  super
end
to_s() click to toggle source

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

# File lib/dockerspec/runner/docker.rb, line 128
def to_s
  description('Docker Run from')
end

Protected Instance Methods

add_container_cmd_option(opts) click to toggle source

Ensures that the Docker container has a correct `CMD`.

@param opts [Hash] {Docker::Container} options.

@return [Hash] {Docker::Container} options.

@api private

# File lib/dockerspec/runner/docker.rb, line 233
def add_container_cmd_option(opts)
  opts['Cmd'] = %w(/bin/sh) if @build.cmd.nil?
  opts
end
add_container_env_options(opts) click to toggle source

Adds some `ENV` options to the Docker container.

@param opts [Hash] {Docker::Container} options.

@return [Hash] {Docker::Container} options.

@api private

# File lib/dockerspec/runner/docker.rb, line 247
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
assert_options!(opts) click to toggle source

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

# File lib/dockerspec/runner/docker.rb, line 184
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
container_options() click to toggle source

Generates the Docker container options for {Docker::Container}.

@return [Hash] The container options.

@api private

# File lib/dockerspec/runner/docker.rb, line 261
def container_options
  opts = { 'Image' => image_id, 'OpenStdin' => true }

  add_container_cmd_option(opts)
  add_container_env_options(opts)
  opts
end
create_container() click to toggle source

Creates the Docker container.

*Note: Based on Specinfra `:docker` backend code.*

@return void

@raise [Dockerspec::DockerError] For underlaying docker errors.

@api private

# File lib/dockerspec/runner/docker.rb, line 280
def create_container
  return @container unless @container.nil?
  @container = ::Docker::Container.create(container_options)
rescue ::Docker::Error::DockerError => e
  DockerExceptionParser.new(e)
end
run_container() click to toggle source

Creates and runs the Docker container.

@return void

@raise [Dockerspec::DockerError] For underlaying docker errors.

@api private

Calls superclass method Dockerspec::Runner::Base#run_container
# File lib/dockerspec/runner/docker.rb, line 296
def run_container
  create_container
  super
end
setup_from_id(id) click to toggle source

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

# File lib/dockerspec/runner/docker.rb, line 218
def setup_from_id(id)
  @container = ::Docker::Container.get(id)
rescue ::Docker::Error::DockerError => e
  DockerExceptionParser.new(e)
end
setup_from_tag(tag) click to toggle source

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

# File lib/dockerspec/runner/docker.rb, line 201
def setup_from_tag(tag)
  @build = Builder.new(id: tag).build
end
source() click to toggle source

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

# File lib/dockerspec/runner/docker.rb, line 149
def source
  return @source unless @source.nil?
  @source = %i(tag id).find { |from| options.key?(from) }
end