dockerspec 0.2.0 → 0.3.0

data/lib/dockerspec/{serverspec/specinfra_hack.rb → engine/specinfra/backend_hack.rb}

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@zuazo.org>)
-# Copyright:: Copyright (c) 2015 Xabier de Zuazo
+# Copyright:: Copyright (c) 2015-2016 Xabier de Zuazo
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,7 +23,7 @@ require 'specinfra/backend/base'
 # Add a method to the {Specinfra::Backend::Base} singleton class to set its
 # internal backend.
 #
-# TODO: This hack makes me want to poke my own eyes out.
+# This hack makes me want to poke my own eyes out :-(
 #
 Specinfra::Backend::Base.class_eval do
   #
@@ -37,7 +37,21 @@ Specinfra::Backend::Base.class_eval do
   #
   def self.instance_set(instance)
     return if @instance == instance
-    property[:host_inventory] = property[:os] = nil
+    host_reset
     @instance = instance
   end
+
+  #
+  # Resets the information stored for a host.
+  #
+  # - Host inventory.
+  # - Detected OS.
+  #
+  # @return void
+  #
+  # @api public
+  #
+  def self.host_reset
+    property[:host_inventory] = property[:os] = nil
+  end
 end

data/lib/dockerspec/engine_list.rb

@@ -0,0 +1,150 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 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/configuration'
+require 'dockerspec/exceptions'
+
+module Dockerspec
+  #
+  # Manages the list of testing engines to use.
+  #
+  class EngineList
+    #
+    # A message with description on how to avoid the error when you forget
+    # specifying the testing engine you want to use.
+    #
+    NO_ENGINES_MESSAGE = <<-EOE
+
+Remember to include the Test Engine you want to use.
+
+For example, to use Serverspec:
+
+    require 'dockerspec/serverspec'
+
+    EOE
+                         .freeze
+
+    #
+    # Constructs the list of engines.
+    #
+    # Initializes all the selected engines.
+    #
+    # @param runner [Dockerspec::Runner::Base] The class used to run the
+    #   docker container.
+    #
+    # @return [Dockerspec::EngineList] The list of engines.
+    #
+    # @raise [Dockerspec::EngineError] Raises this exception when the engine
+    #   list is empty.
+    #
+    # @api public
+    #
+    def initialize(runner)
+      engine_classes = Configuration.engines
+      @engines =
+        engine_classes.map { |engine_class| engine_class.new(runner) }
+      assert_engines!
+    end
+
+    #
+    # Setups all the engines one by one.
+    #
+    # @param args [Mixed] Arguments to pass to the `#before_running` methods.
+    #
+    # @return void
+    #
+    # @api public
+    #
+    def before_running(*args)
+      call_engines_method(:before_running, *args)
+    end
+
+    #
+    # Notify the engines that the container to test is selected and ready.
+    #
+    # @param args [Mixed] Arguments to pass to the `#when_container_ready`
+    # methods.
+    #
+    # @return void
+    #
+    # @api public
+    #
+    def when_container_ready(*args)
+      call_engines_method(:when_container_ready, *args)
+    end
+
+    #
+    # Saves all the engines one by one.
+    #
+    # @param args [Mixed] Arguments to pass to the `#when_running` methods.
+    #
+    # @return void
+    #
+    # @api public
+    #
+    def when_running(*args)
+      call_engines_method(:when_running, *args)
+    end
+
+    #
+    # Restores all the engines one by one.
+    #
+    # @param args [Mixed] Arguments to pass to the `#restore` methods.
+    #
+    # @return void
+    #
+    # @api public
+    #
+    def restore(*args)
+      call_engines_method(:restore, *args)
+    end
+
+    protected
+
+    #
+    # Ensures that there has been chosen at least one engine.
+    #
+    # @return void
+    #
+    # @raise [Dockerspec::EngineError] Raises this exception when the engine
+    #   list is empty.
+    #
+    # @api private
+    #
+    def assert_engines!
+      return unless @engines.empty?
+      raise EngineError, NO_ENGINES_MESSAGE
+    end
+
+    #
+    # Runs the same method on all the engines.
+    #
+    # @param method [String, Symbol] The method to run.
+    #
+    # @param args [Mixed] Arguments to pass to the methods.
+    #
+    # @return void
+    #
+    # @api private
+    #
+    def call_engines_method(method, *args)
+      @engines.map { |engine| engine.send(method, *args) }
+    end
+  end
+end

