kitchen-docker 3.3.0 → 3.3.3

data/spec/file_helper_spec.rb

@@ -0,0 +1,110 @@
+#
+# 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.
+#
+
+require "spec_helper"
+require "tmpdir"
+
+describe Kitchen::Docker::Helpers::FileHelper do
+  around do |example|
+    Dir.mktmpdir { |dir| @dir = dir; example.run }
+  end
+
+  describe "#create_temp_file" do
+    it "writes the contents" do
+      path = File.join(@dir, "docker-abc.sh")
+      helper.create_temp_file(path, "echo hi\n")
+      expect(File.read(path)).to eq "echo hi\n"
+    end
+
+    it "creates the parent directory" do
+      # Container#execute writes to ./.kitchen/temp, which does not exist on a
+      # fresh checkout.
+      path = File.join(@dir, ".kitchen", "temp", "docker-abc.sh")
+      helper.create_temp_file(path, "echo hi\n")
+      expect(File.read(path)).to eq "echo hi\n"
+    end
+
+    it "replaces the contents of an existing file" do
+      path = File.join(@dir, "docker-abc.sh")
+      File.write(path, "old and longer content")
+      helper.create_temp_file(path, "new\n")
+      expect(File.read(path)).to eq "new\n"
+    end
+
+    it "leaves no open handle behind" do
+      path = File.join(@dir, "docker-abc.sh")
+      before = ObjectSpace.each_object(File).count { |f| !f.closed? }
+      helper.create_temp_file(path, "echo hi\n")
+      expect(ObjectSpace.each_object(File).count { |f| !f.closed? }).to eq before
+    end
+
+    # Every one of these used to raise "undefined method 'close' for an instance
+    # of String": the open failed, `file` was still the path, and the ensure
+    # tried to close it. The real cause never reached the user, who saw a Ruby
+    # NoMethodError reported as a Docker failure.
+    context "when the file cannot be written" do
+      it "reports a parent that is not a directory" do
+        # ".kitchen" existing as a file rather than a directory. The exact errno
+        # differs by platform -- macOS reports EEXIST from mkdir here, Linux
+        # ENOTDIR -- so the assertion is that the underlying cause reaches the
+        # user at all, which is what used to be lost.
+        blocker = File.join(@dir, "kitchen")
+        File.write(blocker, "not a directory")
+        path = File.join(blocker, "temp", "docker-abc.sh")
+
+        expect { helper.create_temp_file(path, "echo hi") }
+          .to raise_error(RuntimeError, /Failed to write temp file.*Error Details: \S+.*#{Regexp.escape(blocker)}/m)
+      end
+
+      it "reports a directory it may not write to" do
+        readonly = File.join(@dir, "readonly")
+        Dir.mkdir(readonly)
+        File.chmod(0o500, readonly)
+
+        begin
+          expect { helper.create_temp_file(File.join(readonly, "docker-abc.sh"), "echo hi") }
+            .to raise_error(RuntimeError, /Failed to write temp file.*Permission denied/m)
+        ensure
+          File.chmod(0o700, readonly)
+        end
+      end
+
+      it "reports a target that is itself a directory" do
+        target = File.join(@dir, "isadir")
+        Dir.mkdir(target)
+
+        expect { helper.create_temp_file(target, "echo hi") }
+          .to raise_error(RuntimeError, /Failed to write temp file/)
+      end
+
+      it "names the path it could not write" do
+        # The old message said only "Failed to write temp file", which did not
+        # say which one.
+        path = File.join(@dir, "isadir")
+        Dir.mkdir(path)
+
+        expect { helper.create_temp_file(path, "echo hi") }
+          .to raise_error(RuntimeError, /#{Regexp.escape(path)}/)
+      end
+
+      it "never raises NoMethodError" do
+        blocker = File.join(@dir, "kitchen")
+        File.write(blocker, "not a directory")
+
+        expect { helper.create_temp_file(File.join(blocker, "x.sh"), "echo hi") }
+          .not_to raise_error(NoMethodError)
+      end
+    end
+  end
+end

data/spec/image_helper_spec.rb

@@ -0,0 +1,181 @@
+#
+# 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.
+#
+
+require "spec_helper"
+
+describe Kitchen::Docker::Helpers::ImageHelper do
+  describe "#parse_image_id" do
+    # Docker has changed how it reports the built image's id several times, and
+    # each change has broken this parser. Every format the driver claims to
+    # support gets a case here, against output copied from a real build.
+    {
+      "Docker 29.7 with BuildKit" =>
+        [DockerOutput::BUILD_29_7_BUILDKIT, DockerOutput::BUILD_29_7_IMAGE_ID],
+      "BuildKit emitting 'writing image'" =>
+        [DockerOutput::BUILD_BUILDKIT_WRITING_IMAGE, DockerOutput::BUILD_BUILDKIT_WRITING_IMAGE_ID],
+      "the pre-BuildKit builder" =>
+        [DockerOutput::BUILD_LEGACY, DockerOutput::BUILD_LEGACY_IMAGE_ID],
+    }.each do |description, (output, expected_id)|
+      context "with output from #{description}" do
+        it "finds the image id" do
+          expect(helper.parse_image_id(output)).to eq expected_id
+        end
+
+        it "returns something that looks like an image id" do
+          # Two of the three patterns pull the id out with a bare `split.last`,
+          # which will return whatever trailing token a matching line happens to
+          # end with. Asserting the shape catches a match on the wrong line.
+          expect(helper.parse_image_id(output)).to match(/\A(sha256:[0-9a-f]{64}|[0-9a-f]{12})\z/)
+        end
+      end
+    end
+
+    it "fails loudly when the output holds no image id" do
+      # Returning nil here would put nil into state[:image_id] and fail much
+      # later, while `docker run` complained about an empty image name.
+      expect { helper.parse_image_id("#1 [internal] load build definition\n#1 DONE 0.0s\n") }
+        .to raise_error(Kitchen::ActionFailed, /Could not parse Docker build output/)
+    end
+
+    it "fails loudly on empty output" do
+      expect { helper.parse_image_id("") }
+        .to raise_error(Kitchen::ActionFailed, /Could not parse Docker build output/)
+    end
+
+    it "prefers the last id in the output" do
+      # The scan runs in reverse so that a rebuild's final export wins over
+      # anything earlier in the log.
+      doubled = DockerOutput::BUILD_BUILDKIT_WRITING_IMAGE + DockerOutput::BUILD_29_7_BUILDKIT
+      expect(helper.parse_image_id(doubled)).to eq DockerOutput::BUILD_29_7_IMAGE_ID
+    end
+  end
+
+  describe "#build_image" do
+    # build_image writes a temp Dockerfile and shells out. Stubbing the shell-out
+    # leaves the part worth testing: the command line it assembles.
+    let(:built) { [] }
+
+    def build(config = {})
+      h = helper({ build_tempdir: ".", build_context: false, use_cache: true }.merge(config))
+      allow(h).to receive(:docker_command) do |cmd, _opts|
+        built << cmd
+        DockerOutput::BUILD_29_7_BUILDKIT
+      end
+      h.build_image({}, "FROM alpine:3.20\n")
+      argv(built.last)
+    end
+
+    it "builds, reading the Dockerfile from stdin when there is no build context" do
+      expect(build).to eq %w{build -}
+    end
+
+    it "passes a build context as the final argument when one is configured" do
+      expect(build(build_context: true).last).to eq "."
+    end
+
+    it "names the Dockerfile with -f when there is a build context" do
+      expect(build(build_context: true)).to include "-f"
+    end
+
+    it "disables the cache when use_cache is false" do
+      expect(build(use_cache: false)).to include "--no-cache"
+    end
+
+    it "uses the cache when use_cache is true, as the driver defaults it" do
+      expect(build).not_to include "--no-cache"
+    end
+
+    it "passes docker_platform through" do
+      expect(build(docker_platform: "linux/arm64")).to include "--platform=linux/arm64"
+    end
+
+    it "appends build_options" do
+      expect(build(build_options: { "build-arg" => "VERSION=1.2.3" }))
+        .to include "--build-arg=VERSION=1.2.3"
+    end
+
+    it "returns the parsed image id" do
+      h = helper(build_tempdir: ".", build_context: false, use_cache: true)
+      allow(h).to receive(:docker_command).and_return(DockerOutput::BUILD_29_7_BUILDKIT)
+      expect(h.build_image({}, "FROM alpine:3.20\n")).to eq DockerOutput::BUILD_29_7_IMAGE_ID
+    end
+
+    it "removes the temp Dockerfile even when the build fails" do
+      # A failed build that leaves Dockerfile-kitchen files behind pollutes the
+      # cookbook directory, and they end up in the next build's context.
+      before = Dir.glob("Dockerfile-kitchen*")
+      h = helper(build_tempdir: ".", build_context: false, use_cache: true)
+      allow(h).to receive(:docker_command).and_raise(Kitchen::ShellOut::ShellCommandFailed, "boom")
+      expect { h.build_image({}, "FROM alpine:3.20\n") }.to raise_error(Kitchen::ShellOut::ShellCommandFailed)
+      expect(Dir.glob("Dockerfile-kitchen*")).to eq before
+    end
+  end
+
+  describe "#image_in_use?" do
+    let(:image_id) { "sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc" }
+
+    def helper_seeing(output)
+      h = helper
+      @asked = nil
+      allow(h).to receive(:docker_command) { |cmd, _opts = {}| @asked = cmd; output }
+      h
+    end
+
+    it "reports the image as in use when a container references it" do
+      expect(helper_seeing("331a7cd151e4\n").image_in_use?(image_id: image_id)).to be true
+    end
+
+    it "reports the image as free when nothing references it" do
+      expect(helper_seeing("").image_in_use?(image_id: image_id)).to be false
+    end
+
+    it "reports the image as free when state names no image" do
+      h = helper
+      expect(h).not_to receive(:docker_command)
+      expect(h.image_in_use?({})).to be false
+    end
+
+    it "asks docker to filter, rather than searching ps output for the id" do
+      # `docker ps -a` abbreviates the IMAGE column to twelve characters, so
+      # searching it for the full sha256 digest never matched and the guard
+      # was always false.
+      h = helper_seeing("331a7cd151e4\n")
+      h.image_in_use?(image_id: image_id)
+      expect(@asked).to eq "ps -a -q --filter ancestor=#{image_id}"
+    end
+
+    it "does not mistake a warning on stderr for a container" do
+      expect(helper_seeing("WARNING: something happened\n").image_in_use?(image_id: image_id))
+        .to be false
+    end
+  end
+
+  describe "#remove_image" do
+    let(:state) { { image_id: "sha256:abc" } }
+
+    it "removes the image when nothing is using it" do
+      h = helper
+      allow(h).to receive(:image_in_use?).and_return(false)
+      expect(h).to receive(:docker_command).with("rmi sha256:abc")
+      h.remove_image(state)
+    end
+
+    it "leaves the image alone when a container still references it" do
+      h = helper
+      allow(h).to receive(:image_in_use?).and_return(true)
+      expect(h).not_to receive(:docker_command)
+      h.remove_image(state)
+    end
+  end
+end

data/spec/linux_container_spec.rb

@@ -0,0 +1,252 @@
+#
+# 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.
+#
+
+require "spec_helper"
+require "tmpdir"
+
+describe Kitchen::Docker::Container::Linux do
+  around do |example|
+    Dir.mktmpdir do |dir|
+      @tmpdir = dir
+      @public_key = File.join(dir, "docker_id_rsa.pub")
+      File.write(@public_key, "ssh-rsa AAAAB3NzaC1yc2E kitchen_docker_key\n")
+      example.run
+    end
+  end
+
+  def container(config = {})
+    described_class.new({
+      image: "ubuntu:24.04",
+      platform: "ubuntu",
+      username: "kitchen",
+      public_key: @public_key,
+      private_key: File.join(@tmpdir, "docker_id_rsa"),
+    }.merge(config))
+  end
+
+  describe "#parse_container_ssh_port" do
+    def port(output)
+      container.send(:parse_container_ssh_port, output)
+    end
+
+    it "reads the published port from a dual-stack daemon" do
+      expect(port(DockerOutput::PORT_DUAL_STACK)).to eq DockerOutput::PUBLISHED_PORT
+    end
+
+    it "reads the published port from an IPv4-only daemon" do
+      expect(port(DockerOutput::PORT_IPV4_ONLY)).to eq DockerOutput::PUBLISHED_PORT
+    end
+
+    # `_host, port = output.split(":")` assumes the host is everything before
+    # the first colon. On IPv6 output the first two fields are "[" and "", so
+    # the port becomes "".to_i -- and `to_i` never raises, so the method's
+    # rescue clause cannot fire. Test Kitchen is then handed port 0 and fails
+    # far away from here, complaining that SSH was refused.
+    it "reads the published port from an IPv6-only daemon" do
+      expect(port(DockerOutput::PORT_IPV6_ONLY)).to eq DockerOutput::PUBLISHED_PORT
+    end
+
+    it "refuses to report a port it could not parse" do
+      expect { port("") }.to raise_error(Kitchen::ActionFailed)
+    end
+
+    it "reads the published port when docker names the host" do
+      expect(port("localhost:52239\n")).to eq DockerOutput::PUBLISHED_PORT
+    end
+
+    it "refuses to report a port from output with no port in it" do
+      expect { port("no public port '22/tcp' published\n") }
+        .to raise_error(Kitchen::ActionFailed, /Could not parse Docker port output/)
+    end
+
+    it "names the output it could not parse" do
+      # The previous message said only that parsing failed, which left nobody
+      # any way to tell what docker had actually printed.
+      expect { port("surprising\n") }.to raise_error(Kitchen::ActionFailed, /surprising/)
+    end
+
+    it "never returns a port that cannot be connected to" do
+      # The invariant behind both pending examples above: whatever this returns
+      # has to be usable. Zero is not.
+      expect(port(DockerOutput::PORT_DUAL_STACK)).to be_between(1, 65_535)
+    end
+  end
+
+  describe "#container_ssh_port" do
+    it "uses port 22 directly on the internal Docker network" do
+      # On the Docker network the container is addressed by its own IP, so the
+      # published mapping is irrelevant -- and asking for it would fail.
+      c = container(use_internal_docker_network: true)
+      expect(c).not_to receive(:docker_command)
+      expect(c.send(:container_ssh_port, {})).to eq 22
+    end
+
+    it "raises a useful error when docker reports no mapping" do
+      c = container
+      allow(c).to receive(:docker_command).and_raise(StandardError, "no public port")
+      expect { c.send(:container_ssh_port, container_id: "abc") }
+        .to raise_error(Kitchen::ActionFailed, /no ssh port mapped/)
+    end
+  end
+
+  describe "#dockerfile" do
+    subject(:dockerfile) { container.send(:dockerfile) }
+
+    it "starts from the configured image" do
+      expect(dockerfile.lines.first.strip).to eq "FROM ubuntu:24.04"
+    end
+
+    it "authorises the generated public key" do
+      # Without this line the container builds and starts, and then every
+      # connection is refused -- the single most confusing way for this driver
+      # to fail.
+      expect(dockerfile).to match(%r{>> /home/kitchen/\.ssh/authorized_keys})
+    end
+
+    it "escapes the public key so a shell cannot split it" do
+      # The key contains spaces, and it is appended with `RUN echo <key> >> ...`.
+      run_line = dockerfile.lines.grep(/authorized_keys/).last
+      expect(argv(run_line.sub(/\ARUN /, ""))).to include "ssh-rsa AAAAB3NzaC1yc2E kitchen_docker_key"
+    end
+
+    it "creates the login user" do
+      expect(dockerfile).to match(/useradd .*kitchen/)
+    end
+
+    it "puts root's home in the right place" do
+      expect(container(username: "root").send(:dockerfile)).to match(%r{>> /root/\.ssh/authorized_keys})
+    end
+
+    it "appends each provision_command as its own RUN line" do
+      generated = container(provision_command: ["apt-get install -y dnsutils", "apt-get install -y telnet"])
+        .send(:dockerfile)
+      expect(generated).to include "RUN apt-get install -y dnsutils\n"
+      expect(generated).to include "RUN apt-get install -y telnet\n"
+    end
+
+    it "accepts a single provision_command" do
+      expect(container(provision_command: "echo hi").send(:dockerfile)).to include "RUN echo hi\n"
+    end
+
+    it "ends with a newline" do
+      # A Dockerfile whose last line lacks a newline loses that instruction on
+      # some builders.
+      expect(dockerfile).to end_with "\n"
+    end
+
+    it "carries the proxy configuration into the image" do
+      expect(container(http_proxy: "http://proxy:8080").send(:dockerfile))
+        .to include "ENV http_proxy=http://proxy:8080"
+    end
+
+    context "when a custom dockerfile is configured" do
+      it "uses it verbatim, rendered through ERB" do
+        path = File.join(@tmpdir, "Dockerfile")
+        File.write(path, "FROM <%= @image %>\nRUN echo <%= @username %>\n")
+        expect(container(dockerfile: path).send(:dockerfile))
+          .to eq "FROM ubuntu:24.04\nRUN echo kitchen\n"
+      end
+
+      it "does not append the generated SSH setup to it" do
+        # The custom Dockerfile owns the whole image; silently appending would
+        # overwrite what the author set up.
+        path = File.join(@tmpdir, "Dockerfile")
+        File.write(path, "FROM scratch\n")
+        expect(container(dockerfile: path).send(:dockerfile)).not_to include "authorized_keys"
+      end
+    end
+  end
+
+  describe "#execute" do
+    # The command is staged as a script under .kitchen/temp and uploaded. That
+    # local copy has to go whether or not the rest of the run works, or a failing
+    # converge leaves a file behind on every attempt.
+    def container_in(dir, &upload)
+      c = container
+      allow(c).to receive(:create_dir_on_container)
+      allow(c).to receive(:replace_env_variables) { |_cfg, path| path }
+      allow(c).to receive(:container_exec).and_return("ok")
+      allow(c).to receive(:upload, &(upload || ->(*) { nil }))
+      allow(Dir).to receive(:pwd).and_return(dir)
+      c
+    end
+
+    around do |example|
+      Dir.chdir(@tmpdir) { example.run }
+    end
+
+    it "removes the staged script once the command has run" do
+      c = container_in(@tmpdir)
+      c.execute("echo hi")
+      expect(Dir.glob(".kitchen/temp/docker-*.sh")).to be_empty
+    end
+
+    it "removes the staged script when the upload fails" do
+      c = container_in(@tmpdir) { raise "upload exploded" }
+      expect { c.execute("echo hi") }.to raise_error(/Failed to execute command/)
+      expect(Dir.glob(".kitchen/temp/docker-*.sh")).to be_empty
+    end
+
+    it "removes the staged script when the command itself fails" do
+      c = container_in(@tmpdir)
+      allow(c).to receive(:container_exec).and_raise("command exploded")
+      expect { c.execute("echo hi") }.to raise_error(/Failed to execute command/)
+      expect(Dir.glob(".kitchen/temp/docker-*.sh")).to be_empty
+    end
+
+    it "uploads the command as the contents of the script" do
+      uploaded = nil
+      c = container_in(@tmpdir) { |local, _remote| uploaded = ::File.read(local) }
+      c.execute("echo hi")
+      expect(uploaded).to eq "echo hi"
+    end
+  end
+
+  describe "#generate_keys" do
+    it "writes a usable key pair when none exists" do
+      private_key = File.join(@tmpdir, "generated")
+      public_key = File.join(@tmpdir, "generated.pub")
+      container(private_key: private_key, public_key: public_key).send(:generate_keys)
+
+      expect(File.read(public_key)).to start_with "ssh-rsa "
+      expect { OpenSSL::PKey::RSA.new(File.read(private_key)) }.not_to raise_error
+    end
+
+    it "leaves an existing key pair alone" do
+      # Regenerating would invalidate the authorized_keys baked into images
+      # that were already built.
+      private_key = File.join(@tmpdir, "docker_id_rsa")
+      File.write(private_key, "existing private key")
+      before = File.read(@public_key)
+
+      container(private_key: private_key).send(:generate_keys)
+
+      expect(File.read(@public_key)).to eq before
+      expect(File.read(private_key)).to eq "existing private key"
+    end
+
+    it "regenerates when only one half of the pair is present" do
+      # A half-written pair cannot authenticate, so keeping it would strand the
+      # user with a container they can never reach.
+      File.delete(@public_key)
+      private_key = File.join(@tmpdir, "docker_id_rsa")
+      File.write(private_key, "orphaned private key")
+
+      container(private_key: private_key).send(:generate_keys)
+
+      expect(File.read(@public_key)).to start_with "ssh-rsa "
+      expect(File.read(private_key)).not_to eq "orphaned private key"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -19,8 +19,34 @@ require "rspec"
 require "rspec/its"
 
 require "kitchen/driver/docker"
+require "kitchen/transport/docker"
 
+Dir[File.join(__dir__, "support", "**", "*.rb")].sort.each { |f| require f }
+
+# These specs never talk to a Docker daemon. Everything this gem does is turn
+# configuration into Dockerfiles and `docker` command lines, and turn Docker's
+# output back into ids and ports, so all of it can be exercised as pure string
+# work. Anything that genuinely needs a daemon belongs in the Test Kitchen
+# integration suites -- see CONTRIBUTING.md.
 RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    # Fail if an example stubs a method the real object does not have. Without
+    # this, a rename in lib/ leaves the specs stubbing a method that no longer
+    # exists and passing while the driver is broken.
+    mocks.verify_partial_doubles = true
+  end
+
+  # Surface deprecations as failures rather than warnings that scroll past.
+  config.raise_errors_for_deprecations!
+
+  config.include ArgvHelpers
+  config.include HelperHarness
+  config.include DockerOutput
+
   # Basic configuration
   config.run_all_when_everything_filtered = true
   config.filter_run(:focus)
@@ -30,4 +56,5 @@ RSpec.configure do |config|
   # the seed, which is printed after each run.
   #     --seed 1234
   config.order = "random"
+  Kernel.srand config.seed
 end

data/spec/support/argv.rb

@@ -0,0 +1,55 @@
+#
+# 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.
+#
+
+require "shellwords"
+
+# Helpers for asserting on generated command lines.
+#
+# The driver builds `docker` invocations as single strings and hands them to a
+# shell. Asserting on those strings with `include` is misleading: the string
+# "-v /my volume:/data" contains "-v /my volume:/data", but the shell will tear
+# it into three arguments and Docker will reject it. Splitting the command the
+# way a shell would, and asserting on the resulting argument vector, is the only
+# way for a test to see what Docker will actually receive.
+module ArgvHelpers
+  # Splits a generated command line the way a shell would.
+  #
+  # @param command [String] the command line the driver built
+  # @return [Array<String>] the arguments Docker will actually receive
+  def argv(command)
+    Shellwords.split(command)
+  end
+end
+
+# Asserts that a flag and its value survive shell splitting as one argument
+# each, and remain adjacent.
+#
+# `include` alone cannot express this: an argv of ["-v", "/my", "volume:/data"]
+# includes "-v", and includes "/my", and would satisfy a naive assertion while
+# being completely broken.
+RSpec::Matchers.define :include_consecutive do |*expected|
+  match do |actual|
+    actual.each_cons(expected.length).any? { |window| window == expected }
+  end
+
+  failure_message do |actual|
+    "expected the argument vector to contain #{expected.inspect} as consecutive arguments\n" \
+      "                                 got: #{actual.inspect}"
+  end
+
+  failure_message_when_negated do |actual|
+    "expected the argument vector not to contain #{expected.inspect} as consecutive arguments\n" \
+      "                                     got: #{actual.inspect}"
+  end
+end