diff --git a/TEST_PLAN.md b/TEST_PLAN.md
new file mode 100644
index 0000000..8546ed0
--- /dev/null
+++ b/TEST_PLAN.md
@@ -0,0 +1,46 @@
+# Avida-ED App Test Plan
+
+This builder packages the browser apps, so tests should cover two separate layers:
+
+1. Browser app behavior in the canonical repositories.
+2. Packaged executable behavior in this builder.
+
+## Canonical App Tests
+
+The canonical v3 and v4 repositories should own browser-level behavior tests. Current coverage:
+
+- Load the app through Playwright with `?avidaTest=1`.
+- Wait for the Avida worker to start.
+- Import a minimal default experiment.
+- Verify `webGridData` and `webPopulationStats` messages arrive.
+- Assert no browser errors were captured.
+- Exercise the missing-parent-series population-stats regression directly.
+
+Next browser tests to add:
+
+- Inject an ancestor sequence, step several updates, and verify population count changes.
+- Trace an organism with `webOrgTraceBySequence` and verify snapshots are produced.
+- Simulate the freezer offspring delete/rename path that previously caused stale DOM removal.
+- Import a saved workspace containing multiple ancestors and verify all injection responses are handled.
+- Export CSV from empty and populated page states.
+
+## Packaged App Tests
+
+The packaged executable should be validated without depending on visual inspection. The Rust wrapper already logs:
+
+- Local HTTP server URL.
+- HTTP 200/404 responses.
+- WebView page-load start/finish.
+- JavaScript errors, unhandled rejections, and proxied `console.error` output.
+
+Use `tests/smoke_appimage.sh` to run a built AppImage briefly, capture those signals, and fail if the app never loads or JavaScript errors appear.
+
+Recommended Linux smoke matrix:
+
+- `Avida-ED-v3-Linux-x86_64.AppImage`
+- `Avida-ED-v4-Linux-x86_64.AppImage`
+- Run under `xvfb-run` in CI when no display is available.
+- Run once with software GL environment variables for older GPUs:
+  `LIBGL_ALWAYS_SOFTWARE=1 WEBKIT_DISABLE_COMPOSITING_MODE=1`.
+
+The AppImage smoke test intentionally treats timeout exit as success after the app has loaded, because the app is expected to keep running until the window is closed.
diff --git a/tests/smoke_appimage.sh b/tests/smoke_appimage.sh
new file mode 100755
index 0000000..dc5078d
--- /dev/null
+++ b/tests/smoke_appimage.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: tests/smoke_appimage.sh PATH_TO_APPIMAGE [SECONDS]
+
+Runs an Avida-ED AppImage long enough to verify wrapper startup, embedded HTTP
+serving, WebView page load, and absence of proxied JavaScript errors.
+
+The app normally keeps running until its window closes, so timeout exit code 124
+is accepted after the expected load signals appear.
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+appimage="${1:?missing AppImage path}"
+seconds="${2:-20}"
+
+if [[ ! -x "$appimage" ]]; then
+  echo "error: AppImage is missing or not executable: $appimage" >&2
+  exit 2
+fi
+
+tmpdir="$(mktemp -d)"
+logfile="$tmpdir/appimage.log"
+cleanup() {
+  rm -rf "$tmpdir"
+}
+trap cleanup EXIT
+
+cmd=(
+  env
+  LIBGL_ALWAYS_SOFTWARE="${LIBGL_ALWAYS_SOFTWARE:-1}"
+  WEBKIT_DISABLE_COMPOSITING_MODE="${WEBKIT_DISABLE_COMPOSITING_MODE:-1}"
+  "$appimage"
+)
+
+if [[ -z "${DISPLAY:-}" ]] && command -v xvfb-run >/dev/null 2>&1; then
+  cmd=(xvfb-run -a "${cmd[@]}")
+fi
+
+set +e
+timeout "$seconds" "${cmd[@]}" >"$logfile" 2>&1
+status=$?
+set -e
+
+cat "$logfile"
+
+if [[ "$status" -ne 0 && "$status" -ne 124 ]]; then
+  echo "error: AppImage exited before smoke window completed; status=$status" >&2
+  exit "$status"
+fi
+
+if ! grep -q "Avida-ED loading http://127.0.0.1:" "$logfile"; then
+  echo "error: wrapper did not log local HTTP load URL" >&2
+  exit 1
+fi
+
+if ! grep -q "Avida-ED HTTP 200" "$logfile"; then
+  echo "error: embedded HTTP server did not serve any successful response" >&2
+  exit 1
+fi
+
+if ! grep -q "Avida-ED page-load finished" "$logfile"; then
+  echo "error: WebView did not finish loading the app page" >&2
+  exit 1
+fi
+
+if grep -E "Avida-ED WebView (js-error|js-rejection|console-error):" "$logfile"; then
+  echo "error: WebView reported JavaScript errors" >&2
+  exit 1
+fi
+
+echo "AppImage smoke passed: $appimage"