Bash-Skripte in Docker-Containern isoliert testen

1. Warum lokale Bash-Tests allein nicht ausreichen

Ein Bash-Skript, das auf dem Entwicklerrechner fehlerfrei läuft, verlässt sich implizit auf die dort installierte Umgebung: eine bestimmte Bash-Version, eine bestimmte Coreutils-Variante (GNU auf den meisten Linux-Distributionen, BSD auf macOS), und eine Reihe von Tools, die einfach schon da sind, weil sie irgendwann einmal installiert wurden. Auf dem Zielsystem, oft einem schlanken Server- oder Container-Image, können genau diese Annahmen scheitern.

Diese Lücke zwischen lokaler Entwicklungsumgebung und Produktionsumgebung ist eine der häufigsten Ursachen für Skripte, die überraschend in der Produktion fehlschlagen, obwohl sie lokal und sogar in einer ersten CI-Testphase erfolgreich liefen. Docker schließt diese Lücke, indem es erlaubt, exakt das Image zu testen, das später auch tatsächlich deployt wird, statt sich auf die zufällige Ausstattung der Entwicklermaschine zu verlassen.

2. Coreutils-Unterschiede gezielt aufdecken: GNU vs. BSD und Versionsdrift

Ein klassisches Beispiel ist der Aufruf date -d, der unter GNU-Coreutils auf den meisten Linux-Distributionen funktioniert, unter der BSD-Variante von macOS aber eine völlig andere Syntax erwartet. Wer ein Skript nur auf macOS entwickelt und testet, bemerkt diesen Unterschied oft erst, wenn das Skript auf einem Linux-Produktionsserver mit einer scheinbar kryptischen Fehlermeldung abbricht.

Auch innerhalb der GNU-Coreutils-Familie gibt es Versionsdrift: Ältere Distributionen wie ein länger nicht aktualisiertes Debian- oder CentOS-Image unterstützen bestimmte Flags von sort, date oder grep noch nicht, die auf einer aktuellen Ubuntu-Version längst Standard sind. Ein Docker-Container mit exakt dem Basis-Image der Zielumgebung deckt solche Versionsunterschiede zuverlässig auf, lange bevor ein echtes Deployment daran scheitert.

# Reproduce the exact target environment locally
docker run --rm -v "$PWD:/app" -w /app debian:12-slim \
  bash -c './deploy.sh --dry-run'

# Compare GNU vs BSD date syntax directly
docker run --rm alpine sh -c "date -d '2026-08-06' '+%s'"   # GNU-style, fails on BSD
docker run --rm -e TZ=UTC ubuntu:24.04 date -d '2026-08-06' '+%s'

3. Fehlende Tools erkennen, bevor sie in Produktion auffallen

Entwicklerrechner sammeln über Jahre eine Vielzahl an Werkzeugen an, die irgendwann für ein anderes Projekt installiert wurden und danach einfach verfügbar bleiben: jq, yq, rsync, ein bestimmtes Kompressionswerkzeug. Ein Skript, das eines dieser Tools voraussetzt, ohne das explizit zu prüfen, läuft lokal klaglos, schlägt aber auf einem schlanken Produktions- oder Container-Image sofort mit command not found fehl.

Ein minimales Basis-Image wie alpine oder ein schlankes debian-slim deckt fehlende Abhängigkeiten zuverlässig auf, weil es bewusst nur die Werkzeuge enthält, die explizit installiert wurden. Ergänzt um eine Prüfung am Skriptanfang, die mit command -v alle benötigten externen Programme verifiziert, bevor der eigentliche Skriptlauf beginnt, lassen sich fehlende Abhängigkeiten schon beim Start klar benennen, statt erst mitten im Ablauf mit einem kryptischen Fehler abzubrechen.

#!/usr/bin/env bash
set -euo pipefail

require() {
  command -v "$1" >/dev/null 2>&1 || {
    echo "Missing required tool: $1" >&2
    exit 1
  }
}

require jq
require rsync
require curl

# Run this check inside the minimal target image, not just locally:
# docker run --rm -v "$PWD:/app" -w /app alpine:3.20 ./deploy.sh

4. Ein dediziertes Test-Image bauen: reproduzierbar statt improvisiert

Statt bei jedem Testlauf ein Basis-Image manuell mit Werkzeugen zu ergänzen, lohnt sich ein dediziertes Dockerfile.test, das exakt die Umgebung nachbildet, in der das Skript später laufen soll, inklusive fixierter Coreutils-Version, Bash-Version und aller externen Tools, die das Skript benötigt. Dieses Image wird einmal gebaut und danach für jeden Testlauf wiederverwendet, statt bei jedem CI-Durchlauf erneut zusammengestellt zu werden.

Wichtig ist, das Test-Image so nah wie möglich am tatsächlichen Produktions-Image zu halten, idealerweise vom selben Basis-Image abgeleitet, ergänzt nur um die für den Testlauf zusätzlich benötigten Werkzeuge wie ein Test-Framework. Ein Test-Image, das deutlich mehr Werkzeuge enthält als das Produktions-Image, verdeckt genau die fehlenden Abhängigkeiten, die eigentlich aufgedeckt werden sollen.

# Dockerfile.test -- mirrors the production base image, plus test tooling
FROM debian:12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
      bash coreutils rsync curl jq bats \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .

CMD ["bats", "test/"]

5. Tests im Container ausführen: lokal und in der CI identisch

Sobald das Test-Image existiert, lässt sich derselbe docker run-Aufruf sowohl lokal auf dem Entwicklerrechner als auch in der CI-Pipeline verwenden, wodurch beide Umgebungen exakt denselben Testlauf ausführen. Das eliminiert die klassische Aussage bei mir lief es, weil lokale Ausführung und CI-Ausführung dieselbe Container-Umgebung teilen, nicht nur denselben Quellcode.

