Dockerspec

Description

A small Ruby Gem to run RSpec and Serverspec 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.2.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.

Documentation

Usage Examples

Run Tests Against a Dockerfile in the Current Directory

require 'dockerspec'
require 'dockerspec/serverspec'

describe 'My Dockerfile' do
  describe docker_build('.', tag: 'myapp') 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 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.

Real-world Examples

alpine-tor image (spec/, Gemfile, .travis.yml).

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.2.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'
require 'dockerspec/serverspec'

describe 'My Dockerfile' do
  describe docker_build('.', tag: 'myapp') do
    # [...]
    describe docker_run('myapp') 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

rvm:
- 2.0.0
- 2.1
- 2.2

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 ([email protected])
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.