class Dockerspec::Runner::Base

A basic class with the minimal skeleton to create a Runner: Classes to start docker containers.

Constants

OPTIONS_DEFAULT_KEY

The option key to set when you pass a string instead of a hash of options.

Attributes

options[R]

Gets the configuration options.

@return [Hash] The options.

@api private

Public Class Methods

new(*opts) click to toggle source

Constructs a runner class to run Docker images.

@param opts [String, Hash] The id/name/file or a list of options.

@option opts [Boolean] :rm (calculated) Whether to remove the Docker

container afterwards.

@option opts [Integer] :wait Time to wait before running the tests.

@return [Dockerspec::Runner::Base] Runner object.

@raise [Dockerspec::EngineError] Raises this exception when the engine

list is empty.

@api public

# File lib/dockerspec/runner/base.rb, line 65
def initialize(*opts)
  @options = parse_options(opts)
  @engines = EngineList.new(self)
  ObjectSpace.define_finalizer(self, proc { finalize })
end

Public Instance Methods

container() click to toggle source

Gets the internal {Docker::Container} object.

@return [Docker::Container] The container.

@raise [Dockerspec::RunnerError] When the method is no implemented in

the subclass.

@api public

# File lib/dockerspec/runner/base.rb, line 126
def container
  raise RunnerError, "#{self.class}#container method must be implemented"
end
container_name() click to toggle source

Gets the container name.

@return [String] Container name.

@raise [Dockerspec::RunnerError] When the `#container` method is no

implemented in the subclass or cannot select the container to test.

@api public

# File lib/dockerspec/runner/base.rb, line 140
def container_name
  container.json['Name']
end
finalize() click to toggle source

Stops and deletes the Docker Container.

Automatically called when `:rm` option is enabled.

@return void

@api public

# File lib/dockerspec/runner/base.rb, line 203
def finalize
  return if options[:rm] == false || container.nil?
  container.stop
  container.delete
end
id() click to toggle source

Gets the Docker container ID.

@example

builder = Dockerspec::Builder.new('.').build
runner = Dockerspec::Runner::Base.new(builder).run
runner.id #=> "b8ba0befc716[...]"

@return [String] Container ID.

@raise [Dockerspec::RunnerError] When the `#container` method is no

implemented in the subclass or cannot select the container to test.

@api public

# File lib/dockerspec/runner/base.rb, line 159
def id
  return nil unless container.respond_to?(:id)
  container.id
end
image_id() click to toggle source

Gets the Docker image ID.

@return [String] Image ID.

@raise [Dockerspec::RunnerError] When the `#container` method is no

implemented in the subclass or cannot select the container to test.

@api public

# File lib/dockerspec/runner/base.rb, line 174
def image_id
  container.json['Image']
end
ipaddress() click to toggle source

Gets the Docker Container IP address.

This is used by {Dockerspec::Engine::Infrataster}.

@return [String] IP address.

@raise [Dockerspec::RunnerError] When the `#container` method is no

implemented in the subclass or cannot select the container to test.

@api public

# File lib/dockerspec/runner/base.rb, line 190
def ipaddress
  container.json['NetworkSettings']['IPAddress']
end
restore_rspec_context() click to toggle source

Restores the Specinfra backend instance to point to this object's container.

This is used to avoid Serverspec running against the last started container if you are testing multiple containers at the same time.

@return void

# File lib/dockerspec/runner/base.rb, line 112
def restore_rspec_context
  @engines.restore
end
run() click to toggle source

Runs the Docker Container.

  1. Sets up the test context.

  2. Runs the container (or Compose).

  3. Saves the created underlaying test context.

  4. Sets the container as ready.

  5. Waits the required (configured) time after container has been started.

@example

builder = Dockerspec::Builder.new('.')
builder.build
runner = Dockerspec::Runner::Base.new(builder)
runner.run #=> #<Dockerspec::Runner::Base:0x0123>

@return [Dockerspec::Runner::Base] Runner object.

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

@api public

# File lib/dockerspec/runner/base.rb, line 93
def run
  before_running
  start_time = Time.new.utc
  run_container
  when_running
  when_container_ready
  do_wait((Time.new.utc - start_time).to_i)
  self
end

Protected Instance Methods

assert_options!(opts) click to toggle source

Ensures that the passed options are correct.

Does nothing. Must be implemented in subclasses.

@return void

@api private

# File lib/dockerspec/runner/base.rb, line 297
def assert_options!(opts); end
before_running() click to toggle source

Sets up the context just before starting the docker container.

@return void

@api public

# File lib/dockerspec/runner/base.rb, line 218
def before_running
  @engines.before_running
end
default_options() click to toggle source

Gets the default configuration options after merging them with RSpec configuration options.

@example

self.default_options #=> {}

@return [Hash] The configuration options.

@api private

# File lib/dockerspec/runner/base.rb, line 284
def default_options
  {}.merge(rspec_options)
end
do_wait(waited) click to toggle source

Sleeps for some time if required.

Reads the seconds to sleep from the `:docker_wait` or `:wait` configuration option.

@param waited [Integer] The time already waited.

@return nil

@api private

# File lib/dockerspec/runner/base.rb, line 352
def do_wait(waited)
  wait = options[:wait]
  return unless wait.is_a?(Integer) || wait.is_a?(Float)
  return if waited >= wait
  sleep(wait - waited)
end
options_default_key() click to toggle source

The option key to set when you pass a string instead of a hash of options.

@return [Symbol] The key name.

@api private

# File lib/dockerspec/runner/base.rb, line 269
def options_default_key
  self.class::OPTIONS_DEFAULT_KEY
end
parse_options(opts) click to toggle source

Parses the configuration options passed to the constructor.

@example

self.parse_options #=> {:rm=>true, :file=> "docker-compose.yml"}

@param opts [Array<String, Hash>] The list of options. The strings will

be interpreted as `default_opt` key value, others will be merged.

@return [Hash] The configuration options.

@raise [Dockerspec::DockerRunArgumentError] Raises this exception when

some required fields are missing.

@see initialize

@api private

# File lib/dockerspec/runner/base.rb, line 317
def parse_options(opts)
  opts_hs_ary = opts.map do |x|
    x.is_a?(Hash) ? x : { options_default_key => x }
  end
  result = opts_hs_ary.reduce(default_options) { |a, e| a.merge(e) }
  assert_options!(result)
  result
end
rspec_options() click to toggle source

Gets the default options configured using `RSpec.configuration`.

@example

self.rspec_options #=> {}

@return [Hash] The configuration options.

@api private

# File lib/dockerspec/runner/base.rb, line 254
def rspec_options
  config = ::RSpec.configuration
  {}.tap do |opts|
    opts[:wait] = config.docker_wait if config.docker_wait?
  end
end
run_container() click to toggle source

Starts the Docker container.

@return void

@raise [Dockerspec::RunnerError] When the `#container` method is no

implemented in the subclass.

@api private

# File lib/dockerspec/runner/base.rb, line 336
def run_container
  container.start
end
when_container_ready() click to toggle source

Notifies the engines that the container to test is selected and ready.

@return void

@api public

# File lib/dockerspec/runner/base.rb, line 240
def when_container_ready
  @engines.when_container_ready
end
when_running() click to toggle source

Saves the context after starting the docker container.

@return void

@api public

# File lib/dockerspec/runner/base.rb, line 229
def when_running
  @engines.when_running
end