https://github.com/yegor256/donce
Docker Once: builds a temporary Docker image, runs a temporary Docker container, lets your tests interact with it, terminates and cleans up
https://github.com/yegor256/donce
automated-testing docker ruby testing unit-testing
Last synced: 12 days ago
JSON representation
Docker Once: builds a temporary Docker image, runs a temporary Docker container, lets your tests interact with it, terminates and cleans up
- Host: GitHub
- URL: https://github.com/yegor256/donce
- Owner: yegor256
- License: mit
- Created: 2025-02-06T05:48:00.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-09-25T21:14:28.000Z (21 days ago)
- Last Synced: 2025-09-25T23:32:34.025Z (21 days ago)
- Topics: automated-testing, docker, ruby, testing, unit-testing
- Language: Ruby
- Homepage:
- Size: 148 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Builds Docker image, runs it, and kills
[](https://www.rultor.com/p/yegor256/donce)
[](https://www.jetbrains.com/ruby/)
[](https://github.com/yegor256/donce/actions/workflows/rake.yml)
[](https://www.0pdd.com/p?name=yegor256/donce)
[](https://badge.fury.io/rb/donce)
[](https://codecov.io/github/yegor256/donce?branch=master)
[](https://rubydoc.info/github/yegor256/donce/master/frames)
[](https://hitsofcode.com/view/github/yegor256/donce)
[](https://github.com/yegor256/donce/blob/master/LICENSE.txt)
This small Ruby library helps to build temporary [Docker]
images, run Docker containers, and clean up afterwards — it may be
convenient for automated tests (for example, with [Minitest]):
```ruby
class MyTest < Minitest::Test
def test_prints_hello_world
stdout = donce(
dockerfile: '
FROM ubuntu
CMD echo "Hello, world!"
'
)
assert_equal("Hello, world!\n", stdout)
end
end
```
It's possible to run a Docker image in background mode too:
```ruby
stdout = donce(image: 'ubuntu', command: 'sleep 9999') do |id|
# The "id" is the container id
# The "donce_host()" is the hostname of it
end
```
If you set `DONCE_SUDO` environment variable to `true`, `docker` will
be executed via `sudo`.
## Parameters
Here's a list of the available parameters for `donce`:
* `dockerfile`: Content of the Dockerfile (string or array of strings)
* `home`: Directory with Dockerfile and all other necessary files
* `image`: Name of a Docker image to use (e.g. "ubuntu:22.04")
* `log`: Logging destination (defaults to $stdout)
* `args`: Extra arguments for the docker command
* `env`: Environment variables mapping for the container
* `volumes`: Local to container volumes mapping
* `ports`: Local to container port mapping
* `build_args`: Arguments for docker build (--build-arg)
* `root`: Let user inside the container be "root" (default: false)
* `command`: The command to execute in the container
* `timeout`: Maximum seconds to spend on each docker call (default: 10)
The function `donce_host()` returns the hostname of the host machine that
can be used from within the container.
## How to contribute
Read
[these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
Make sure your build is green before you contribute
your pull request. You will need to have
[Ruby](https://www.ruby-lang.org/en/) 3.0+ and
[Bundler](https://bundler.io/) installed. Then:
```bash
bundle update
bundle exec rake
```
If it's clean and you don't see any error messages, submit your pull request.
[Docker]: https://www.docker.com/
[Minitest]: https://github.com/minitest/minitest