dockerspec 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7694cecd69e554a6954f6b9db00f3fe2b768f15c
-  data.tar.gz: 1a2a4415286128639366c18f8ab4f6d303d416c0
+  metadata.gz: 00c000093e65be525764d4adb1a19c986747a1f2
+  data.tar.gz: 31ffe0b3521f66c09dffb9994e0d5de0a7895ef9
 SHA512:
-  metadata.gz: 524a40d59079d2532db4817df108b08e78d964a1a4ec24f046a2f20c398d9121952fa1f9fd43211a02dfa2211e9bd45fb49b10c6c3dad3f693c5432e78cabe77
-  data.tar.gz: 1e60d573d88980f9c018dbed60012ee51e4fdfba50a181ec3a7389d1aa655038f67556ea95421089b4f1d2a1e1b933d75720c20d12f51654edca4afa2c42d982
+  metadata.gz: cf7da409ef3be6b88a6720bab01736e9badb61fc12b6ed494fee7efc47df18ca51aa09ad11a1703230aee29912e0dd62788d2653463048f8bfcea457a3fb4297
+  data.tar.gz: 769fd611bd5c3e1bb8b97e8d37f65adb9572a2fe810e26af03e85d41ec7dac8af7fc543ba8575c7afef6fccc2cace7455404f8a0e20d9c0caa14deb5fca248b5

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 This file is used to list changes made in each version of `dockerspec` Ruby Gem.
 
+## 0.3.0 (2016-02-28)
+
+### Breaking Changes on 0.3.0
+
+* Enable `options[:rm]` by default.
+
+### New Features on 0.3.0
+
+* Add Docker Compose support.
+* Add Infrataster and Capybara support.
+* Add `:wait` option to `docker_run` and `docker_compose`.
+* Add `described_image` helper for `docker_run`.
+* Support integer values with `have_expose` matcher.
+* Make `require 'dockerspec'` optional.
+
+### Fixes on 0.3.0
+
+* Fix `:env` in `docker_run` with Serverspec.
+* Fix *Must have id* error when building images from IDs with tags.
+
+### Improvements on 0.3.0
+
+* Update RuboCop to `0.37`, fix new offenses.
+* `Runner` classes split into `Engine::Base` and `Runner::Base`.
+* Add support for multiple testing engines.
+* Add a `Configuration` class to setup the internal modularization.
+* Rename many classes.
+
+### Documentation Changes on 0.3.0
+
+* README:
+ * Move the documentation below examples.
+ * Add many examples.
+
 ## 0.2.0 (2015-12-11)
 
 ### New Features on 0.2.0

data/LICENSE

@@ -175,7 +175,7 @@ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
 END OF TERMS AND CONDITIONS
 
-Copyright 2015 Xabier de Zuazo
+Copyright 2015-2016 Xabier de Zuazo
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/README.md