Für schnelle Iteration während der Entwicklung lohnt sich zusätzlich ein Volume-Mount des Projektverzeichnisses in den Container, sodass Codeänderungen sofort ohne erneuten Image-Build sichtbar werden. Für den tatsächlichen CI-Lauf sollte der Code dagegen fest in das Image kopiert werden (COPY statt Volume), damit der Testlauf exakt den Stand testet, der auch tatsächlich committet und ausgeliefert wird.

# Fast local iteration: mount the working tree, rerun without rebuilding
docker run --rm -v "$PWD:/app" -w /app debian:12-slim bats test/

# CI run: build once, test the exact committed state, no live mount
docker build -f Dockerfile.test -t deploy-scripts-test .
docker run --rm deploy-scripts-test

6. Testcontainer in der CI-Pipeline wiederverwenden

Wird das Test-Image nicht bei jedem Pipeline-Lauf neu gebaut, sondern einmalig in einer Container-Registry veröffentlicht und in nachfolgenden Läufen nur noch gezogen, sinkt die Laufzeit der Pipeline erheblich, gerade bei Test-Images mit vielen installierten Paketen. Ein Rebuild lohnt sich dann nur noch, wenn sich die Testabhängigkeiten selbst ändern, nicht bei jeder Codeänderung im getesteten Skript.

In GitLab CI oder GitHub Actions lässt sich dieses Muster mit einem separaten Pipeline-Job umsetzen, der das Test-Image nur baut und veröffentlicht, wenn sich Dockerfile.test geändert hat, während der eigentliche Test-Job das zuletzt veröffentlichte Image einfach zieht und die Tests darin ausführt. Das trennt die Kosten für den Image-Build sauber von den Kosten für den eigentlichen Testlauf.

# .gitlab-ci.yml excerpt: rebuild the test image only when it changes
build-test-image:
  stage: prepare
  script:
    - docker build -f Dockerfile.test -t "$CI_REGISTRY_IMAGE/test:latest" .
    - docker push "$CI_REGISTRY_IMAGE/test:latest"
  rules:
    - changes: [Dockerfile.test]

test:bash:
  stage: test
  image: "$CI_REGISTRY_IMAGE/test:latest"
  script:
    - bats test/

7. Gegen mehrere Basis-Images gleichzeitig testen

Skripte, die auf unterschiedlichen Zielsystemen laufen sollen, etwa auf Debian- und Alpine-basierten Servern gleichzeitig, profitieren davon, die Testsuite gegen mehrere Basis-Images parallel auszuführen, statt sich auf ein einziges Referenzsystem zu verlassen. Eine Matrix-Konfiguration in der CI, die dasselbe Test-Kommando gegen mehrere Images (debian:12-slim, alpine:3.20, ubuntu:24.04) startet, deckt Unterschiede in Coreutils-Version und Shell-Verhalten frühzeitig auf.

Besonders relevant ist das für Skripte, die auf /bin/sh statt fest auf /bin/bash gesetzt sind, da /bin/sh auf Alpine typischerweise auf busybox ash zeigt und nicht alle Bash-Erweiterungen unterstützt. Wer ein Skript ausschließlich auf einem Debian-Container getestet hat, entdeckt solche Unterschiede oft erst, wenn dasselbe Skript versehentlich auf einem Alpine-basierten System landet.

8. Grenzen des Ansatzes: was Docker-Tests nicht abdecken

Docker-basierte Tests decken Unterschiede in installierter Software, Coreutils-Version und Shell-Verhalten zuverlässig ab, prüfen aber nicht automatisch Aspekte, die spezifisch für die eigentliche Zielumgebung sind, etwa Kernel-spezifisches Verhalten, echte Hardware-Ressourcenlimits oder Netzwerktopologien, die sich innerhalb eines Containers nur eingeschränkt nachbilden lassen. Ein Container teilt sich außerdem grundsätzlich den Host-Kernel, weshalb kernelspezifische Unterschiede zwischen Zielsystemen auf diesem Weg nicht sichtbar werden.

Für die überwiegende Mehrheit der Deployment- und Automatisierungsskripte reicht diese Einschränkung in der Praxis kaum, weil die häufigsten Fehlerquellen tatsächlich fehlende Tools, abweichende Coreutils-Versionen und unterschiedliches Shell-Verhalten sind, nicht Kernel-Eigenheiten. Für Skripte mit echten Kernel-Abhängigkeiten, etwa cgroups-Manipulation, bleibt ein Test auf einer echten virtuellen Maschine mit identischem Kernel die zuverlässigere Ergänzung.

9. Docker-Testcontainer im Vergleich zu anderen Testumgebungen

Docker ist nicht die einzige Möglichkeit, eine reproduzierbare Bash-Testumgebung zu schaffen, aber meist die praktikabelste, weil Images sich schnell starten lassen, in nahezu jeder CI-Umgebung nativ unterstützt werden und sich exakt versionieren lassen. Virtuelle Maschinen bieten stärkere Isolation bis auf Kernel-Ebene, sind dafür aber deutlich langsamer zu starten und aufwendiger in der CI zu pflegen.

Die folgende Tabelle ordnet Docker-Testcontainer neben den gängigsten Alternativen ein und zeigt, für welchen Testbedarf welcher Ansatz die richtige Wahl ist, von einfachen Coreutils-Unterschieden bis zu echten Kernel-Abhängigkeiten.

10. Zusammenfassung

11. FAQ: Bash-Skripte in Docker testen: Das Wichtigste auf einen Blick