Dockerspec

Description

A small Ruby Gem to run RSpec, Serverspec, Infrataster and Capybara tests against Dockerfiles or Docker images easily.

This gem is designed to work out of the box on Travis CI, CircleCI and other similar CI environments.

Requirements

• Ruby 2 or higher.
• Recommended Docker 1.7 or higher.

Installation

You can install the Ruby Gem with:

$ gem install dockerspec

Or you can add this line to the Gemfile of your application:

gem 'dockerspec', '~> 0.3.0'

And then execute:

$ bundle

Warning: As the gem is in its early development stages, the API is very likely to break between minor versions.

Usage Examples

Run Tests Against a Dockerfile in the Current Directory

require 'dockerspec/serverspec'

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' }
    it { should have_user 'nobody' }

    describe docker_run(described_image) do
      describe file('/etc/httpd.conf') do
        it { should be_file }
        it { should contain 'ServerName www.example.jp' }
      end

      describe service('httpd') do
        it { should be_enabled }
        it { should be_running }
      end
    end

  end
end

See the documentation above for more examples.

Run Tests Against Docker Compose

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 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 for all his work by the way!

Run HTTP Tests Using Infrataster

# 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 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:

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 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:

# Gemfile

# gem [...]
gem 'infrataster-plugin-mysql', '~> 0.2.0'

A docker-compose.yml file example with a database:

myapp:
  image: myapp
  links:
  - db:mysql
  ports:
  - 8080:80

db:
  image: mariadb
  environment:
  - MYSQL_ROOT_PASSWORD=example

The file with the tests:

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
  • Docker Build helpers
• docker_run
  • Docker Run Serverspec resource types
  • Infrataster Resources
  • Capybara DSL
• docker_compose
  • its_container

Real-world Examples

• alpine-tor image (spec/, Gemfile, .travis.yml).
• chef-local image (spec/, Gemfile, .travis.yml): Runs the same tests against multiple tags.
• keywhiz image (spec/, Gemfile, .travis.yml).
• irssi-tor image (spec/, Gemfile, .travis.yml).
• dradis image (spec/, Gemfile, .travis.yml): Runs some Capybara HTTP tests.

Prepare Your Ruby Environment

If you are new to Ruby, you can follow these steps:

1. Create a Gemfile:

# Gemfile

source 'https://rubygems.org'

gem 'dockerspec', '~> 0.3.0'

2. Create the spec/ directory:

$ mkdir spec

3. Add your tests to a file with the spec/myapp_spec.rb format:

# spec/myapp_spec.rb

require 'dockerspec/serverspec'

describe 'My Dockerfile' do
  describe docker_build('.') do
    # [...]
    describe docker_run(described_image) do
      # [...]
    end
  end
end

4. Install the gems:

$ bundle

5. Run the tests:

$ bundle exec rspec

Travis CI Configuration Example

.travis.yml file example:

language: ruby

sudo: required

services: docker

script: travis_retry bundle exec rspec

CircleCI Configuration Example

circle.yml file example:

machine:
  services:
  - docker
  ruby:
    version: 2.2.3

test:
  override:
  - bundle exec rspec

Testing

See TESTING.md.

Contributing

Please do not hesitate to open an issue with any questions or problems.

See CONTRIBUTING.md.

TODO

See TODO.md.

License and Author

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.