data/lib/dockerspec/exceptions.rb

@@ -24,8 +24,21 @@ module Dockerspec
   #
   class DockerRunArgumentError < ArgumentError; end
   #
+  # An exception message raised when there are errors related to Test Engines.
+  #
+  class EngineError < ArgumentError; end
+  #
+  # An exception message raised when there are errors related to the Runner.
+  #
+  class RunnerError < ArgumentError; end
+  #
   # An exception message raised when there are errors running Docker or
   # building Docker images.
   #
   class DockerError < ArgumentError; end
+  #
+  # An exception message raised when there is an error with the `its_container`
+  # resource.
+  #
+  class ItsContainerError < ArgumentError; end
 end

data/lib/dockerspec/helper/multiple_sources_description.rb

@@ -83,14 +83,14 @@ module Dockerspec
       # @api private
       #
       def description_from_docker(str)
-        return str unless str.match(/^[0-9a-f]+$/)
+        return str unless str =~ /^[0-9a-f]+$/
         str[0..11]
       end
 
       #
       # Generates a description from Docker ID.
       #
-      alias_method :description_from_id, :description_from_docker
+      alias description_from_id description_from_docker
 
       #
       # Generates a description from string.
@@ -136,7 +136,7 @@ module Dockerspec
       #
       # @api private
       #
-      alias_method :description_from_path, :description_from_file
+      alias description_from_path description_from_file
     end
   end
 end

data/lib/dockerspec/helper/rspec_example_helpers.rb

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@zuazo.org>)
-# Copyright:: Copyright (c) 2015 Xabier de Zuazo
+# Copyright:: Copyright (c) 2015-2016 Xabier de Zuazo
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,6 +23,36 @@ module Dockerspec
     # Some Helper methods to work with RSpec Examples.
     #
     module RSpecExampleHelpers
+      #
+      # Checks if the parent RSpec example information exists in the metadata.
+      #
+      # @param metadata [Hash] RSpec metadata.
+      #
+      # @return [Boolean] Returns true if the parent metadata is available.
+      #
+      # @api private
+      #
+      def self.metadata_has_parent?(metadata)
+        metadata.key?(:parent_example_group) || metadata.key?(:example_group)
+      end
+
+      #
+      # Get the parent RSpec example metadata if available.
+      #
+      # @param metadata [Hash] RSpec metadata.
+      #
+      # @return [Hash] RSpec metadata from the parent example.
+      #
+      # @api private
+      #
+      def self.metadata_parent(metadata)
+        if metadata.key?(:parent_example_group)
+          metadata[:parent_example_group]
+        elsif metadata.key?(:example_group)
+          metadata[:example_group]
+        end
+      end
+
       #
       # Searches for an object in the description of the parent RSpec examples.
       #
@@ -34,15 +64,65 @@ module Dockerspec
       # @api public
       #
       def self.search_object(metadata, klass)
-        return metadata if metadata.nil?
+        return nil if metadata.nil?
         if metadata[:described_class].is_a?(klass)
           metadata[:described_class]
-        elsif metadata.key?(:parent_example_group)
-          search_object(metadata[:parent_example_group], klass)
-        elsif metadata.key?(:example_group)
-          search_object(metadata[:example_group], klass)
+        elsif metadata_has_parent?(metadata)
+          search_object(metadata_parent(metadata), klass)
         end
       end
+
+      #
+      # Searches for an object in the description of the parent RSpec examples
+      # that implements a specific method.
+      #
+      # @param metadata [Hash] RSpec metadata.
+      # @param meth [Symbol] The method name.
+      # @param arity [Integer] The arity of the method.
+      #
+      # @return [Array<Object>] Returns the objects list.
+      #
+      # @api public
+      #
+      def self.search_objects_with(metadata, meth, arity)
+        o_ary = []
+        return o_ary if metadata.nil?
+        if metadata[:described_class].respond_to?(meth) &&
+           metadata[:described_class].method(meth).arity == arity
+          o_ary << metadata[:described_class]
+        end
+        return o_ary unless metadata_has_parent?(metadata)
+        search_objects_with(metadata_parent(metadata), meth, arity) + o_ary
+      end
+
+      #
+      # Restores the Docker running container instance in the Specinfra
+      # internal reference.
+      #
+      # Gets the correct {Runner::Base} reference from the RSpec metadata.
+      #
+      # @example Restore Specinfra Backend
+      #   RSpec.configure do |c|
+      #     c.before(:each) do
+      #       metadata = RSpec.current_example.metadata
+      #       Dockerspec::Runner::Base.restore(metadata)
+      #     end
+      #   end
+      #
+      # @param metadata [Hash] RSpec metadata.
+      #
+      # @return void
+      #
+      # @api public
+      #
+      # @see restore
+      #
+      def self.restore_rspec_context(metadata)
+        o_ary =
+          Helper::RSpecExampleHelpers
+          .search_objects_with(metadata, :restore_rspec_context, 0)
+        o_ary.each(&:restore_rspec_context)
+      end
     end
   end
 end

