{"id":13416593,"url":"https://github.com/zuazo/dockerspec","last_synced_at":"2025-04-06T03:08:28.109Z","repository":{"id":56844310,"uuid":"47682521","full_name":"zuazo/dockerspec","owner":"zuazo","description":"A small Ruby Gem to run RSpec and Serverspec, Infrataster and Capybara tests against Dockerfiles or Docker images easily.","archived":false,"fork":false,"pushed_at":"2017-08-30T20:40:57.000Z","size":217,"stargazers_count":180,"open_issues_count":10,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T02:05:56.082Z","etag":null,"topics":["capybara","circleci","compliance","devops","docker","docker-compose","rspec","rspec-retry","serverspec","spec","tdd","tdd-utilities","testing","travis-ci"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/dockerspec","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zuazo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-09T09:47:29.000Z","updated_at":"2025-02-26T15:41:06.000Z","dependencies_parsed_at":"2022-09-09T04:11:02.222Z","dependency_job_id":null,"html_url":"https://github.com/zuazo/dockerspec","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fdockerspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fdockerspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fdockerspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fdockerspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zuazo","download_url":"https://codeload.github.com/zuazo/dockerspec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capybara","circleci","compliance","devops","docker","docker-compose","rspec","rspec-retry","serverspec","spec","tdd","tdd-utilities","testing","travis-ci"],"created_at":"2024-07-30T21:01:01.636Z","updated_at":"2025-04-06T03:08:28.087Z","avatar_url":"https://github.com/zuazo.png","language":"Ruby","readme":"# Dockerspec\n[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg?style=flat)](http://www.rubydoc.info/gems/dockerspec)\n[![GitHub](http://img.shields.io/badge/github-zuazo/dockerspec-blue.svg?style=flat)](https://github.com/zuazo/dockerspec)\n[![License](https://img.shields.io/github/license/zuazo/dockerspec.svg?style=flat)](#license-and-author)\n\n[![Gem Version](https://badge.fury.io/rb/dockerspec.svg)](https://rubygems.org/gems/dockerspec)\n[![Dependency Status](http://img.shields.io/gemnasium/zuazo/dockerspec.svg?style=flat)](https://gemnasium.com/zuazo/dockerspec)\n[![Code Climate](http://img.shields.io/codeclimate/github/zuazo/dockerspec.svg?style=flat)](https://codeclimate.com/github/zuazo/dockerspec)\n[![Travis CI Build Status](http://img.shields.io/travis/zuazo/dockerspec.svg?style=flat)](https://travis-ci.org/zuazo/dockerspec)\n[![Circle CI Build Status](https://circleci.com/gh/zuazo/dockerspec/tree/master.svg?style=shield)](https://circleci.com/gh/zuazo/dockerspec/tree/master)\n[![Coverage Status](http://img.shields.io/coveralls/zuazo/dockerspec.svg?style=flat)](https://coveralls.io/github/zuazo/dockerspec?branch=master)\n[![Inline docs](http://inch-ci.org/github/zuazo/dockerspec.svg?branch=master\u0026style=flat)](http://inch-ci.org/github/zuazo/dockerspec)\n\nA 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.\n\nThis 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.\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Documentation](#documentation)\n  - [Presentations](#presentations)\n- [Usage Examples](#usage-examples)\n  - [Run Tests Against a Dockerfile in the Current Directory](#run-tests-against-a-dockerfile-in-the-current-directory)\n  - [Run Tests Against Docker Compose](#run-tests-against-docker-compose)\n  - [Checking Container Logs](#checking-container-logs)\n  - [Retrying Tests That Fail Temporarily](#retrying-tests-that-fail-temporarily)\n  - [Run HTTP Tests Using Infrataster](#run-http-tests-using-infrataster)\n  - [Run HTTP Tests Using Capybara](#run-http-tests-using-capybara)\n  - [Run Database Tests Using `infrataster-plugin-mysql` Gem with Docker Compose](#run-database-tests-using-infrataster-plugin-mysql-gem-with-docker-compose)\n  - [Run Different Tests on Each Platform](#run-different-tests-on-each-platform)\n  - [Real-world Examples](#real-world-examples)\n  - [Prepare Your Ruby Environment](#prepare-your-ruby-environment)\n  - [Travis CI Configuration Example](#travis-ci-configuration-example)\n  - [CircleCI Configuration Example](#circleci-configuration-example)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [TODO](#todo)\n- [License and Author](#license-and-author)\n\n## Requirements\n\n* Ruby `2.2` or higher.\n* Recommended Docker `1.7` or higher.\n\n## Installation\n\nYou can install the Ruby Gem with:\n\n```\n$ gem install dockerspec\n```\n\nOr you can add this line to the *Gemfile* of your application:\n\n```ruby\ngem 'dockerspec', '~\u003e 0.5.0'\n```\n\nAnd then execute:\n\n```\n$ bundle\n```\n\n**Warning:** As the gem is in its early development stages, [the API is very likely to break between minor versions](http://semver.org/).\n\n## Documentation\n\n- Latest release documentation: http://www.rubydoc.info/gems/dockerspec\n- Master unreleased documentation: http://www.rubydoc.info/github/zuazo/dockerspec\n\nSpecific documentation sections for resources or functions that can be used to generate test cases:\n\n- [`docker_build`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#docker_build-instance_method)\n  - [*Docker Build* helpers](http://www.rubydoc.info/gems/dockerspec/Dockerspec/Builder/ConfigHelpers)\n- [`docker_run`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#docker_run-instance_method)\n  - [*Docker Run* helpers](http://www.rubydoc.info/gems/dockerspec/Dockerspec/Runner/ConfigHelpers)\n  - [*Docker Run* Serverspec resource types](http://serverspec.org/resource_types.html)\n  - [Infrataster Resources](http://www.rubydoc.info/gems/infrataster#Resources)\n  - [Capybara DSL](http://www.rubydoc.info/gems/capybara#The_DSL)\n- [`docker_compose`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#docker_compose-instance_method)\n  - [`its_container`](http://www.rubydoc.info/gems/dockerspec/Dockerspec/RSpec/Resources#its_container-instance_method)\n\n### Presentations\n\nApart from the official documentation, [Nan Liu](https://github.com/nanliu) presented a talk for [Portland Docker user group](https://www.meetup.com/Docker-Portland-OR/events/236739986/) regarding how to use Dockerspec in a container:\n\n- [Trust, but verify | Testing with Docker Containers](http://www.slideshare.net/NanLiu1/trust-but-verify-testing-with-docker-containers)\n\n\u003ca href=\"https://www.slideshare.net/NanLiu1/trust-but-verify-testing-with-docker-containers\"\u003e\n  \u003cimg src=\"https://i.gyazo.com/fe45a36c2e329af317482c280a09dfab.png\" alt=\"Trust, but verify | Testing with Docker Containers\" width=\"300px\"\u003e\n\u003c/a\u003e\n\n## Usage Examples\n\n### Run Tests Against a Dockerfile in the Current Directory\n\n```ruby\nrequire 'dockerspec/serverspec'\n\ndescribe 'My Dockerfile' do\n  describe docker_build('.') do\n\n    it { should have_maintainer /John Doe/ }\n    it { should have_cmd ['/bin/dash'] }\n    it { should have_expose '80' }\n    it { should have_user 'nobody' }\n\n    describe docker_run(described_image) do\n      describe file('/etc/httpd.conf') do\n        it { should be_file }\n        it { should contain 'ServerName www.example.jp' }\n      end\n\n      describe service('httpd') do\n        it { should be_enabled }\n        it { should be_running }\n      end\n    end\n\n  end\nend\n```\n\nSee [the documentation above](#documentation) for more examples.\n\n### Run Tests Against Docker Compose\n\n```ruby\nrequire 'dockerspec/serverspec'\n\ndescribe docker_compose('.', wait: 30) do\n\n  its_container(:myapp) do\n    describe process('apache2') do\n      it { should be_running }\n      its(:args) { should match(/-DFOREGROUND/) }\n    end\n    # [...]\n  end\n\n  its_container(:db) do\n    its(:stdout) { should include 'MySQL init process done.' }\n\n    describe process('mysqld') do\n      it { should be_running }\n    end\n    # [...]\n  end\n\nend\n```\n\n**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!\n\n### Checking Container Logs\n\nTo check the running container logs content, you can use [the `stdout` and `stderr` helpers](http://www.rubydoc.info/gems/dockerspec/Dockerspec/Runner/ConfigHelpers) inside `docker_run` or `its_container` blocks.\n\nFor example:\n\n```ruby\nrequire 'dockerspec/serverspec'\n\ndescribe 'My Dockerfile' do\n  describe docker_build('.') do\n    describe docker_run(described_image) do\n      its(:stdout) { should include 'Successfully Started.' }\n      its(:stderr) { should eq '' }\n    end\n  end\nend\n```\n\n### Retrying Tests That Fail Temporarily\n\nThis gem includes the [`rspec-retry`](https://github.com/NoRedInk/rspec-retry) gem. So, you can add `:retry` to the RSpec metadata in order to retry some tests multiple times.\n\nFor example:\n\n```ruby\ndescribe docker_run('mariadb') do\n  its(:stdout, retry: 30) { should include 'MySQL init process done.' }\nend\n```\n\nBy default, it will do a sleep of 1 second between each retry. You can adjust it with `:retry_wait`. See [`rspec-retry` documentation](http://www.rubydoc.info/gems/rspec-retry/0.4.5) for more details.\n\nYou can also make all tests within a block retry:\n\n```ruby\ndescribe docker_run('mariadb'), retry: 30 do\n  its(:stdout) { should include 'MySQL init process done.' }\n  its(:stderr) { should include 'MySQL init process done.' }\n\n  describe command('mysqld -V'), retry: 1 do # disable retries here\n    its(:stdout) { should match(/^mysqld .*MariaDB/i) }\n  end\nend\n```\n\nThe same applies to `its_container` blocks.\n\n### Run HTTP Tests Using Infrataster\n\n```ruby\n# require 'dockerspec/serverspec' # Only if you want to run both types of tests\nrequire 'dockerspec/infrataster'\n\ndescribe docker_run('nginx') do\n  describe server(described_container) do # Infrataster\n\n    describe http('/') do\n      it 'responds content including \"Welcome to nginx!\"' do\n        expect(response.body).to include 'Welcome to nginx!'\n      end\n\n      it 'responds as \"nginx\" server' do\n        expect(response.headers['server']).to match(/nginx/i)\n      end\n    end\n\n  end\nend\n```\nSee the [Infrataster Resources documentation](http://www.rubydoc.info/gems/infrataster#Resources) for more information.\n\n### Run HTTP Tests Using Capybara\n\nIn the following example we set the *admin* password and log in in a hypothetical web application:\n\n```ruby\nrequire 'dockerspec/infrataster'\n\ndescribe docker_build('.', tag: 'mywebapp') do\n  describe docker_run('mywebapp') do\n\n    describe server(described_container) do\n      describe capybara('/') do\n        let(:password) { '4dm1nP4ssw0rd' }\n\n        describe 'on /setup' do\n          before { visit '/setup' }\n\n          it 'contains \"Configure the password\"' do\n            expect(page).to have_content 'Configure the password'\n          end\n\n          it 'sets the admin password' do\n            fill_in 'Password', with: password\n            fill_in 'Confirm Password', with: password\n            click_button 'Set password'\n          end\n        end\n\n        describe 'on /login' do\n          before { visit '/login' }\n\n          it 'logs in as admin' do\n            expect(page).to have_content 'sign in'\n            fill_in 'User name', with: 'admin'\n            fill_in 'Password', with: password\n            click_button 'Sig in'\n          end\n        end\n\n        describe 'on /' do\n          before { visit '/' }\n\n          it 'is logged id' do\n            expect(page).to have_content 'Welcome admin!'\n          end\n        end\n\n      end\n    end\n\n  end\nend\n```\n\nSee the [Capybara DSL documentation](http://www.rubydoc.info/gems/capybara#The_DSL) for more information.\n\n### Run Database Tests Using `infrataster-plugin-mysql` Gem with Docker Compose\n\nYou need to include the `infrataster-plugin-mysql` gem in your *Gemfile*:\n\n```ruby\n# Gemfile\n\n# gem [...]\ngem 'infrataster-plugin-mysql', '~\u003e 0.2.0'\n```\n\nA *docker-compose.yml* file example with a database:\n\n```yaml\nmyapp:\n  image: myapp\n  links:\n  - db:mysql\n  ports:\n  - 8080:80\n\ndb:\n  image: mariadb\n  environment:\n  - MYSQL_ROOT_PASSWORD=example\n```\n\nThe file with the tests:\n\n```ruby\nrequire 'dockerspec/infrataster'\nrequire 'infrataster-plugin-mysql'\n\ndescribe docker_compose('docker-compose.yml', wait: 60) do\n\n  its_container(:db, mysql: { user: 'root', password: 'example' }) do\n    describe server(described_container) do # Infrataster\n\n      describe mysql_query('SHOW STATUS') do\n        it 'returns positive uptime' do\n          row = results.find { |r| r['Variable_name'] == 'Uptime' }\n          expect(row['Value'].to_i).to be \u003e 0\n        end\n      end\n\n      describe mysql_query('SHOW DATABASES') do\n        it 'includes `myapp` database' do\n          databases = results.map { |r| r['Database'] }\n          expect(databases).to include('myapp')\n        end\n      end\n\n    end\n  end\nend\n```\n\n### Run Different Tests on Each Platform\n\nSometimes, you may want to be able to run different tests depending on the platform. You can use Serverspec's `os` helper method for that:\n\n```ruby\nrequire 'dockerspec/serverspec'\n\ndescribe docker_build('.', tag: 'mywebapp') do\n  describe docker_run('mywebapp') do\n    case os[:family]\n    when 'debian'\n\n      describe file('/etc/debian_version') do\n        it { should exist }\n      end\n\n      # [...]\n\n    when 'alpine'\n\n      describe file('/etc/alpine-release') do\n        it { should exist }\n      end\n\n      # [...]\n\n    end\n  end\nend\n```\n\nFor more details, see [Serverspec documenation on how to get OS information](http://serverspec.org/advanced_tips.html#how-to-get-os-information).\n\n### Real-world Examples\n\n* [`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)).\n* [`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.\n* [`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)).\n* [`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)).\n* [`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.\n\n### Prepare Your Ruby Environment\n\nIf you are new to Ruby, you can follow these steps:\n\n#### 1. Create a **Gemfile**:\n\n```ruby\n# Gemfile\n\nsource 'https://rubygems.org'\n\ngem 'dockerspec', '~\u003e 0.5.0'\n```\n\n#### 2. Create the *spec/* directory:\n\n```\n$ mkdir spec\n```\n\n#### 3. Add your tests to a file with the *spec/myapp_spec.rb* format:\n\nWith this gem, you can use both [Serverspec](http://serverspec.org/) and [Infrataster](https://github.com/ryotarai/infrataster) tests.\n\nIf you just want to use [Serverspec](http://serverspec.org/) tests:\n\n```ruby\nrequire 'dockerspec/serverspec'\n```\n\nIf you just want to use [Infrataster](https://github.com/ryotarai/infrataster) tests:\n\n```ruby\nrequire 'dockerspec/infrataster'\n```\n\nBut, of course, you can use both types of tests if you want:\n\n```ruby\nrequire 'dockerspec/serverspec'\nrequire 'dockerspec/infrataster'\n```\n\nFor example, you can create a file in *spec/myapp_spec.rb* with the following content:\n\n```ruby\n# spec/myapp_spec.rb\n\nrequire 'dockerspec/serverspec'\n\ndescribe 'My Dockerfile' do\n  describe docker_build('.') do\n    # [...]\n    describe docker_run(described_image) do\n      # [...]\n    end\n  end\nend\n```\n\n#### 4. Install the gems:\n\n```\n$ bundle\n```\n\n#### 5. Run the tests:\n\n```\n$ bundle exec rspec\n```\n\n### Travis CI Configuration Example\n\n**.travis.yml** file example:\n\n```yaml\nlanguage: ruby\n\nsudo: required\n\nservices: docker\n\nscript: travis_retry bundle exec rspec\n```\n\n### CircleCI Configuration Example\n\n**circle.yml** file example:\n\n```yaml\nmachine:\n  services:\n  - docker\n  ruby:\n    version: 2.2.3\n\ntest:\n  override:\n  - bundle exec rspec\n```\n\n## Testing\n\nSee [TESTING.md](https://github.com/zuazo/dockerspec/blob/master/TESTING.md).\n\n## Contributing\n\nPlease do not hesitate to [open an issue](https://github.com/zuazo/dockerspec/issues/new) with any questions or problems.\n\nSee [CONTRIBUTING.md](https://github.com/zuazo/dockerspec/blob/master/CONTRIBUTING.md).\n\n## TODO\n\nSee [TODO.md](https://github.com/zuazo/dockerspec/blob/master/TODO.md).\n\n## License and Author\n\n|                      |                                          |\n|:---------------------|:-----------------------------------------|\n| **Author:**          | [Xabier de Zuazo](https://github.com/zuazo) (\u003cxabier@zuazo.org\u003e)\n| **Contributor:**     | [John Meichle](https://github.com/jmeichle)\n| **Copyright:**       | Copyright (c) 2015-2016 Xabier de Zuazo\n| **License:**         | Apache License, Version 2.0\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n    \n        http://www.apache.org/licenses/LICENSE-2.0\n    \n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","funding_links":[],"categories":["Development with Docker","Ruby","Tools"],"sub_categories":["Testing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuazo%2Fdockerspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzuazo%2Fdockerspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuazo%2Fdockerspec/lists"}