In a Dockerfile, what happens to `docker build` when a `RUN` test command exits non-zero?

### What a RUN step actually does A `RUN` instruction in a Dockerfile starts a container from the current stage's filesystem, executes one command inside it, waits for that process to finish, and commits the resulting filesystem as a new read-only image layer. The commit happens **only** if the process exited with status 0. Any other status aborts the entire build; the builder prints a line of the shape ``` ERROR: process "/bin/sh -c bundle exec rspec" did not complete successfully: exit code: 1 ``` and `docker build` returns non-zero to whatever invoked it. Nothing is tagged, and the failing step's container is discarded. That single rule is the entire reason a test suite can live inside an image build. Test runners already signal failure the Unix way — a non-zero exit — so `RUN <run the suite>` needs no integration of any kind to make a red suite stop the pipeline before an image exists to push. ### Shell form is where exit codes get lost `RUN bundle exec rspec` is *shell form*: the builder actually runs `/bin/sh -c "bundle exec rspec"`. The step's status is the shell's status, which is the status of the **last** command on that line. Three ways that silently disarms the gate: - `RUN bundle exec rspec | tee /tmp/test.log` — the reported status is `tee`'s, essentially always 0. Put a `SHELL ["/bin/sh", "-o", "pipefail", "-c"]` instruction above it so the pipeline reports the first failure instead (note that busybox `sh`, the default shell in Alpine-based images, does not support `pipefail`; those images need `bash` installed or a restructured command). - `RUN bundle exec rspec || true` — deliberately swallows the failure. Sometimes intentional, when you want the report files and will assert the result later, but then something else must assert it. - `RUN bundle exec rspec; echo done` — the `;` discards the status the same way. Exec form, `RUN ["bundle", "exec", "rspec"]`, skips the shell entirely: no globbing, no variable expansion, and the process's own status is the step's status. ### The build cache decides whether the tests run at all A `RUN` step whose cache key is unchanged is not executed — the builder reuses the layer it produced last time. The cache key is built from the instruction text and the state of everything above it, so a test step re-runs only when something before it changed. That is usually exactly what you want, but it makes ordering load-bearing: copy the source in *before* the test step, so a source change invalidates it. Otherwise you get the worst outcome available — a green build whose suite was a cache hit. `--no-cache` disables caching for the whole build; `docker buildx build --no-cache-filter test` disables it for one named stage; varying a `--build-arg` used in that stage also busts it. ### Worked example A chat-message fan-out worker written in Ruby, 1,847 examples in its suite: ```dockerfile FROM ruby:3.3-bookworm AS test WORKDIR /app COPY Gemfile Gemfile.lock ./ RUN bundle install COPY . . RUN bundle exec rspec ``` The `bundle install` layer is cached across builds because the two dependency files rarely change; editing a worker source file invalidates the `COPY . .` layer and therefore re-runs the suite. Three failures out of 1,847 and the build stops on that last step — the build log carries the failure output, and no image exists. ### What it costs you A build that fails on the test step produces no image and no files on the host: everything the suite wrote lives in a layer that was never committed. Your only artefact is the build log, which is why teams that want JUnit XML or coverage out of the run need an explicit export step rather than the exit code alone. There is also a scheduling difference worth knowing: the builder runs independent stages concurrently, so build output from a test step can interleave with other stages' output in the log. Finally, remember which exit code you are looking at. The status that matters here is the one from the test process inside the build. It is not the same as the exit code of a container you later start from the finished image, and it is not the `docker build` process's own status — that is simply 1 when any step failed.