diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 33dc32e1..300537a2 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -41,6 +41,9 @@ dev = [
testpaths = ["src/test"]
pythonpath = ["src"]
asyncio_mode = "auto"
+markers = [
+ "e2e: End-to-end integration tests (require Docker)",
+]
[tool.ruff]
line-length = 88
diff --git a/backend/src/test/e2e/Dockerfile.mock-rss b/backend/src/test/e2e/Dockerfile.mock-rss
new file mode 100644
index 00000000..af4c560a
--- /dev/null
+++ b/backend/src/test/e2e/Dockerfile.mock-rss
@@ -0,0 +1,7 @@
+FROM python:3.11-slim
+RUN pip install --no-cache-dir aiohttp
+COPY mock_rss_server.py /app/
+COPY fixtures/ /app/fixtures/
+WORKDIR /app
+EXPOSE 18888
+CMD ["python", "mock_rss_server.py"]
diff --git a/backend/src/test/e2e/__init__.py b/backend/src/test/e2e/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/backend/src/test/e2e/conftest.py b/backend/src/test/e2e/conftest.py
new file mode 100644
index 00000000..4adea5a4
--- /dev/null
+++ b/backend/src/test/e2e/conftest.py
@@ -0,0 +1,180 @@
+"""Shared fixtures for E2E integration tests.
+
+These tests require Docker (qBittorrent + mock RSS server) and run
+AutoBangumi as a real subprocess with isolated config/data directories.
+
+Run with: cd backend && uv run pytest -m e2e -v
+"""
+
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+import pytest
+
+# ---------------------------------------------------------------------------
+# Auto-skip E2E tests unless explicitly selected
+# ---------------------------------------------------------------------------
+
+E2E_DIR = Path(__file__).parent
+
+
+def pytest_collection_modifyitems(config, items):
+ """Skip E2E tests unless -m e2e is specified."""
+ marker_expr = config.getoption("-m", default="")
+ if "e2e" in marker_expr:
+ return
+ skip = pytest.mark.skip(reason="E2E tests require: pytest -m e2e")
+ for item in items:
+ if "e2e" in item.keywords:
+ item.add_marker(skip)
+
+
+# ---------------------------------------------------------------------------
+# Test credentials (used in setup and login)
+# ---------------------------------------------------------------------------
+
+E2E_USERNAME = "testadmin"
+E2E_PASSWORD = "testpassword123"
+
+# ---------------------------------------------------------------------------
+# Session-scoped fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def e2e_tmpdir(tmp_path_factory):
+ """Session-scoped temp directory for AB config/data isolation."""
+ return tmp_path_factory.mktemp("e2e")
+
+
+@pytest.fixture(scope="session")
+def docker_services():
+ """Start and stop Docker Compose test infrastructure."""
+ compose_file = E2E_DIR / "docker-compose.test.yml"
+
+ # Build mock RSS image
+ subprocess.run(
+ ["docker", "compose", "-f", str(compose_file), "build"],
+ check=True,
+ capture_output=True,
+ )
+
+ # Start services and wait for health checks
+ subprocess.run(
+ ["docker", "compose", "-f", str(compose_file), "up", "-d", "--wait"],
+ check=True,
+ timeout=120,
+ )
+
+ yield
+
+ # Teardown
+ subprocess.run(
+ ["docker", "compose", "-f", str(compose_file), "down", "-v"],
+ check=True,
+ capture_output=True,
+ )
+
+
+@pytest.fixture(scope="session")
+def qb_password(docker_services):
+ """Extract the auto-generated password from qBittorrent container logs."""
+ for _ in range(30):
+ result = subprocess.run(
+ ["docker", "logs", "ab-test-qbittorrent"],
+ capture_output=True,
+ text=True,
+ )
+ for line in result.stdout.splitlines() + result.stderr.splitlines():
+ if "temporary password" in line.lower():
+ return line.split(":")[-1].strip()
+ time.sleep(2)
+ pytest.fail("Could not extract qBittorrent temporary password from Docker logs")
+
+
+@pytest.fixture(scope="session")
+def ab_process(e2e_tmpdir, docker_services):
+ """Start AutoBangumi as a subprocess with isolated config/data dirs.
+
+ Uses CWD-based isolation: main.py resolves config/ and data/ relative
+ to the working directory, so we create those dirs in a temp location
+ and run the process from there.
+ """
+ work_dir = e2e_tmpdir / "ab_workdir"
+ work_dir.mkdir()
+ (work_dir / "config").mkdir()
+ (work_dir / "data").mkdir()
+
+ # main.py mounts StaticFiles for dist/assets and dist/images when
+ # VERSION != "DEV_VERSION". Create dummy dirs so the mounts succeed
+ # (the E2E tests only exercise the API, not the frontend).
+ dist_dir = work_dir / "dist"
+ dist_dir.mkdir()
+ (dist_dir / "assets").mkdir()
+ (dist_dir / "images").mkdir()
+ # Jinja2Templates requires at least one template file
+ (dist_dir / "index.html").write_text(
+ "e2e stub"
+ )
+
+ # backend/src/ is the directory containing main.py and module/
+ src_dir = Path(__file__).resolve().parents[2]
+
+ proc = subprocess.Popen(
+ [sys.executable, str(src_dir / "main.py")],
+ cwd=str(work_dir),
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ )
+
+ # Wait for AutoBangumi to be ready (poll setup status endpoint)
+ ready = False
+ for _ in range(30):
+ try:
+ resp = httpx.get(
+ "http://localhost:7892/api/v1/setup/status", timeout=3.0
+ )
+ if resp.status_code == 200:
+ ready = True
+ break
+ except (httpx.ConnectError, httpx.ReadTimeout):
+ pass
+ time.sleep(1)
+
+ if not ready:
+ proc.terminate()
+ stdout, stderr = proc.communicate(timeout=5)
+ pytest.fail(
+ f"AutoBangumi did not start within 30s.\n"
+ f"stdout: {stdout.decode(errors='replace')[-2000:]}\n"
+ f"stderr: {stderr.decode(errors='replace')[-2000:]}"
+ )
+
+ yield proc
+
+ proc.terminate()
+ try:
+ proc.wait(timeout=10)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.wait(timeout=5)
+
+
+@pytest.fixture(scope="session")
+def api_client(ab_process):
+ """HTTP client pointing at the running AutoBangumi instance.
+
+ Maintains cookies across requests so that the auth token (set via
+ Set-Cookie on login) is automatically included in subsequent calls.
+ """
+ with httpx.Client(base_url="http://localhost:7892", timeout=10.0) as client:
+ yield client
+
+
+@pytest.fixture(scope="session")
+def e2e_state():
+ """Mutable dict for sharing state across ordered E2E tests."""
+ return {}
diff --git a/backend/src/test/e2e/docker-compose.test.yml b/backend/src/test/e2e/docker-compose.test.yml
new file mode 100644
index 00000000..f3a1cf01
--- /dev/null
+++ b/backend/src/test/e2e/docker-compose.test.yml
@@ -0,0 +1,34 @@
+services:
+ qbittorrent:
+ image: linuxserver/qbittorrent:latest
+ container_name: ab-test-qbittorrent
+ environment:
+ - PUID=1000
+ - PGID=1000
+ - TZ=UTC
+ - WEBUI_PORT=18080
+ ports:
+ - "18080:18080"
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:18080"]
+ interval: 5s
+ timeout: 3s
+ retries: 15
+ start_period: 10s
+ tmpfs:
+ - /config
+ - /downloads
+
+ mock-rss:
+ build:
+ context: .
+ dockerfile: Dockerfile.mock-rss
+ container_name: ab-test-mock-rss
+ ports:
+ - "18888:18888"
+ healthcheck:
+ test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:18888/health')"]
+ interval: 3s
+ timeout: 2s
+ retries: 5
+ start_period: 3s
diff --git a/backend/src/test/e2e/fixtures/mikan.xml b/backend/src/test/e2e/fixtures/mikan.xml
new file mode 100644
index 00000000..e54af410
--- /dev/null
+++ b/backend/src/test/e2e/fixtures/mikan.xml
@@ -0,0 +1,72 @@
+
+
+
+ Mikan Project - E2E Test Feed
+ https://mikanani.me
+ E2E test RSS feed for AutoBangumi
+ -
+ [Lilith-Raws] Sousou no Frieren - 01 [Baha][WEB-DL][1080p][AVC AAC][CHT][MP4]
+ https://mikanani.me/Home/Episode/abc001
+
+
+ 2025-10-06T12:00:00
+
+
+ -
+ [Lilith-Raws] Sousou no Frieren - 02 [Baha][WEB-DL][1080p][AVC AAC][CHT][MP4]
+ https://mikanani.me/Home/Episode/abc002
+
+
+ 2025-10-13T12:00:00
+
+
+ -
+ [Lilith-Raws] Sousou no Frieren - 03 [Baha][WEB-DL][1080p][AVC AAC][CHT][MP4]
+ https://mikanani.me/Home/Episode/abc003
+
+
+ 2025-10-20T12:00:00
+
+
+ -
+ [SubsPlease] Jujutsu Kaisen - 01 (1080p) [ABCD1234].mkv
+ https://mikanani.me/Home/Episode/def001
+
+
+ 2025-10-07T12:00:00
+
+
+ -
+ [SubsPlease] Jujutsu Kaisen - 02 (1080p) [EFGH5678].mkv
+ https://mikanani.me/Home/Episode/def002
+
+
+ 2025-10-14T12:00:00
+
+
+ -
+ [ANi] Spy x Family Season 2 - 01 [1080p][Baha][WEB-DL][AAC AVC][CHT]
+ https://mikanani.me/Home/Episode/ghi001
+
+
+ 2025-10-07T18:00:00
+
+
+ -
+ [Nekomoe kissaten] Kusuriya no Hitorigoto - 01 [BDRip 1080p HEVC-10bit FLAC]
+ https://mikanani.me/Home/Episode/jkl001
+
+
+ 2025-10-21T12:00:00
+
+
+ -
+ [Nekomoe kissaten] Kusuriya no Hitorigoto - 02 [BDRip 1080p HEVC-10bit FLAC]
+ https://mikanani.me/Home/Episode/jkl002
+
+
+ 2025-10-28T12:00:00
+
+
+
+
diff --git a/backend/src/test/e2e/mock_rss_server.py b/backend/src/test/e2e/mock_rss_server.py
new file mode 100644
index 00000000..bb7c473f
--- /dev/null
+++ b/backend/src/test/e2e/mock_rss_server.py
@@ -0,0 +1,34 @@
+"""Minimal HTTP server that serves static RSS XML fixtures."""
+
+import asyncio
+from pathlib import Path
+
+from aiohttp import web
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+async def handle_rss(request: web.Request) -> web.Response:
+ feed_name = request.match_info["feed_name"]
+ xml_path = FIXTURES_DIR / f"{feed_name}.xml"
+ if not xml_path.exists():
+ return web.Response(status=404, text=f"Feed not found: {feed_name}")
+ return web.Response(
+ text=xml_path.read_text(encoding="utf-8"),
+ content_type="application/xml",
+ )
+
+
+async def handle_health(request: web.Request) -> web.Response:
+ return web.Response(text="OK")
+
+
+def create_app() -> web.Application:
+ app = web.Application()
+ app.router.add_get("/health", handle_health)
+ app.router.add_get("/rss/{feed_name}.xml", handle_rss)
+ return app
+
+
+if __name__ == "__main__":
+ web.run_app(create_app(), host="0.0.0.0", port=18888)
diff --git a/backend/src/test/e2e/test_e2e_workflow.py b/backend/src/test/e2e/test_e2e_workflow.py
new file mode 100644
index 00000000..89690d3d
--- /dev/null
+++ b/backend/src/test/e2e/test_e2e_workflow.py
@@ -0,0 +1,668 @@
+"""E2E integration tests for the full AutoBangumi workflow.
+
+Tests are executed in definition order within the class. Each phase
+builds on state created by earlier phases (setup wizard -> auth ->
+config -> RSS -> bangumi -> downloader -> program -> log -> search ->
+notification -> credential update -> cleanup).
+
+Prerequisites:
+ - Docker running (qBittorrent + mock RSS containers)
+ - Port 7892 free (AutoBangumi)
+ - Port 18080 free (qBittorrent)
+ - Port 18888 free (mock RSS server)
+
+Run:
+ cd backend && uv run pytest -m e2e -v --tb=long
+"""
+
+import httpx
+import pytest
+
+from .conftest import E2E_PASSWORD, E2E_USERNAME
+
+
+@pytest.mark.e2e
+class TestE2EWorkflow:
+ """Full workflow test against real qBittorrent and mock RSS server."""
+
+ # ===================================================================
+ # Phase 1: Setup Wizard
+ # ===================================================================
+
+ def test_01_setup_status_needs_setup(self, api_client):
+ """Fresh instance should require setup."""
+ resp = api_client.get("/api/v1/setup/status")
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["need_setup"] is True
+ assert "version" in data
+
+ def test_02_verify_infrastructure(self, api_client, qb_password):
+ """Verify Docker test infrastructure is reachable."""
+ # qBittorrent WebUI
+ qb_resp = httpx.get("http://localhost:18080", timeout=5.0)
+ assert qb_resp.status_code == 200
+
+ # Mock RSS server
+ rss_resp = httpx.get("http://localhost:18888/health", timeout=5.0)
+ assert rss_resp.status_code == 200
+
+ # Mock RSS feed content
+ xml_resp = httpx.get("http://localhost:18888/rss/mikan.xml", timeout=5.0)
+ assert xml_resp.status_code == 200
+ assert " 0
+
+ def test_81_search_provider_config(self, api_client):
+ """Get search provider URL templates."""
+ resp = api_client.get("/api/v1/search/provider/config")
+ assert resp.status_code == 200
+ config = resp.json()
+ assert isinstance(config, dict)
+
+ def test_82_search_empty_keywords(self, api_client):
+ """Search with no keywords returns empty list."""
+ resp = api_client.get("/api/v1/search/bangumi")
+ assert resp.status_code == 200
+ assert resp.json() == []
+
+ # ===================================================================
+ # Phase 10: Notification
+ # ===================================================================
+
+ def test_85_notification_test_invalid_index(self, api_client):
+ """Test notification with out-of-range index returns success=false."""
+ resp = api_client.post(
+ "/api/v1/notification/test", json={"provider_index": 9999}
+ )
+ assert resp.status_code == 200
+ assert resp.json()["success"] is False
+
+ def test_86_notification_test_config_unknown_type(self, api_client):
+ """Test-config with unknown provider type returns success=false."""
+ resp = api_client.post(
+ "/api/v1/notification/test-config",
+ json={"type": "nonexistent_provider", "enabled": True},
+ )
+ assert resp.status_code == 200
+ assert resp.json()["success"] is False
+
+ # ===================================================================
+ # Phase 11: Credential Update & Cleanup
+ # ===================================================================
+
+ def test_90_update_credentials(self, api_client, e2e_state):
+ """Update user password via /auth/update."""
+ resp = api_client.post(
+ "/api/v1/auth/update",
+ json={"password": "newpassword123"},
+ )
+ assert resp.status_code == 200
+ data = resp.json()
+ assert "access_token" in data
+ assert data["message"] == "update success"
+ e2e_state["new_password"] = "newpassword123"
+
+ def test_91_login_with_new_password(self, api_client, e2e_state):
+ """Login works with the updated password."""
+ resp = api_client.post(
+ "/api/v1/auth/login",
+ data={
+ "username": E2E_USERNAME,
+ "password": e2e_state["new_password"],
+ },
+ )
+ assert resp.status_code == 200
+ assert "access_token" in resp.json()
+
+ def test_92_login_old_password_fails(self, api_client):
+ """Old password should no longer work after credential update."""
+ resp = api_client.post(
+ "/api/v1/auth/login",
+ data={"username": E2E_USERNAME, "password": E2E_PASSWORD},
+ )
+ assert resp.status_code == 401
+
+ def test_93_logout(self, api_client):
+ """Logout clears the auth session and deletes cookie."""
+ resp = api_client.get("/api/v1/auth/logout")
+ assert resp.status_code == 200
+
+ def test_94_verify_logged_out(self, api_client):
+ """After logout, the token cookie should be cleared.
+
+ NOTE: In DEV_VERSION, endpoints still work (auth bypass).
+ This test verifies the cookie was deleted.
+ """
+ # httpx may still have a cookie if the server didn't properly
+ # delete it, but the logout response should have Set-Cookie
+ # with max-age=0 or explicit deletion.
+ resp = api_client.get("/api/v1/status")
+ # DEV_VERSION: 200 (bypass), Production: 401 (no token)
+ assert resp.status_code in (200, 401)
diff --git a/docs/dev/e2e-test-guide.md b/docs/dev/e2e-test-guide.md
new file mode 100644
index 00000000..177875e5
--- /dev/null
+++ b/docs/dev/e2e-test-guide.md
@@ -0,0 +1,145 @@
+# E2E Integration Test Guide
+
+End-to-end tests that exercise the full AutoBangumi workflow against real
+Docker services (qBittorrent + mock RSS server).
+
+## Prerequisites
+
+- **Docker** with `docker compose` (v2)
+- **uv** for Python dependency management
+- Ports **7892**, **18080**, **18888** must be free
+
+## Quick Start
+
+```bash
+# 1. Build the mock RSS server image
+cd backend/src/test/e2e
+docker build -f Dockerfile.mock-rss -t ab-mock-rss .
+
+# 2. Start test infrastructure
+docker compose -f docker-compose.test.yml up -d --wait
+
+# 3. Verify services are healthy
+docker compose -f docker-compose.test.yml ps
+
+# 4. Run E2E tests
+cd backend && uv run pytest -m e2e -v --tb=long
+
+# 5. Cleanup
+docker compose -f backend/src/test/e2e/docker-compose.test.yml down -v
+```
+
+## Architecture
+
+```
+Host machine
+├── pytest (test runner)
+│ └── Drives HTTP requests to AutoBangumi at localhost:7892
+├── AutoBangumi subprocess
+│ ├── Isolated config/ and data/ in temp directory
+│ └── Uses mock downloader (no real qB coupling during setup)
+├── qBittorrent container (localhost:18080)
+│ └── linuxserver/qbittorrent:latest
+└── Mock RSS server container (localhost:18888)
+ └── Serves static XML fixtures from fixtures/
+```
+
+## Test Phases
+
+| Phase | Tests | What It Validates |
+|-------|-------|-------------------|
+| 1. Setup Wizard | `test_01` - `test_06` | First-run detection, mock downloader, setup completion, 403 guard |
+| 2. Authentication | `test_10` - `test_13` | Login, cookie-based JWT, token refresh, logout |
+| 3. Configuration | `test_20` - `test_22` | Config CRUD, password masking |
+| 4. RSS Management | `test_30` - `test_32` | Add, list, delete RSS feeds |
+| 5. Program Lifecycle | `test_40` - `test_41` | Status check, restart |
+| 6. Downloader | `test_50` - `test_51` | Mock downloader health, direct qB connectivity |
+| 7. Cleanup | `test_90` | Logout |
+
+## Key Design Decisions
+
+### Mock Downloader for Setup
+
+The setup wizard's `_validate_url()` blocks private/loopback IPs (SSRF
+protection). Since the Docker qBittorrent instance is on `localhost`, the
+setup wizard's "test downloader" endpoint would reject it. Instead:
+
+1. Setup uses `downloader_type: "mock"` (bypasses URL validation)
+2. Config can be updated to point to real qBittorrent after auth
+3. Direct qBittorrent connectivity is tested independently (`test_51`)
+
+### DEV_VERSION Auth Bypass
+
+When running from source, `VERSION == "DEV_VERSION"` which bypasses JWT
+validation (`get_current_user` returns `"dev_user"` unconditionally). Tests
+document this behavior: login/refresh/logout endpoints still work, but
+unauthenticated access is also allowed. In production builds, test_13
+would expect HTTP 401.
+
+### CWD-Based Isolation
+
+AutoBangumi resolves all paths relative to the working directory:
+- `config/` - config files, JWT secret, setup sentinel
+- `data/` - SQLite database, posters, logs
+
+The `ab_process` fixture creates a temp directory with these subdirs and
+runs `main.py` from there, ensuring complete isolation from any existing
+installation.
+
+### qBittorrent Password Extraction
+
+Recent `linuxserver/qbittorrent` images generate a random temporary
+password on first start. The `qb_password` fixture polls `docker logs`
+until it finds the line:
+
+```
+A temporary password is provided for this session: XXXXXXXX
+```
+
+## Debugging Failures
+
+### AutoBangumi won't start
+
+```bash
+# Check if port 7892 is in use
+lsof -i :7892
+
+# Run manually to see startup logs
+cd /tmp/test-workdir && uv run python /path/to/backend/src/main.py
+```
+
+### qBittorrent issues
+
+```bash
+docker logs ab-test-qbittorrent
+docker exec ab-test-qbittorrent curl -s http://localhost:18080
+```
+
+### Mock RSS server issues
+
+```bash
+docker logs ab-test-mock-rss
+curl http://localhost:18888/health
+curl http://localhost:18888/rss/mikan.xml
+```
+
+### Test infrastructure stuck
+
+```bash
+# Force cleanup
+docker compose -f backend/src/test/e2e/docker-compose.test.yml down -v --remove-orphans
+```
+
+## Adding New Test Scenarios
+
+1. Add new test methods to `TestE2EWorkflow` in definition order
+2. Use `api_client` for HTTP requests (cookies persist across tests)
+3. Use `e2e_state` dict to share data between tests
+4. For new RSS fixtures, add XML files to `fixtures/` directory
+5. Keep test names ordered: `test_XX_description` where XX reflects the phase
+
+### Adding a new fixture feed
+
+1. Create `backend/src/test/e2e/fixtures/your_feed.xml`
+2. Access via `http://localhost:18888/rss/your_feed.xml`
+3. Rebuild the mock RSS image: `docker compose ... build mock-rss`