docker.md

How to use ShellSpec with Docker

• Official docker images
• Using ShellSpec docker image
  • 1. Run ShellSpec and your specfiles within container
  • 2. Run simple with helper script and extra hooks
    • Hooks
      • .shellspec-docker/initrc
      • .shellspec-docker/pre-test
      • .shellspec-docker/post-test
  • 3. Using ShellSpec image as parent image
  • 4. Include ShellSpec into another image
• Appendix
  • How to build official ShellSpec docker image yourself

Official docker images

There are official images on the Docker Hub.

Name	Linux	Included	Size
shellspec/shellspec	Alpine	busybox (ash)
shellspec/shellspec:kcov	Alpine	busybox (ash), bash, kcov
shellspec/shellspec-debian	Debian	dash, bash
shellspec/shellspec-debian:kcov	Debian	dash, bash, kcov
shellspec/shellspec-scratch	None	none (shellspec only)

• Version specified images are also available (VERSION: 0.21.0 and above)
  • shellspec/shellspec[-VARIANT]:<VERSION | master>[-kcov]

Using ShellSpec docker image

1. Run ShellSpec and your specfiles within container

# Run docker command on the project root
$ docker run -it --rm -v "$PWD:/src" shellspec/shellspec

# Display help
$ docker run -it --rm -v "$PWD:/src" shellspec/shellspec --help

# Run with kcov (requires kcov supported image)
$ docker run -it --rm -u $(id -u):$(id -g) \
    -v "$PWD:/src" shellspec/shellspec:kcov --kcov

# For users using Docker Desktop for Windows within WSL 1
$ docker run -it --rm -v "$(wslpath -wa .):/src" shellspec/shellspec

2. Run simple with helper script and extra hooks

Use contrib/shellspec-docker helper script.

# Specify the Docker image to use (default: shellspec/shellspec)
$ export SHELLSPEC_DOCKER=shellspec/shellspec

# Run helper script on the project root
$ shellspec-docker

# Display help
$ shellspec-docker --help

# Run with kcov (requires kcov supported image)
$ shellspec-docker --kcov

# Enter the Docker container
$ shellspec-docker -

# Execute command with in the Docker container
$ shellspec-docker - hostname

If you want to run manually.

$ docker run -it --rm --entrypoint=/shellspec-docker \
    -u $(id -u):$(id -g) -v "$PWD:/src" shellspec/shellspec

# For users using Docker Desktop for Windows within WSL 1
$ docker run -it --rm --entrypoint=/shellspec-docker \
    -u $(id -u):$(id -g) -v "$(wslpath -wa .):/src" shellspec/shellspec

Hooks

.shellspec-docker/initrc

This file should be a shell script. You can override docker_run() to changes options, pass environment variables, etc.

.shellspec-docker/pre-test

Invoked before execute shellspec inside of the docker container.

.shellspec-docker/post-test

Invoked after executed shellspec inside of the docker container.

3. Using ShellSpec image as parent image

Example

# Dockerfile
FROM shellspec/shellspec
RUN apk add --no-cache add-your-required-packages
COPY ./ /src

# Build and run at your project root
$ docker build -t your-project-name .
$ docker run -it your-project-name

4. Include ShellSpec into another image

Example

# Dockerfile
FROM buildpack-deps
RUN apt-get update && apt-get install -y add-your-required-packages
COPY --from=shellspec/shellspec-scratch /opt/shellspec /opt/shellspec
ENV PATH /opt/shellspec/:$PATH
WORKDIR /src
ENTRYPOINT [ "shellspec" ]
COPY ./ /src

# Build and run at your project root
$ docker build -t your-project-name .
$ docker run -it your-project-name

Appendix

How to build official ShellSpec docker image yourself

Example

contrib/build.sh .dockerhub/Dockerfile         shellspec
contrib/build.sh .dockerhub/Dockerfile         shellspec kcov
contrib/build.sh .dockerhub/Dockerfile.debian  shellspec-debian
contrib/build.sh .dockerhub/Dockerfile.debian  shellspec-debian kcov
contrib/build.sh .dockerhub/Dockerfile.scratch shellspec-scratch