Skip to content

Test Plundarr deployments ๐Ÿงช๐Ÿดโ€โ˜ ๏ธ

Use the developer testing guide for unit, strict type, helper, workflow, image, generation-matrix, and documentation checks. This page covers optional live deployment tests and their recovery boundaries.

Find a test

Directory Responsibility
generator/ Image resolution, hardened generator smoke checks, and real Compose syntax matrix
helpers/ Offline Make/workflow/policy and cleanup-ownership fixtures
policy/ Build-pin synchronization and image-channel rules
runtime/ Live stack health, VPN/port forwarding, and isolated cleanup acceptance
stubs/ Deterministic command substitutes used only by offline tests
examples/ Secret-free WireGuard/forwarding fixtures used by disposable live tests

Make targets are the normal interface; individual scripts are for focused diagnosis. Stub results do not prove real container health.

Prepare an isolated live test

Replace YOUR-PRESET with one catalog ID and use it consistently. Run mutating tests only with disposable bind-mounted config, media, and downloads on an isolated Docker test daemon, preferably a disposable host or VM. Watchtower and Portainer may access the Docker socket; it must belong to the test environment. Different checkout, project, preset, or Docker context names alone do not isolate host data or sockets.

Caution

make test-e2e and make test-stack replace selected WireGuard and forwarding files with examples before and after validation and can interrupt services. Back up disposable test state and protect credentials. Interrupted commands can leave services or sensitive state behind; inspect before recovery. Never use these targets to diagnose an operator deployment.

The generator revision guide explains selecting the source-built image. Generate the full desired selection before live tests. Supply test credentials privately; never publish .env, wg0.conf, privateerr.env, application databases, or raw private logs.

Check an already-running test stack

make test-vpn PRESET=YOUR-PRESET

This inspects actual Privateerr/Gluetun containers, generated files, tunnel health, and PIA forwarding. When qBittorrent validation is enabled it also checks that its listening port matches the forwarded port. Syntax validation alone proves none of these runtime properties.

Start and test VPN/download services

make test-e2e PRESET=YOUR-PRESET

This stops the selected disposable stack before restoring fixtures, starts the VPN pair and selected download clients, waits for health, and validates the forwarding chain. After either a passing or failing test, it shuts the stack down and restores fixtures only when shutdown succeeds. A failed shutdown preserves the generated VPN files and reports how to retry cleanup; shutdown or restoration errors fail the target. Generate the intended downloader selection first; for example, Usenet-only uses REMOVE_SERVICES=qbittorrent,cleanuparr ADD_SERVICES=sabnzbd. Use nzbget instead for NZBGet, or add either without removal to test combined modes.

Start and test the full stack

make test-stack PRESET=YOUR-PRESET

This stops the selected disposable test stack before restoring fixtures, starts all services, waits for configured healthchecks, and validates VPN/forwarding state. On success, it leaves the stack running with its generated VPN files intact. On failure, it prints status/recent logs, stops the stack, and restores fixtures only after shutdown succeeds. If shutdown fails, it preserves the VPN files; resolve the reported shutdown error, then run make reset-test-stack PRESET=YOUR-PRESET. It is a mutating development test, not a routine health check.

Validate lifecycle cleanup ownership

After lifecycle-helper changes, use the explicitly isolated acceptance test:

test/runtime/test-compose-cleanup-live.sh

It creates uniquely named projects and unrelated sentinels, proves down retains images/volumes, then checks scoped nuke cleanup and restarts to verify retained data. It uses no dist/, repository .env, or PIA credentials. Test teardown deletes only volumes recorded as created by that run, with matching project/run labels; rejected ownership or cleanup failure retains the ledger and fails the test. Never use global pruning.

Restore example files ๐Ÿ“œ

The following commands stop or reset only the explicitly selected disposable test deployment:

Caution

make reset-test-stack stops the selected stack and replaces its VPN files with examples. make restore-vpn-examples replaces those files even while services run, potentially breaking VPN operation. Confirm the preset and isolation before running either.

make reset-test-stack PRESET=YOUR-PRESET
make restore-vpn-examples PRESET=YOUR-PRESET

reset-test-stack uses volume-preserving down. make clean-artifacts removes disposable repository artifacts only. make remove-stack also stops services and removes scoped containers, networks, eligible images, the separate Maraudarr project, and repository-owned build cache; it preserves application volumes, deployment .env, persistent config, and backups. make delete-config is a separate destructive host-config deletion and is not part of routine cleanup. Keep exported backups off-host; named-volume application backups need their own export procedure.