@@ -6,14 +6,14 @@
 [![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.2.0.svg?style=flat)](https://travis-ci.org/zuazo/dockerspec)
+[![Travis CI Build Status](http://img.shields.io/travis/zuazo/dockerspec/0.3.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.2.0.svg?style=flat)](https://coveralls.io/r/zuazo/dockerspec?branch=0.2.0)
+[![Coverage Status](http://img.shields.io/coveralls/zuazo/dockerspec/0.3.0.svg?style=flat)](https://coveralls.io/r/zuazo/dockerspec?branch=0.3.0)
 [![Inline docs](http://inch-ci.org/github/zuazo/dockerspec.svg?branch=master&style=flat)](http://inch-ci.org/github/zuazo/dockerspec)
 
 ## Description
 
-A small Ruby Gem to run RSpec and [Serverspec](http://serverspec.org/) tests against Dockerfiles or Docker images easily.
+A small Ruby Gem to run RSpec, [Serverspec](http://serverspec.org/), [Infrataster](https://github.com/ryotarai/infrataster) and [Capybara](http://jnicklas.github.io/capybara/) tests against Dockerfiles or Docker images easily.
 
 This gem is designed to work out of the box on [Travis CI](https://travis-ci.org/), [CircleCI](https://circleci.com/) and other similar CI environments.
 
@@ -33,7 +33,7 @@ $ gem install dockerspec
 Or you can add this line to the *Gemfile* of your application:
 
 ```ruby
-gem 'dockerspec', '~> 0.2.0'
+gem 'dockerspec', '~> 0.3.0'
 ```
 
 And then execute:
@@ -44,30 +44,22 @@ $ bundle
 
 **Warning:** As the gem is in its early development stages, [the API is very likely to break between minor versions](http://semver.org/).
 
-## Documentation
-
-- [`docker_build`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpecResources#docker_build-instance_method)
-  - [*Docker Build* helpers](http://www.rubydoc.info/gems/dockerspec/Dockerspec/Builder/ConfigHelpers)
-- [`docker_run`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/Serverspec/RSpecResources#docker_run-instance_method)
-  - [*Docker Run* Serverspec resource types](http://serverspec.org/resource_types.html)
-
 ## Usage Examples
 
 ### Run Tests Against a Dockerfile in the Current Directory
 
 ```ruby
-require 'dockerspec'
 require 'dockerspec/serverspec'
 
 describe 'My Dockerfile' do
-  describe docker_build('.', tag: 'myapp') do
+  describe docker_build('.') do
 
     it { should have_maintainer /John Doe/ }
     it { should have_cmd ['/bin/dash'] }
     it { should have_expose '80' }
     it { should have_user 'nobody' }
 
-    describe docker_run('myapp') do
+    describe docker_run(described_image) do
       describe file('/etc/httpd.conf') do
         it { should be_file }
         it { should contain 'ServerName www.example.jp' }
@@ -78,15 +70,195 @@ describe 'My Dockerfile' do
         it { should be_running }
       end
     end
+
   end
 end
 ```
 
 See the documentation above for more examples.
 
+### Run Tests Against Docker Compose
+
+```ruby
+require 'dockerspec/serverspec'
+
+describe docker_compose('.', wait: 30) 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
+```
+
+**Important Warning:** The `docker_compose` resource uses the [`docker-compose-api`](https://rubygems.org/gems/docker-compose-api) Ruby gem to emulate Docker Compose. So, some *docker-compose.yml* configuration options may not be supported yet or may not work exactly the same. Let us know if you find any bug or you need a missing feature. And thanks to [Mauricio Klein](https://github.com/mauricioklein) for all his work by the way!
+
+### Run HTTP Tests Using Infrataster
+
+```ruby
+# require 'dockerspec/serverspec' # Only if you want to run both types of tests
+require 'dockerspec/infrataster'
+
+describe docker_run('nginx') do
+  describe server(described_container) do # Infrataster
+
+    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
+```
+See the [Infrataster Resources documentation](http://www.rubydoc.info/gems/infrataster#Resources) for more information.
+
+### Run HTTP Tests Using Capybara
+
+In the following example we set the *admin* password and log in in a hypothetical web application:
+
+```ruby
+require 'dockerspec/infrataster'
+
+describe docker_build('.', tag: 'mywebapp') do
+  describe docker_run('mywebapp') do
+
+    describe server(described_container) do
+      describe capybara('/') do
+        let(:password) { '4dm1nP4ssw0rd' }
+
+        describe 'on /setup' do
+          before { visit '/setup' }
+
+          it 'contains "Configure the password"' do
+            expect(page).to have_content 'Configure the password'
+          end
+
+          it 'sets the admin password' do
+            fill_in 'Password', with: password
+            fill_in 'Confirm Password', with: password
+            click_button 'Set password'
+          end
+        end
+
+        describe 'on /login' do
+          before { visit '/login' }
+
+          it 'logs in as admin' do
+            expect(page).to have_content 'sign in'
+            fill_in 'User name', with: 'admin'
+            fill_in 'Password', with: password
+            click_button 'Sig in'
+          end
+        end
+
+        describe 'on /' do
+          before { visit '/' }
+
+          it 'is logged id' do
+            expect(page).to have_content 'Welcome admin!'
+          end
+        end
+
+      end
+    end
+
+  end
+end
+```
+
+See the [Capybara DSL documentation](http://www.rubydoc.info/gems/capybara#The_DSL) for more information.
+
+### Run Database Tests Using `infrataster-plugin-mysql` Gem with Docker Compose
+
+You need to include the `infrataster-plugin-mysql` gem in your *Gemfile*:
+
+```ruby
+# Gemfile
+
+# gem [...]
+gem 'infrataster-plugin-mysql', '~> 0.2.0'
+```
+
+A *docker-compose.yml* file example with a database:
+
+```yaml
+myapp:
+  image: myapp
+  links:
+  - db:mysql
+  ports:
+  - 8080:80
+
+db:
+  image: mariadb
+  environment:
+  - MYSQL_ROOT_PASSWORD=example
+```
+
+The file with the tests:
+
+```ruby
+require 'dockerspec/infrataster'
+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 # Infrataster
+
+      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
+
+      describe mysql_query('SHOW DATABASES') do
+        it 'includes `myapp` database' do
+          databases = results.map { |r| r['Database'] }
+          expect(databases).to include('myapp')
+        end
+      end
+
+    end
+  end
+end
+```
+
+## Documentation
+
+- [`docker_build`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#docker_build-instance_method)
+  - [*Docker Build* helpers](http://www.rubydoc.info/gems/dockerspec/Dockerspec/Builder/ConfigHelpers)
+- [`docker_run`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#docker_run-instance_method)
+  - [*Docker Run* Serverspec resource types](http://serverspec.org/resource_types.html)
+  - [Infrataster Resources](http://www.rubydoc.info/gems/infrataster#Resources)
+  - [Capybara DSL](http://www.rubydoc.info/gems/capybara#The_DSL)
+- [`docker_compose`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#docker_compose-instance_method)
+  - [`its_container`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#its_container-instance_method)
+
 ### 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)).
+* [`chef-local`](https://github.com/zuazo/chef-local-docker) image ([*spec/*](https://github.com/zuazo/chef-local-docker/tree/master/spec), [*Gemfile*](https://github.com/zuazo/chef-local-docker/tree/master/Gemfile), [*.travis.yml*](https://github.com/zuazo/chef-local-docker/tree/master/.travis.yml)): Runs the same tests against multiple tags.
+* [`keywhiz`](https://github.com/zuazo/keywhiz-docker) image ([*spec/*](https://github.com/zuazo/keywhiz-docker/tree/master/spec), [*Gemfile*](https://github.com/zuazo/keywhiz-docker/tree/master/Gemfile), [*.travis.yml*](https://github.com/zuazo/keywhiz-docker/tree/master/.travis.yml)).
+* [`irssi-tor`](https://github.com/zuazo/irssi-tor-docker) image ([*spec/*](https://github.com/zuazo/irssi-tor-docker/tree/master/spec), [*Gemfile*](https://github.com/zuazo/irssi-tor-docker/tree/master/Gemfile), [*.travis.yml*](https://github.com/zuazo/irssi-tor-docker/tree/master/.travis.yml)).
+* [`dradis`](https://github.com/zuazo/dradis-docker) image ([*spec/*](https://github.com/zuazo/dradis-docker/tree/master/spec), [*Gemfile*](https://github.com/zuazo/dradis-docker/tree/master/Gemfile), [*.travis.yml*](https://github.com/zuazo/dradis-docker/tree/master/.travis.yml)): Runs some Capybara HTTP tests.
 
 ### Prepare Your Ruby Environment
 
@@ -99,7 +271,7 @@ If you are new to Ruby, you can follow these steps:
 
 source 'https://rubygems.org'
 
-gem 'dockerspec', '~> 0.2.0'
+gem 'dockerspec', '~> 0.3.0'
 ```
 
 #### 2. Create the *spec/* directory:
@@ -113,13 +285,12 @@ $ mkdir spec
 ```ruby
 # spec/myapp_spec.rb
 
-require 'dockerspec'
 require 'dockerspec/serverspec'
 
 describe 'My Dockerfile' do
-  describe docker_build('.', tag: 'myapp') do
+  describe docker_build('.') do
     # [...]
-    describe docker_run('myapp') do
+    describe docker_run(described_image) do
       # [...]
     end
   end
@@ -145,11 +316,6 @@ $ bundle exec rspec
 ```yaml
 language: ruby
 
-rvm:
-- 2.0.0
-- 2.1
-- 2.2
-
 sudo: required
 
 services: docker
@@ -192,7 +358,7 @@ See [TODO.md](https://github.com/zuazo/dockerspec/blob/master/TODO.md).
 |                      |                                          |
 |:---------------------|:-----------------------------------------|
 | **Author:**          | [Xabier de Zuazo](https://github.com/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/Rakefile

@@ -2,7 +2,22 @@
 # -*- mode: ruby -*-
 # vi: set ft=ruby :
 
+#
+# Available Rake tasks:
+#
+# $ rake -T
+# rake clean                    # Clean some generated files
+# rake integration              # Run the integration tests
+# rake integration:infrataster  # Infrataster engine integration tests
+# rake integration:serverspec   # Serverspec engine integration tests
+# rake rubocop                  # Run RuboCop style checks
+# rake style                    # Run all style checks
+# rake test                     # Run all the tests
+# rake unit                     # Run the unit tests
+# rake yard                     # Generate Ruby documentation
+#
 # More info at https://github.com/ruby/rake/blob/master/doc/rakefile.rdoc
+#
 
 require 'bundler'
 Bundler::GemHelper.install_tasks
@@ -43,15 +58,54 @@ task style: %w(rubocop)
 
 require 'rspec/core/rake_task'
 
-{
-  test: '{unit,integration}',
-  unit: 'unit',
-  integration: 'integration'
-}.each do |test, dir|
-  RSpec::Core::RakeTask.new(test) do |t|
+#
+# Gest the tests directory name to use.
+#
+# @param name [String] The task name.
+#
+# @return [String] Subdirectory name inside *spec/*.
+#
+def rake_dir_from_name(name)
+  if %w(serverspec infrataster).include?(name.to_s)
+    'integration'
+  else
+    name.to_s == 'test' ? '{unit,integration}' : name
+  end
+end
+
+#
+# Generates RakeTask to run the tests.
+#
+# @param name [String] The task name.
+#
+# @param env [Hash] The environment variables to set.
+#
+# @return [RSpec::Core::RakeTask] The Generated RakeTask.
+#
+def rake_task(name, env = {})
+  dir = rake_dir_from_name(name)
+  RSpec::Core::RakeTask.new(name) do |t|
+    env.each { |k, v| ENV[k.to_s.upcase] = v.to_s }
     t.pattern = "spec/#{dir}/**{,/*/**}/*_spec.rb"
     t.verbose = true
   end
 end
 
+desc 'Run the unit tests'
+rake_task(:unit)
+
+namespace :integration do
+  desc 'Serverspec engine integration tests'
+  rake_task(:serverspec, serverspec: true)
+
+  desc 'Infrataster engine integration tests'
+  rake_task(:infrataster, infrataster: true)
+end
+
+desc 'Run all the integration tests'
+rake_task(:integration)
+
+desc 'Run all the tests'
+rake_task(:test)
+
 task default: %w(style test)

data/TODO.md

@@ -1,6 +1,7 @@
 # TODO for Dockerspec
 
 * [ ] Integrate with [Inspec](https://www.chef.io/inspec/).
-* [ ] Integrate with [Infrataster](https://github.com/ryotarai/infrataster).
-* [ ] Support Docker Compose.
+* [ ] Test resources for built images supported inside `docker_compose`.
+* [ ] Add `docker_context`, `docker_describe` to avoid starting all containers at the same time.
 * [ ] Add a Runner logger.
+* [ ] Create `stub_*` methods for unit tests.