dockerspec 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a39571e9f5eb647131860a8950bce41592c9887c
-  data.tar.gz: f61ee33d8d382ec51859aa15ea296cbf64acaf64
+  metadata.gz: 7694cecd69e554a6954f6b9db00f3fe2b768f15c
+  data.tar.gz: 1a2a4415286128639366c18f8ab4f6d303d416c0
 SHA512:
-  metadata.gz: 9a4e57c561111f07730b533ff1e43514c19a6f6858be23acd1819203ad035aa4a425fba88a6dc718d7fde7b046055a6fd30afc1949b8a99f93c6414175eefb50
-  data.tar.gz: 9c40fd10e8cef3e785bbcc83cde4de774ae1dcef53d8d029ce6a1e507c7954641ee868d81788378ecfa34ad6afbbf03da871ddb78107a45635dd72cb1cefa897
+  metadata.gz: 524a40d59079d2532db4817df108b08e78d964a1a4ec24f046a2f20c398d9121952fa1f9fd43211a02dfa2211e9bd45fb49b10c6c3dad3f693c5432e78cabe77
+  data.tar.gz: 1e60d573d88980f9c018dbed60012ee51e4fdfba50a181ec3a7389d1aa655038f67556ea95421089b4f1d2a1e1b933d75720c20d12f51654edca4afa2c42d982

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 This file is used to list changes made in each version of `dockerspec` Ruby Gem.
 
+## 0.2.0 (2015-12-11)
+
+### New Features on 0.2.0
+
+* Set some opinionated RSpec configurations.
+* Print Docker errors in a more readable format.
+
+### Fixes on 0.2.0
+
+* Fix *undefined method* error in the outermost examples.
+
+### Documentation Changes on 0.2.0
+
+* Add examples for `#have_cmd` using string format.
+* README:
+ * Improve Ruby documentation.
+ * Change gem badge to point to RubyGems.
+ * Add Real-world examples section.
+
 ## 0.1.0 (2015-12-09)
 
 * Initial release of `dockerspec`.

data/README.md

