# Tests Two layers: - **`run_tests.sh`** — assertions against `bw_export.sh` using a stateful mock of the Bitwarden CLI (`mock/bw`). Fast, no network, no containers: `mock/curl` answers like an unreachable server, so the log's server probe never leaves the machine. It also checks that every log line has the one format and that no secret, server address or vault name reaches the log. - **`run_ping_tests.sh`** — assertions against the `PING_URL` helpers in `root/usr/local/lib/bw-export/ping.sh`. Also fast, and needs no mock beyond a three-line stub for `curl`. - **`run_notify_tests.sh`** — assertions against the `NOTIFICATION_URL` helper in `root/usr/local/lib/bw-export/notify.sh`, with a stub for `shoutrrr`. - **`run_cron_tests.sh`** — assertions against `entrypoint.sh`: `CRON` scheduling and the one-shot mode, plus the non-root start. - **`run_secrets_tests.sh`** — assertions against `resolve_secret()` in `root/usr/local/lib/bw-export/secrets.sh`: values, `/run/secrets` paths and the `_FILE` variables. - **`run_retention_tests.sh`** — assertions against `root/usr/local/lib/bw-export/retention.sh`, which decides the old backups `KEEP_LAST_BACKUPS` and `KEEP_GFS` delete. Driven with folder names only; nothing is created or deleted. - **`run_vaults_tests.sh`** — several vaults in one run (`BW_VAULTS`), through `bw_export.sh` and the same mock: each vault's folders, key, server and CLI session, a failing vault, inherited and per-vault options, configuration errors, and that no vault's export sees another vault's variables. - **`compose.test.yml` + `e2e-setup.sh`** — a real Vaultwarden 1.37.4 and a bw-export image built from the repo `Dockerfile`, used to validate issue #21 end to end. ## Unit suite ```bash SCRIPT=$PWD/bw_export.sh bash tests/run_tests.sh ``` Expect `FAIL=0`. The suite is only worth anything if it fails on the code it was written against, so as a control: ```bash git show 57aa29d:bw_export.sh > /tmp/orig.sh # before the #21 fixes SCRIPT=/tmp/orig.sh bash tests/run_tests.sh # PASS=61 FAIL=69 git show ae34553:bw_export.sh > /tmp/preattach.sh # #21 fixed, attachments not yet SCRIPT=/tmp/preattach.sh bash tests/run_tests.sh # PASS=77 FAIL=53 git show 5b24f6e:bw_export.sh > /tmp/preexport.sh # vault exports not yet checked SCRIPT=/tmp/preexport.sh bash tests/run_tests.sh # PASS=102 FAIL=28 git show 7346c9d:bw_export.sh > /tmp/preargv.sh # passwords still on the command line SCRIPT=/tmp/preargv.sh bash tests/run_tests.sh # PASS=129 FAIL=7 ``` T15–T19 cover the attachment block: the guard that never fired, and the fact that item and file names used to be pasted into generated shell and executed. T20–T22 cover a download that fails: it has to be counted and reported, not folded into a run that claims success. T23–T24 cover rotation, which must not delete a complete backup to make room for an incomplete one. T25–T28 cover a vault export that fails (the CLI reports it only by its exit status): it is counted and named, the remaining exports still run, the run exits 1, and rotation is skipped. Before this, T27's setup lost both older backups: the failed run's empty folder counted as the newest one. T28 is the control that a full set of successful exports still exits 0. T29–T30 cover a listing the CLI refuses, as it does once a 401 has logged it out: that is not an empty vault, and must not be reported as "No attachments exist". T31–T34 cover how the passwords reach the CLI. A process's command line is readable by every user on the host (`ps`), so the master password goes to `bw unlock` through an environment variable and the export password to `bw export --password` through stdin, where the CLI's prompt reads it. The mock logs every argv and the password each export received, so the tests check both that neither password appears in an argv and that the export got it byte for byte, spaces and quotes included, also when it comes from a file. The prompt is redrawn once per character, so it is kept out of the log. T33 covers what the CLI does when that read comes back empty: exit 0 and no file, which must count as a failed export. T34 checks that an unencrypted export prompts for nothing. TM covers how the legacy `/var/attachment` fallback tells an anonymous volume from a real mount, using mountinfo lines in the formats of rootful Docker and rootless Podman. Against a script without the function it fails once. > `mock/bw` must be executable. On a filesystem that ignores the exec bit > (NTFS/exFAT via FUSE, some network mounts) copy `tests/` to a native Linux > filesystem first, or every test fails with "permission denied". ## Ping suite ```bash bash tests/run_ping_tests.sh ``` Expect `FAIL=0`. It covers the URL building (both placeholders, the appended path segment when there is none, the trailing slash, and the start ping that `{status}` omits) and `send_ping`'s two guarantees: it logs the event without the URL, because that carries the monitor's token, even when the shell is tracing with `set -x` as `send_notification` leaves it, and it returns 0 even when `curl` fails. The last one is the guard for #22. `entrypoint.sh` pings from an `EXIT` trap, and `send_notification` leaves `set -e` on in that shell, so a `curl` failure allowed to escape would make the container exit with curl's status instead of the export's. The library is sourced through `$LIB`, so the suite can be pointed at another implementation as a control. The obvious wrong one — append the event and trust `curl` — fails 30 of the 33: ```bash cat > /tmp/naive.sh <<'EOF' build_ping_url() { printf '%s\n' "$1/$2"; } send_ping() { curl -fsS --retry 3 "${PING_URL}/$1"; } EOF LIB=/tmp/naive.sh bash tests/run_ping_tests.sh # PASS=3 FAIL=30 ``` ## Notify suite ```bash bash tests/run_notify_tests.sh ``` Expect `FAIL=0`. The notification URL carries the service's credentials (a Telegram bot token, a Gotify app token), so the suite checks that it reaches `shoutrrr` through `SHOUTRRR_URL` and never through its argv, which any user on the host can read with `ps`; that it stays out of the log, also under `set -x` and when `shoutrrr` fails with the address in its error; that a failing service leaves the caller's status alone, even under `set -e`; and that an empty message is replaced, since Telegram rejects one and the alert would be lost. The stub records the argv, the environment and the message. As a control, the previous behaviour (print the URL, trace, pass it with `-u`) fails 9 of the 13: ```bash cat > /tmp/old.sh <<'END' send_message() { [[ -z "${NOTIFICATION_URL:-}" ]] && return 0 set -xe echo -e "\nNotification enabled: $NOTIFICATION_URL " "${SHOUTRRR_BIN:-/app/shoutrrr}" send -m "$1" -u "$NOTIFICATION_URL" } END LIB=/tmp/old.sh bash tests/run_notify_tests.sh # PASS=4 FAIL=9 ``` ## End-to-end suite ```bash bash tests/e2e-setup.sh ``` That generates a throwaway CA, starts Vaultwarden behind TLS, builds the image, registers a test account with an API key and an organization, and seeds one personal item (with an attachment) plus one organization item. Everything lands in `tests/e2e/`, which is gitignored. TLS is not optional: the Bitwarden CLI rejects plain-HTTP servers with `Insecure URL not allowed. All URLs must use HTTPS.`, so Vaultwarden sits behind an nginx proxy on `vw.test` and the container trusts the test CA through `NODE_EXTRA_CA_CERTS`. Run an export: ```bash docker compose -f tests/compose.test.yml --env-file tests/e2e/test.env up -d bw-export docker logs -f bwtest-bw-export ``` ### Reproducing issue #21 The bug only appears when the **same** container is restarted — recreating it discards the CLI state in `/app/data.json` and the stale session goes with it. Use `start`, never `up --force-recreate`: ```bash docker compose -f tests/compose.test.yml --env-file tests/e2e/test.env start bw-export ``` To create the dirty state the issue describes, kill a run mid-export so the cleanup trap never fires, then restart: ```bash docker start bwtest-bw-export until docker logs bwtest-bw-export 2>&1 | grep -q 'Vault unlocked'; do sleep 1; done docker kill bwtest-bw-export docker start bwtest-bw-export # logs "Existing session detected. Logging out before starting..." ``` The fixed script recovers. To see the original fail instead, build an image with the pre-fix script and repeat: ```bash git show 57aa29d:bw_export.sh > /tmp/bw_export.orig.sh ``` Add a stale master password on top (change it server-side between two runs, update `tests/e2e/secrets/.bwpassword`) and the original reproduces the reported log exactly: ``` Setting custom server... Logout required before server config update. Unlocking the vault... ERROR: Failed to unlock vault with BW_PASSWORD. ``` ### Checking the entrypoint `entrypoint.sh` is too coupled to the image (`su`, `pkill`, `shoutrrr`) to cover with the mock, so its two behaviours are verified against a container: **It reports failure.** Run with credentials that cannot work and read the exit code, not the log: ```bash docker run --name t -e BW_CLIENTID=bogus -e BW_CLIENTSECRET=bogus \ -e BW_PASSWORD=bogus localhost/bw-export:local docker inspect -f '{{.State.ExitCode}}' t # 1, and 0 before this was fixed ``` **It passes stop signals on.** Interrupt a run and check the export got to clean up after itself: ```bash docker start bwtest-bw-export until docker logs bwtest-bw-export 2>&1 | grep -q 'Vault unlocked'; do sleep 1; done docker stop -t 30 bwtest-bw-export docker logs bwtest-bw-export | grep 'Closing Bitwarden CLI session' # must appear docker inspect -f '{{.State.ExitCode}}' bwtest-bw-export # 143, not 137 ``` 143 means it was asked to stop and did; 137 means it ignored the request and was killed. The next run should then start without logging `Existing session detected`, because nothing was left behind. The cleanup only runs once the `bw` command in flight returns, so on a large vault give `docker stop` more than its default 10 seconds (`-t`, or `stop_grace_period` in compose). **It pings the monitor.** The URL building is unit tested; that the container really reaches out is not. Point it at a listener that records what it is asked for: ```bash python3 -m http.server 8111 & docker run --rm --network host \ -e PING_URL=http://127.0.0.1:8111/ping \ -e BW_CLIENTID=bogus -e BW_CLIENTSECRET=bogus -e BW_PASSWORD=bogus \ localhost/bw-export:local ``` The listener logs `GET /ping/start` and then `GET /ping/1`, in that order. It answers 404 to both, which is useful rather than a problem: the container must log `WARNING: Monitoring ping (...) failed; continuing.` and still exit 1, not 0 and not 22. That is the non-fatal guarantee, seen from outside. ### Teardown ```bash docker rm -f bwtest-bw-export bwtest-vaultwarden bwtest-vw-tls rm -rf tests/e2e ``` Remove the containers before deleting `tests/e2e/` — Vaultwarden holds its SQLite files open and the directory will not delete while it is running.