data/lib/dockerspec/infrataster.rb

@@ -0,0 +1,26 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 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'
+require 'dockerspec/engine/infrataster'
+
+#
+# Use Infrataster to run the tests (engine).
+#
+Dockerspec::Configuration.add_engine Dockerspec::Engine::Infrataster

data/lib/dockerspec/rspec.rb

@@ -0,0 +1,21 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 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/rspec/resources'
+require 'dockerspec/rspec/configuration'

data/lib/dockerspec/{rspec_configuration.rb → rspec/configuration.rb}

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@zuazo.org>)
-# Copyright:: Copyright (c) 2015 Xabier de Zuazo
+# Copyright:: Copyright (c) 2015-2016 Xabier de Zuazo
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

data/lib/dockerspec/rspec/resources.rb

@@ -0,0 +1,602 @@
+# 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/configuration'
+require 'dockerspec/rspec/settings'
+require 'dockerspec/builder'
+require 'dockerspec/rspec/resources/its_container'
+require 'dockerspec/exceptions'
+
+module Dockerspec
+  #
+  # Some classes related to RSpec testing framework.
+  #
+  module RSpec
+    #
+    # Some resources included inside {RSpec::Core::ExampleGroup} to build and
+    # run Docker containers.
+    #
+    # ## Load the Test Engine You Want to Use
+    #
+    # If you want to run [Serverspec](http://serverspec.org/) tests, you need
+    # to require the `dockerspec/serverspec` path:
+    #
+    # ```ruby
+    # require 'dockerspec/serverspec'
+    # ```
+    #
+    # If you want to run [Infrataster](https://github.com/ryotarai/infrataster)
+    # tests, you need to require the `dockerspec/infrataster` path:
+    #
+    # ```ruby
+    # require 'dockerspec/infrataster'
+    # ```
+    #
+    # Of course, you can load both engines:
+    #
+    # ```ruby
+    # require 'dockerspec/serverspec'
+    # require 'dockerspec/infrataster'
+    # ```
+    #
+    # ## RSpec Settings
+    #
+    # * `dockerfile_path`: The dockerfile path.
+    # * `rm_build`: Whether to remove the build after the run.
+    # * `log_level`: Log level to use by default.
+    # * `docker_wait`: Seconds to wait before running the tests.
+    # * `container_name`: Docker container to test with Docker Compose.
+    #
+    # All the RSpec settings are optional.
+    #
+    # @example RSpec Settings
+    #   RSpec.configure do |config|
+    #     config.log_level = :silent
+    #   end
+    #
+    module Resources
+      #
+      # Builds a Docker image.
+      #
+      # The image can be build from a path or from a string.
+      #
+      # See the {Dockerspec::Builder::ConfigHelpers} documentation for more
+      # information about the available RSpec resource helpers.
+      #
+      # @example A Simple Example
+      #   describe 'My Dockerfile' do
+      #     describe docker_build('.') do
+      #       it { should have_maintainer /John Doe/ }
+      #       it { should have_cmd ['/bin/dash'] }
+      #       it { should have_expose '80' }
+      #     end
+      #   end
+      #
+      # @example A Complete Example
+      #   describe docker_build(path: '.') do
+      #     it { should have_maintainer 'John Doe "john.doe@example.com"' }
+      #     it { should have_maintainer(/John Doe/) }
+      #     it { should have_cmd %w(2 2000) }
+      #     it { should have_label 'description' }
+      #     it { should have_label 'description' => 'My Container' }
+      #     it { should have_expose '80' }
+      #     it { should have_expose(/80$/) }
+      #     it { should have_env 'container' }
+      #     it { should have_env 'container' => 'docker' }
+      #     it { should have_env 'PATH' => '/tmp/bin:/sbin:/bin' }
+      #     it { should have_entrypoint ['sleep'] }
+      #     it { should have_volume '/volume1' }
+      #     it { should have_volume %r{/vol.*2} }
+      #     it { should have_user 'nobody' }
+      #     it { should have_workdir '/opt' }
+      #     it { should have_workdir %r{^/op} }
+      #     it { should have_onbuild 'RUN echo onbuild' }
+      #     it { should have_stopsignal 'SIGTERM' }
+      #   end
+      #
+      # @example Checking the Attribute Values Using the `its` Method
+      #   describe docker_build(path: '.') do
+      #     its(:maintainer) { should eq 'John Doe "john.doe@example.com"' }
+      #     its(:cmd) { should eq %w(2 2000) }
+      #     its(:labels) { should include 'description' }
+      #     its(:labels) { should include 'description' => 'My Container' }
+      #     its(:exposes) { should include '80' }
+      #     its(:env) { should include 'container' }
+      #     its(:env) { should include 'container' => 'docker' }
+      #     its(:entrypoint) { should eq ['sleep'] }
+      #     its(:volumes) { should include '/volume1' }
+      #     its(:user) { should eq 'nobody' }
+      #     its(:workdir) { should eq '/opt' }
+      #     its(:onbuilds) { should include 'RUN echo onbuild' }
+      #     its(:stopsignal) { should eq 'SIGTERM' }
+      #   end
+      #
+      # @example Checking Its Size and OS
+      #   describe docker_build(path: '.') do
+      #     its(:size) { should be < 20 * 2**20 } # 20M
+      #     its(:arch) { should eq 'amd64' }
+      #     its(:os) { should eq 'linux' }
+      #   end
+      #
+      # @example Building from a File
+      #   describe docker_build(path: '../dockerfiles/Dockerfile-nginx') do
+      #     # [...]
+      #   end
+      #
+      # @example Building from a Template
+      #   describe docker_build(template: 'Dockerfile1.erb') do
+      #     # [...]
+      #   end
+      #
+      # @example Building from a Template with a Context
+      #   describe docker_build(
+      #     template: 'Dockerfile1.erb', context: {version: '8'}
+      #   ) do
+      #     it { should have_maintainer(/John Doe/) }
+      #     it { should have_cmd %w(/bin/sh) }
+      #     # [...]
+      #   end
+      #
+      # @example Building from a String
+      #   describe docker_build(string: "FROM nginx:1.9\n [...]") do
+      #     # [...]
+      #   end
+      #
+      # @example Building from a Docker Image ID
+      #   describe docker_build(id: '07d362aea98d') do
+      #     # [...]
+      #   end
+      #
+      # @example Building from a Docker Image Name
+      #   describe docker_build(id: 'nginx:1.9') do
+      #     # [...]
+      #   end
+      #
+      # @param opts [String, Hash] The `:path` or a list of options.
+      #
+      # @option opts [String] :path ('.') The directory or file that contains
+      #   the *Dockerfile*. By default tries to read it from the
+      #   `DOCKERFILE_PATH` environment variable and uses `'.'` if it is not
+      #   set.
+      # @option opts [String] :string Use this string as *Dockerfile* instead of
+      #   `:path`. Not set by default.
+      # @option opts [String] :template Use this [Erubis]
+      #   (http://www.kuwata-lab.com/erubis/users-guide.html) template file as
+      #   *Dockerfile*.
+      # @option opts [String] :id Use this Docker image ID instead of a
+      #   *Dockerfile*.
+      # @option opts [Boolean] :rm Whether to remove the generated docker images
+      #   after running the tests. By default only removes them if it is running
+      #   on a CI machine.
+      # @option opts [Hash, Erubis::Context] :context ({}) Template *context*
+      #   used when the `:template` source is used.
+      # @option opts [String] :tag Repository tag to be applied to the resulting
+      #   image.
+      # @option opts [Fixnum, Symbol] :log_level Sets the docker library
+      #   verbosity level. Possible values:
+      #    `:silent` or `0` (no output),
+      #    `:ci` or `1` (enables some outputs recommended for CI environments),
+      #    `:info` or `2` (gives information about main build steps),
+      #    `:debug` or `3` (outputs all the provided information in its raw
+      #      original form).
+      #
+      # @return [Dockerspec::Builder] Builder object.
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @see Dockerspec::Builder::ConfigHelpers
+      #
+      # @api public
+      #
+      def docker_build(*opts)
+        builder = Dockerspec::Builder.new(*opts)
+        builder.build
+        described_image(builder.id)
+        builder
+      end
+
+      #
+      # Runs a docker image.
+      #
+      # See the [Serverspec Resource Types documentation]
+      # (http://serverspec.org/resource_types.html) to see the available
+      # resources.
+      #
+      # By default tries to detect the most appropriate Docker backend: native
+      # or LXC.
+      #
+      # @example A Basic Example to Test the HTTPd Service
+      #   describe docker_build('.', tag: 'myapp') do
+      #     describe docker_run('myapp') do
+      #       describe service('httpd') do
+      #         it { should be_enabled }
+      #         it { should be_running }
+      #       end
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Avoid Automatic OS Detection to Speed Up the Tests
+      #   describe docker_build('.', tag: 'myapp') do
+      #     describe docker_run('myapp', family: 'debian') do
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Using Hash Format
+      #   describe docker_build('.', tag: 'myapp') do
+      #     describe docker_run(tag: 'myapp', family: 'debian') do
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Force a Specific Docker Backend
+      #   describe docker_build('.', tag: 'myapp') do
+      #     describe docker_run('myapp', backend: :lxc) do
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Use a Backend Not Included by Default
+      #   # specinfra-backend-docker_nsenter gem must be installed by hand
+      #   require 'specinfra/backend/docker_nsenter'
+      #   describe docker_build('.', tag: 'myapp') do
+      #     describe docker_run('myapp', backend: :nsenter) do
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Running a Container Image Tag
+      #   describe docker_run('debian:8') do
+      #     # [...]
+      #   end
+      #
+      # @example Testing `FROM` Dockerfile Instruction
+      #   # FROM debian:8
+      #   describe docker_run('myapp') do
+      #     describe file('/etc/debian_version') do
+      #       it { should be_file }
+      #       its(:content) { should match /^8\./ }
+      #     end
+      #     # Another way to check it:
+      #     describe command('lsb_release -ri') do
+      #       its(:stdout) { should match /^Distributor ID:\s+Debian/ }
+      #       its(:stdout) { should match /^Release:\s+8\./ }
+      #     end
+      #   end
+      #
+      # @example Testing `COPY` and `ADD` Dockerfile Instructions
+      #   # COPY docker-entrypoint.sh /entrypoint.sh
+      #   describe docker_run('myapp') do
+      #     describe file('/entrypoint.sh') do
+      #       it { should be_file }
+      #       its(:content) { should match /^exec java -jar myapp\.jar/ }
+      #     end
+      #   end
+      #
+      # @example Testing `RUN` Dockerfile Instructions
+      #   describe docker_run('myapp') do
+      #     # RUN apt-get install -y wget
+      #     describe package('wget') do
+      #       it { should be_installed }
+      #     end
+      #     # RUN useradd -g myapp -d /opt/myapp myapp
+      #     describe user('myapp') do
+      #       it { should exist }
+      #       it { should belong_to_group 'myapp' }
+      #       it { should have_home_directory '/opt/myapp' }
+      #     end
+      #   end
+      #
+      # @example Testing with Infrataster
+      #   require 'dockerspec/infrataster'
+      #   describe docker_run('nginx') do
+      #     describe server(described_container) do
+      #       describe http('/') do
+      #         it 'responds content including "Welcome to nginx!"' do
+      #           expect(response.body).to include 'Welcome to nginx!'
+      #         end
+      #         it 'responds as "nginx" server' do
+      #           expect(response.headers['server']).to match(/nginx/i)
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @param opts [String, Hash] The `:tag` or a list of options. This
+      #   configuration options will be passed to the Testing Engines like
+      #   Infrataster. So you can include your Infrataster server configuration
+      #   here.
+      #
+      # @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 [Symbol, String] :family (calculated) The OS family.
+      #   It's automatically detected by default, but can be used to
+      #   **speed up the tests**. Some possible values:
+      #   `:alpine`, `:arch`, `:coreos`, `:debian`, `:gentoo`, `:nixos`,
+      #   `:plamo`, `:poky`, `:redhat`, `:suse`.
+      # @option opts [Symbol] :backend (calculated) Docker backend to use:
+      #   `:docker`, `:lxc`.
+      #
+      # @return [Dockerspec::Runner::Docker] Runner object.
+      #
+      # @raise [Dockerspec::DockerRunArgumentError] Raises this exception when
+      #   some required fields are missing.
+      #
+      # @raise [Dockerspec::EngineError] Raises this exception when the engine
+      #   list is empty.
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @api public
+      #
+      def docker_run(*opts)
+        runner = Dockerspec::Configuration.docker_runner.new(*opts)
+        runner.run
+        described_container(runner.container_name)
+        runner
+      end
+
+      #
+      # Runs Docker Compose.
+      #
+      # By default tries to detect the most appropriate Docker backend: native
+      # or LXC.
+      #
+      # @example Testing Containers from a YAML File
+      #   describe docker_compose('docker-compose.yml', wait: 15) do
+      #     its_container(:myapp) do
+      #       describe process('apache2') do
+      #         it { should be_running }
+      #       end
+      #       # [...]
+      #     end
+      #     its_container(:db) do
+      #       describe process('mysqld') do
+      #         it { should be_running }
+      #       end
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Testing Only One Container from a Directory
+      #   describe docker_compose('data/', container: :myapp, wait: 15) do
+      #     describe process('apache2') do
+      #       it { should be_running }
+      #     end
+      #     # [...]
+      #   end
+      #
+      # @example Avoid Automatic OS Detection to Speed Up the Tests
+      #   describe docker_compose(
+      #     'data/', container: :myapp, family: 'debian', wait: 15
+      #   ) do
+      #     describe process('apache2') do
+      #       it { should be_running }
+      #     end
+      #     # [...]
+      #   end
+      #
+      # @param opts [String, Hash] The `:file` or a list of options.
+      #
+      # @option opts [String] :file The compose YAML file or a directory
+      #   containing the `'docker-compose.yml'` file.
+      # @option opts [Symbol, String] :container The name of the container to
+      #   test. It is better to use
+      #   {Dockerspec::RSpec::Resources#its_container} if you want to test
+      #   multiple containers.
+      # @option opts [Boolean] :rm (calculated) Whether to remove the Docker
+      #   containers afterwards.
+      # @option opts [Symbol, String] :family (calculated) The OS family.
+      #   It's automatically detected by default, but can be used to
+      #   **speed up the tests**. Some possible values:
+      #   `:alpine`, `:arch`, `:coreos`, `:debian`, `:gentoo`, `:nixos`,
+      #   `:plamo`, `:poky`, `:redhat`, `:suse`.
+      # @option opts [Symbol] :backend (calculated) Docker backend to use:
+      #   `:docker_compose`, `:docker_compose_lxc`.
+      #
+      # @return [Dockerspec::Runner::Compose] Runner object.
+      #
+      # @raise [Dockerspec::DockerRunArgumentError] Raises this exception when
+      #   some required fields are missing.
+      #
+      # @raise [Dockerspec::EngineError] Raises this exception when the engine
+      #   list is empty.
+      #
+      # @raise [Dockerspec::DockerError] For underlaying docker errors.
+      #
+      # @api public
+      #
+      def docker_compose(*opts)
+        runner = Dockerspec::Configuration.compose_runner.new(*opts)
+        runner.run
+      end
+
+      #
+      # Selects the container to test inside {#docker_compose}.
+      #
+      # @example Testing Multiple Containers
+      #   describe docker_compose('docker-compose.yml', wait: 15) do
+      #     its_container(:myapp) do
+      #       describe process('apache2') do
+      #         it { should be_running }
+      #         its(:args) { should match(/-DFOREGROUND/) }
+      #       end
+      #       # [...]
+      #     end
+      #     its_container(:db) do
+      #       describe process('mysqld') do
+      #         it { should be_running }
+      #       end
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Avoid Automatic OS Detection to Speed Up the Tests
+      #   describe docker_compose('docker-compose.yml', wait: 15) do
+      #     its_container('myapp', family: 'centos') do
+      #       describe process('httpd') do
+      #         it { should be_running }
+      #       end
+      #       # [...]
+      #     end
+      #     its_container('db', family: 'debian') do
+      #       describe process('mysqld') do
+      #         it { should be_running }
+      #       end
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @example Testing a Database with Infrataster using Docker Compose
+      #   require 'dockerspec/infrataster'
+      #   # After including `gem 'infrataster-plugin-mysql'` in your Gemfile:
+      #   require 'infrataster-plugin-mysql'
+      #   describe docker_compose('docker-compose.yml', wait: 60) do
+      #     its_container(:db, mysql: { user: 'root', password: 'example' }) do
+      #       describe server(described_container) do
+      #         describe mysql_query('SHOW STATUS') do
+      #           it 'returns positive uptime' do
+      #             row = results.find { |r| r['Variable_name'] == 'Uptime' }
+      #             expect(row['Value'].to_i).to be > 0
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @param container [Symbol, String] The name of the container to test.
+      #
+      # @param opts [Hash] A list of options. This configuration options will
+      #   be passed to the Testing Engines like Infrataster. So you can include
+      #   your Infrataster server configuration here.
+      #
+      # @option opts [Symbol, String] :family (calculated) The OS family.
+      #   It's automatically detected by default, but can be used to
+      #   **speed up the tests**. Some possible values:
+      #   `:alpine`, `:arch`, `:coreos`, `:debian`, `:gentoo`, `:nixos`,
+      #   `:plamo`, `:poky`, `:redhat`, `:suse`.
+      #
+      # @return [Dockerspec::Runner::Compose] Runner object.
+      #
+      # @raise [Dockerspec::DockerComposeError] Raises this exception when
+      #   you call `its_container` without calling `docker_compose`.
+      #
+      # @api public
+      #
+      def its_container(container, *opts, &block)
+        compose = Runner::Compose.current_instance
+        if compose.nil?
+          raise ItsContainerError, ItsContainer::NO_DOCKER_COMPOSE_MESSAGE
+        end
+        container_opts = opts[0].is_a?(Hash) ? opts[0] : {}
+        compose.select_container(container, container_opts)
+        described_container(compose.container_name)
+        describe(ItsContainer.new(container), *opts, &block)
+      end
+
+      #
+      # Sets or gets the latest run container name.
+      #
+      # This can be used to avoid adding a tag to the build image.
+      #
+      # @example
+      #   describe docker_build('.') do
+      #     describe docker_run(described_image, family: 'debian') do
+      #       # [...]
+      #     end
+      #   end
+      #
+      # @param value [String] The docker image id.
+      #
+      # @return [String] The docker image id.
+      #
+      # @api public
+      #
+      def described_image(value = nil)
+        # rubocop:disable Style/ClassVars
+        @@described_image = value unless value.nil?
+        # rubocop:enable Style/ClassVars
+        @@described_image
+      end
+
+      #
+      # Sets or gets the latest run container name.
+      #
+      # Used to call the Infrataster {#server} method.
+      #
+      # @example Testing a Docker Container
+      #   describe docker_run('myapp') do
+      #     describe server(described_container) do
+      #       describe http('/') do
+      #         it 'responds content including "My App Homepage"' do
+      #           expect(response.body).to match(/My App Homepage/i)
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @example Testing with Docker Compose
+      #   describe docker_compose('docker-compose.yml', wait: 60) do
+      #     its_container(:wordpress) do
+      #       describe server(described_container) do
+      #         describe http('/wp-admin/install.php') do
+      #           it 'responds content including "Wordpress Installation"' do
+      #             expect(response.body).to match(/WordPress .* Installation/i)
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @param value [Symbol, String] The container name.
+      #
+      # @return [Symbol] The container name.
+      #
+      # @api public
+      #
+      def described_container(value = nil)
+        # rubocop:disable Style/ClassVars
+        @@described_container = value unless value.nil?
+        # rubocop:enable Style/ClassVars
+        @@described_container.to_sym
+      end
+    end
+  end
+end
+
+#
+# Add the Dockerspec resources to RSpec core.
+#
+RSpec::Core::ExampleGroup.class_eval do
+  extend Dockerspec::RSpec::Resources
+  include Dockerspec::RSpec::Resources
+end
+
+#
+# Allow using #docker_build in the outermost example
+#
+extend Dockerspec::RSpec::Resources