@@ -3,12 +3,12 @@
 [![GitHub](http://img.shields.io/badge/github-zuazo/dockerspec-blue.svg?style=flat)](https://github.com/zuazo/dockerspec)
 [![License](https://img.shields.io/github/license/zuazo/dockerspec.svg?style=flat)](#license-and-author)
 
-[![Gem Version](https://badge.fury.io/rb/dockerspec.svg)](http://github.com/zuazo/dockerspec/releases)
+[![Gem Version](https://badge.fury.io/rb/dockerspec.svg)](https://rubygems.org/gems/dockerspec)
 [![Dependency Status](http://img.shields.io/gemnasium/zuazo/dockerspec.svg?style=flat)](https://gemnasium.com/zuazo/dockerspec)
 [![Code Climate](http://img.shields.io/codeclimate/github/zuazo/dockerspec.svg?style=flat)](https://codeclimate.com/github/zuazo/dockerspec)
-[![Travis CI Build Status](http://img.shields.io/travis/zuazo/dockerspec/0.1.0.svg?style=flat)](https://travis-ci.org/zuazo/dockerspec)
+[![Travis CI Build Status](http://img.shields.io/travis/zuazo/dockerspec/0.2.0.svg?style=flat)](https://travis-ci.org/zuazo/dockerspec)
 [![Circle CI Build Status](https://circleci.com/gh/zuazo/dockerspec/tree/master.svg?style=shield)](https://circleci.com/gh/zuazo/dockerspec/tree/master)
-[![Coverage Status](http://img.shields.io/coveralls/zuazo/dockerspec/0.1.0.svg?style=flat)](https://coveralls.io/r/zuazo/dockerspec?branch=0.1.0)
+[![Coverage Status](http://img.shields.io/coveralls/zuazo/dockerspec/0.2.0.svg?style=flat)](https://coveralls.io/r/zuazo/dockerspec?branch=0.2.0)
 [![Inline docs](http://inch-ci.org/github/zuazo/dockerspec.svg?branch=master&style=flat)](http://inch-ci.org/github/zuazo/dockerspec)
 
 ## Description
@@ -20,7 +20,7 @@ This gem is designed to work out of the box on [Travis CI](https://travis-ci.org
 ## Requirements
 
 * Ruby `2` or higher.
-* Recommended Docker `1.7.0` or higher.
+* Recommended Docker `1.7` or higher.
 
 ## Installation
 
@@ -33,9 +33,7 @@ $ gem install dockerspec
 Or you can add this line to the *Gemfile* of your application:
 
 ```ruby
-# Gemfile
-
-gem 'dockerspec', '~> 0.1.0'
+gem 'dockerspec', '~> 0.2.0'
 ```
 
 And then execute:
@@ -86,23 +84,31 @@ end
 
 See the documentation above for more examples.
 
-### Prepare the Ruby Environment
+### Real-world Examples
+
+* [`alpine-tor`](https://github.com/zuazo/alpine-tor-docker) image ([*spec/*](https://github.com/zuazo/alpine-tor-docker/tree/master/spec), [*Gemfile*](https://github.com/zuazo/alpine-tor-docker/tree/master/Gemfile), [*.travis.yml*](https://github.com/zuazo/alpine-tor-docker/tree/master/.travis.yml)).
 
-1. Create a **Gemfile**:
+### Prepare Your Ruby Environment
+
+If you are new to Ruby, you can follow these steps:
+
+#### 1. Create a **Gemfile**:
 
 ```ruby
 # Gemfile
 
-gem 'dockerspec', '~> 0.1.0'
+source 'https://rubygems.org'
+
+gem 'dockerspec', '~> 0.2.0'
 ```
 
-2. Create the *spec/* directory:
+#### 2. Create the *spec/* directory:
 
 ```
 $ mkdir spec
 ```
 
-3. Add your tests to a file with the *spec/myapp_spec.rb* format:
+#### 3. Add your tests to a file with the *spec/myapp_spec.rb* format:
 
 ```ruby
 # spec/myapp_spec.rb
@@ -120,13 +126,13 @@ describe 'My Dockerfile' do
 end
 ```
 
-4. Install the gems:
+#### 4. Install the gems:
 
 ```
 $ bundle
 ```
 
-5. Run the tests:
+#### 5. Run the tests:
 
 ```
 $ bundle exec rspec

data/lib/dockerspec.rb

@@ -19,3 +19,4 @@
 
 require 'dockerspec/version'
 require 'dockerspec/rspec_resources'
+require 'dockerspec/rspec_configuration'

data/lib/dockerspec/builder.rb

@@ -28,6 +28,7 @@ require 'dockerspec/builder/logger'
 require 'dockerspec/builder/image_gc'
 require 'dockerspec/helper/ci'
 require 'dockerspec/helper/multiple_sources_description'
+require 'dockerspec/docker_exception_parser'
 
 module Dockerspec
   #
@@ -157,11 +158,7 @@ module Dockerspec
     #
     def source
       return @source unless @source.nil?
-      %i(string template id path).any? do |from|
-        next false unless @options.key?(from)
-        @source = from # Used for description
-      end
-      @source
+      @source = %i(string template id path).find { |from| @options.key?(from) }
     end
 
     #
@@ -321,6 +318,8 @@ module Dockerspec
     def build_from_dir(dir)
       image(::Docker::Image.build_from_dir(dir, &build_block))
       add_respository_tag
+    rescue ::Docker::Error::DockerError => e
+      DockerExceptionParser.new(e)
     end
 
     #
@@ -356,11 +355,10 @@ module Dockerspec
     def build_from_template(file)
       context = @options[:context] || {}
 
-      dir = File.dirname(file)
       template = IO.read(file)
       eruby = Erubis::Eruby.new(template)
       string = eruby.evaluate(context)
-      build_from_string(string, dir)
+      build_from_string(string, File.dirname(file))
     end
 
     #
@@ -379,6 +377,8 @@ module Dockerspec
       add_respository_tag
     rescue ::Docker::Error::NotFoundError
       @image = ::Docker::Image.create('fromImage' => id)
+    rescue ::Docker::Error::DockerError => e
+      DockerExceptionParser.new(e)
     end
 
     #

data/lib/dockerspec/builder/config_helpers.rb

@@ -127,6 +127,8 @@ module Dockerspec
       # @example RSpec Example Using *Have* Matchers
       #   describe docker_build(path: '.') do
       #     it { should have_cmd ['/usr/bin/supervisord'] }
+      #     # Or in string format:
+      #     it { should have_cmd '/usr/bin/supervisord' }
       #   end
       #
       # @return [Array] The image command.
@@ -150,7 +152,7 @@ module Dockerspec
       #     it { should have_label 'description' => 'My Container' }
       #   end
       #
-      # @example RSpec Example Checking Only the Existence of the label
+      # @example RSpec Example Checking Only the Existence of the Label
       #   describe docker_build(path: '.') do
       #     it { should have_label 'description' }
       #   end
@@ -264,6 +266,8 @@ module Dockerspec
       # @example RSpec Example Using *Have* Matchers
       #   describe docker_build(path: '.') do
       #     it { should have_entrypoint ['/entrypoint.sh'] }
+      #     # Or in string format:
+      #     it { should have_entrypoint '/entrypoint.sh' }
       #   end
       #
       # @return [Array] The image entrypoint.

data/lib/dockerspec/docker_exception_parser.rb

@@ -0,0 +1,159 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015 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 'json'
+require 'dockerspec/exceptions'
+
+module Dockerspec
+  #
+  # A class to parse `Docker::Error` exceptions.
+  #
+  class DockerExceptionParser
+    #
+    # Parses Docker exceptions.
+    #
+    # Raises the same exception if the format is unknown.
+    #
+    # @example
+    #   rescue ::Docker::Error::DockerError => e
+    #     DockerExceptionParser.new(e)
+    #   end
+    #
+    # @param e [Exception] The exception object to parse.
+    #
+    # @raise [Dockerspec::DockerError] When the exception format is known.
+    # @raise [Exception] When the exception format is unknown.
+    #
+    # @api public
+    #
+    def initialize(e)
+      e_ary = parse_exception(e)
+      raise_docker_error_exception(e_ary)
+      fail e
+    end
+
+    protected
+
+    #
+    # Parses the exception JSON message.
+    #
+    # The message must be a list of JSON messages merged by a new line.
+    #
+    # A valid exception message example:
+    #
+    # ```
+    # {"stream":"Step 1 : FROM alpine:3.2\n"}
+    # {"stream":" ---\u003e d6ead20d5571\n"}
+    # {"stream":"Step 2 : RUN apk add --update wrong-package-name\n"}
+    # {"stream":" ---\u003e Running in 290a46fa8bf4\n"}
+    # {"stream":"fetch http://dl-4.alpinelinux.org/alpine/v3.2/main/...\n"}
+    # {"stream":"ERROR: unsatisfiable constraints:\n"}
+    # {"stream":"  wrong-package-name (missing):\n    required by: world...\n"}
+    # {"errorDetail":{"message":"The command ..."},"error":"The command ..."}
+    # ```
+    #
+    # @example
+    #   self.parse_exception(e)
+    #   #=> [{ "stream" => "Step 1 : FROM alpine:3.2\n" }, "errorDetail" => ...
+    #
+    # @param e [Exception] The exception object to parse.
+    #
+    # @return [Array<Hash>] The list of JSON messages parsed.
+    #
+    # @return
+    #
+    # @api private
+    #
+    def parse_exception(e)
+      msg = e.to_s
+      json = msg.to_s.sub(/^Couldn't find id: /, '').split("\n").map(&:chomp)
+      json.map { |str| JSON.parse(str) }
+    rescue JSON::ParserError
+      raise e
+    end
+
+    #
+    # Gets the error message from the *errorDetail* field.
+    #
+    # @param e_ary [Array<Hash>] The list of JSON messages already parsed.
+    #
+    # @return [String] The error message string.
+    #
+    # @api private
+    #
+    def parse_error_detail(e_ary)
+      e_detail = e_ary.select { |x| x.is_a?(Hash) && x.key?('errorDetail') }[0]
+      return nil unless e_detail.is_a?(Hash)
+      return e_detail['message'] if e_detail.key?('message')
+      return e_detail['error'] if e_detail.key?('error')
+    end
+
+    #
+    # Gets all the console output from the stream logs.
+    #
+    # @param e_ary [Array<Hash>] The list of JSON messages already parsed.
+    #
+    # @return [String] The generated stdout output.
+    #
+    # @api private
+    #
+    def parse_streams(e_ary)
+      e_ary.map { |x| x.is_a?(Hash) && x['stream'] }.compact.join
+    end
+
+    #
+    # Generates a formated error message.
+    #
+    # @param error [String] The error message.
+    # @param output [String] The generated stdout output.
+    #
+    # @return [String] The resulting error message.
+    #
+    # @api private
+    #
+    def generate_error_message(error, output)
+      [
+        "#{error}\n",
+        "OUTPUT: \n#{output.gsub(/^/, ' ' * 8)}",
+        "ERROR:  #{error}\n\n"
+      ].join("\n")
+    end
+
+    #
+    # Raises the right {Dockerspec::DockerError} exception.
+    #
+    # Nothing is raised if the exception format is unknown.
+    #
+    # @param e_ary [Array<Hash>] The list of JSON messages already parsed.
+    #
+    # @return void
+    #
+    # @raise [Dockerspec::DockerError] When the exception format is known.
+    #
+    # @api private
+    #
+    def raise_docker_error_exception(e_ary)
+      e_ary.select { |x| x.is_a?(Hash) && x.key?('errorDetail') }[0]
+      output = parse_streams(e_ary)
+      error_msg = parse_error_detail(e_ary)
+      return if error_msg.nil?
+      fail DockerError, generate_error_message(error_msg, output)
+    end
+  end
+end

data/lib/dockerspec/exceptions.rb

@@ -23,4 +23,9 @@ module Dockerspec
   # wrong.
   #
   class DockerRunArgumentError < ArgumentError; end
+  #
+  # An exception message raised when there are errors running Docker or
+  # building Docker images.
+  #
+  class DockerError < ArgumentError; end
 end

data/lib/dockerspec/rspec_configuration.rb

@@ -0,0 +1,29 @@
+# encoding: UTF-8
+#
+# Author:: Xabier de Zuazo (<xabier@zuazo.org>)
+# Copyright:: Copyright (c) 2015 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.
+#
+
+#
+# Some very opinionated RSpec configuration.
+#
+# This may change in the future.
+#
+RSpec.configure do |config|
+  config.color = true
+  config.formatter = :documentation
+  config.tty = true
+end

data/lib/dockerspec/rspec_resources.rb

@@ -133,7 +133,7 @@ module Dockerspec
     #     # [...]
     #   end
     #
-    # @example Building from a Docker Image name
+    # @example Building from a Docker Image Name
     #   describe docker_build(id: 'nginx:1.9') do
     #     # [...]
     #   end
@@ -196,3 +196,8 @@ RSpec::Core::ExampleGroup.class_eval do
   extend Dockerspec::RSpecResources
   include Dockerspec::RSpecResources
 end
+
+#
+# Allow using #docker_build in the outermost example
+#
+extend Dockerspec::RSpecResources

data/lib/dockerspec/runner.rb

@@ -21,6 +21,7 @@ require 'docker'
 require 'dockerspec/docker_gem'
 require 'dockerspec/exceptions'
 require 'dockerspec/helper/multiple_sources_description'
+require 'dockerspec/docker_exception_parser'
 
 module Dockerspec
   #
@@ -175,11 +176,7 @@ module Dockerspec
     #
     def source
       return @source unless @source.nil?
-      %i(tag id).any? do |from|
-        next false unless @options.key?(from)
-        @source = from # Used for description
-      end
-      @source
+      @source = %i(tag id).find { |from| @options.key?(from) }
     end
 
     #
@@ -299,6 +296,8 @@ module Dockerspec
     #
     def setup_from_id(id)
       @container = ::Docker::Container.get(id)
+    rescue ::Docker::Error::DockerError => e
+      DockerExceptionParser.new(e)
     end
 
     #
@@ -358,6 +357,8 @@ module Dockerspec
     def create_container
       return @container unless @container.nil?
       @container = ::Docker::Container.create(container_options)
+    rescue ::Docker::Error::DockerError => e
+      DockerExceptionParser.new(e)
     end
 
     #

data/lib/dockerspec/serverspec/rspec_resources.rb

@@ -172,3 +172,8 @@ RSpec::Core::ExampleGroup.class_eval do
   extend Dockerspec::Serverspec::RSpecResources
   include Dockerspec::Serverspec::RSpecResources
 end
+
+#
+# Allow using #docker_run in the outermost example
+#
+extend Dockerspec::RSpecResources

data/lib/dockerspec/serverspec/runner.rb

@@ -23,6 +23,7 @@ require 'dockerspec/runner'
 require 'dockerspec/serverspec/specinfra_backend'
 require 'dockerspec/helper/rspec_example_helpers'
 require 'dockerspec/helper/docker'
+require 'dockerspec/docker_exception_parser'
 
 #
 # Silence error: No backend type is specified. Fall back to :exec type.
@@ -100,6 +101,8 @@ module Dockerspec
         run_container
         specinfra_save
         self
+      rescue ::Docker::Error::DockerError => e
+        DockerExceptionParser.new(e)
       end
 
       #

data/lib/dockerspec/version.rb

@@ -25,5 +25,5 @@ module Dockerspec
   #
   # Dockerspec Ruby Gem version.
   #
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/spec/spec_helper.rb

@@ -28,6 +28,7 @@ end
 
 require 'dockerspec'
 require 'dockerspec/serverspec'
+require 'support/dockerspec_tests'
 
 require 'should_not/rspec'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dockerspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Xabier de Zuazo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-09 00:00:00.000000000 Z
+date: 2015-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docker-api
@@ -246,6 +246,7 @@ files:
 - lib/dockerspec/builder/logger/silent.rb
 - lib/dockerspec/builder/matchers.rb
 - lib/dockerspec/builder/matchers/helpers.rb
+- lib/dockerspec/docker_exception_parser.rb
 - lib/dockerspec/docker_gem.rb
 - lib/dockerspec/exceptions.rb
 - lib/dockerspec/helper/ci.rb
@@ -253,6 +254,7 @@ files:
 - lib/dockerspec/helper/multiple_sources_description.rb
 - lib/dockerspec/helper/rspec_example_helpers.rb
 - lib/dockerspec/rspec_assertions.rb
+- lib/dockerspec/rspec_configuration.rb
 - lib/dockerspec/rspec_resources.rb
 - lib/dockerspec/rspec_settings.rb
 - lib/dockerspec/runner.rb