Files
MoviePilot/tests/test_mediavault_module.py
thsrite d04b721f84 feat(mediaserver): 新增 MediaVault 自建媒体库模块
通过 MediaVault 管理端口的原生接口接入自建媒体库,凭据为管理面板的长效 API Key:

- 媒体库列表、条目分页遍历、条目详情与总数
- 按标题/年份/媒体身份判断电影与剧集存在性,季集齐全度与季集条目 ID
- 数量统计、最近入库、继续观看、封面与背景图直链、播放地址
- 入库后按目标路径命中媒体库并排队后台扫描,未命中时回退全库扫描
- 用 MediaVault 账号完成 MoviePilot 用户认证

MediaVault 无音乐库也不外发 Webhook,get_music 与 webhook_parser 不实现;
图片直链自带 API Key,无需 mediaserver_image_cookies。

同时把 mediavault 接入 mediaserver-operation Agent Skill 的 provider 清单。
2026-09-07 13:49:10 +08:00

444 lines
19 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""MediaVault 自建媒体库客户端的行为契约,全部走假 API 不发真实请求。"""
from pathlib import Path
from typing import Optional
import pytest
from app.modules.mediavault.api import Result
from app.modules.mediavault.mediavault import MediaVault
from app.schemas.mediaserver import RefreshMediaItem
from app.schemas.types import MediaSource, MediaType
class _FakeApi:
"""按路径返回预置数据,并记录调用参数。"""
def __init__(self, routes: dict, host: str = "http://mv.local"):
self.routes = routes
self.calls = []
self.closed = False
self._host = host
@property
def configured(self) -> bool:
return True
def close(self) -> None:
self.closed = True
def image_url(self, item_id: str, image_type: str, host: Optional[str] = None) -> str:
return f"{host or self._host}/api/v1/media-library/items/{item_id}/image/{image_type}?api_key=k"
def request(self, api, method=None, params=None, data=None, base_path=None, suppress_log=False):
self.calls.append({"api": api, "method": method, "params": params or {}, "data": data,
"base_path": base_path})
handler = self.routes.get(api)
if handler is None:
return Result(False, None, "not found", 404)
return handler(params or {}, data) if callable(handler) else handler
def _client(routes: dict, **kwargs) -> MediaVault:
"""构造一个绕过网络探测的客户端。"""
client = MediaVault.__new__(MediaVault)
client._host = "http://mv.local"
client._playhost = kwargs.get("play_host")
client._apikey = "k"
client._sync_libraries = kwargs.get("sync_libraries") or []
client._api = _FakeApi(routes)
client._active = True
return client
def _item_row(index: int, kind: str = "Movie", **extra) -> dict:
row = {"id": f"id-{index}", "library_id": "lib-1", "parent_id": "", "kind": kind,
"title": f"影片{index}", "year": 2020, "tmdb_id": 1000 + index, "overview": "",
"genres": [], "has_poster": True, "has_backdrop": False, "season": 0, "episode": 0,
"duration_ticks": 0, "is_missing": False, "metadata_info": {}, "user_data": {}}
row.update(extra)
return row
def _paged_items(total_rows: list):
"""按 page/page_size 切分预置条目,模拟 MediaVault 的分页语义。"""
def handler(params, _data):
page = int(params.get("page", 1))
size = int(params.get("page_size", 40))
start = (page - 1) * size
return Result(True, {"items": total_rows[start:start + size], "total": len(total_rows)})
return handler
# ── 分页 ────────────────────────────────────────────────────────────
@pytest.mark.parametrize("limit", [1, 30, 100, 130, 250, 356, 400])
def test_get_items_limit_matches_full_scan_prefix(limit):
"""限量遍历的结果必须是全量遍历的前缀,不重复也不跳条。"""
rows = [_item_row(i) for i in range(356)]
client = _client({"/items": _paged_items(rows)})
full = [item.item_id for item in client.get_items("lib-1")]
assert len(full) == len(set(full)) == 356
client = _client({"/items": _paged_items(rows)})
got = [item.item_id for item in client.get_items("lib-1", limit=limit)]
assert got == full[:limit]
@pytest.mark.parametrize("start_index", [0, 30, 100, 130, 250])
def test_get_items_start_index_matches_full_scan_slice(start_index):
"""起始偏移不是页大小整数倍时,也必须精确对齐到全量切片。"""
rows = [_item_row(i) for i in range(356)]
full = [item.item_id for item in _client({"/items": _paged_items(rows)}).get_items("lib-1")]
client = _client({"/items": _paged_items(rows)})
got = [item.item_id for item in client.get_items("lib-1", start_index=start_index, limit=20)]
assert got == full[start_index:start_index + 20]
def test_get_items_always_requests_full_pages():
"""页大小恒为上限,页码才能稳定换算成偏移量。"""
rows = [_item_row(i) for i in range(250)]
client = _client({"/items": _paged_items(rows)})
list(client.get_items("lib-1", limit=130))
sizes = {call["params"]["page_size"] for call in client._api.calls}
pages = [call["params"]["page"] for call in client._api.calls]
assert sizes == {MediaVault.PAGE_LIMIT}
assert pages == [1, 2]
def test_get_items_stops_when_request_fails():
"""中途请求失败时停止产出,不把失败当成遍历结束的空库。"""
rows = [_item_row(i) for i in range(150)]
calls = {"n": 0}
def flaky(params, _data):
calls["n"] += 1
if calls["n"] > 1:
return None
return _paged_items(rows)(params, None)
client = _client({"/items": flaky})
assert len([*client.get_items("lib-1")]) == 100
# ── 媒体库与统计 ────────────────────────────────────────────────────
def test_get_librarys_maps_type_and_builds_image_url():
"""媒体库类型按 MediaVault 的 library_type 映射,封面走带鉴权的图片直链。"""
routes = {
"/libraries": Result(True, {"items": [
{"id": "lib-1", "name": "电影库", "library_type": "movies", "root_paths": ["/mnt/movies"]},
{"id": "lib-2", "name": "剧集库", "library_type": "tvshows", "root_path": "/mnt/tv"},
{"id": "lib-3", "name": "未知库", "library_type": "other", "root_paths": []},
]}),
"/items": _paged_items([_item_row(0)]),
}
libraries = _client(routes).get_librarys()
assert [lib.type for lib in libraries] == [
MediaType.MOVIE.value, MediaType.TV.value, MediaType.UNKNOWN.value
]
assert libraries[0].path == ["/mnt/movies"]
assert libraries[1].path == "/mnt/tv"
assert libraries[0].image.endswith("/items/lib-1/image/primary?api_key=k")
assert libraries[0].server_type == "mediavault"
def test_get_librarys_hidden_respects_sync_selection():
"""开启过滤时只保留已勾选同步的媒体库。"""
routes = {
"/libraries": Result(True, {"items": [
{"id": "lib-1", "name": "A", "library_type": "movies"},
{"id": "lib-2", "name": "B", "library_type": "movies"},
]}),
"/items": _paged_items([]),
}
client = _client(routes, sync_libraries=["lib-2"])
assert [lib.id for lib in client.get_librarys(hidden=True)] == ["lib-2"]
assert [lib.id for lib in client.get_librarys(hidden=False)] == ["lib-1", "lib-2"]
def test_get_librarys_returns_none_when_unreachable():
"""连接失败返回 None,与"媒体库为空"区分开。"""
assert _client({"/libraries": None}).get_librarys() is None
def test_get_medias_count_maps_statistics_fields():
"""统计接口字段映射到 MoviePilot 的统计模型。"""
routes = {"/statistics": Result(True, {"movie_count": 3030, "series_count": 1501,
"episode_count": 69597, "item_count": 74128})}
statistic = _client(routes).get_medias_count()
assert (statistic.movie_count, statistic.tv_count, statistic.episode_count) == (3030, 1501, 69597)
def test_get_items_count_reads_total_not_page_length():
"""条目总数取分页返回的 total,不受页大小影响。"""
rows = [_item_row(i) for i in range(356)]
client = _client({"/items": _paged_items(rows)})
assert client.get_items_count("lib-1") == 356
# ── 存在性判断 ──────────────────────────────────────────────────────
def test_get_movies_filters_by_title_year_and_identity():
"""电影匹配要求标题全等、年份一致且媒体身份不冲突。"""
rows = [
_item_row(1, title="沙丘", year=2021, tmdb_id=438631),
_item_row(2, title="沙丘", year=2024, tmdb_id=693134),
_item_row(3, title="沙丘前传", year=2021, tmdb_id=111),
]
client = _client({"/items": _paged_items(rows)})
assert [m.item_id for m in client.get_movies(title="沙丘")] == ["id-1", "id-2"]
client = _client({"/items": _paged_items(rows)})
assert [m.item_id for m in client.get_movies(title="沙丘", year="2021")] == ["id-1"]
client = _client({"/items": _paged_items(rows)})
matched = client.get_movies(title="沙丘", media_source=MediaSource.TMDB, media_id="693134")
assert [m.item_id for m in matched] == ["id-2"]
def test_get_movies_requests_movie_kind_only():
"""存在性查询按类型收窄,避免剧集与分集混进电影结果。"""
client = _client({"/items": _paged_items([])})
client.get_movies(title="沙丘")
assert client._api.calls[0]["params"]["kinds"] == "Movie"
assert client._api.calls[0]["params"]["keyword"] == "沙丘"
def test_get_tv_episodes_by_item_id_returns_season_map():
"""按条目 ID 查询直接返回季集映射。"""
routes = {
"/items/series-1": Result(True, _item_row(1, kind="Series", title="剧A", tmdb_id=99)),
"/items/series-1/episodes": Result(True, {"seasons": {"1": [1, 2, 3], "2": [1]}}),
}
item_id, seasons = _client(routes).get_tv_episodes(item_id="series-1")
assert item_id == "series-1"
assert seasons == {1: [1, 2, 3], 2: [1]}
def test_get_tv_episodes_filters_requested_season():
"""指定季号时只返回该季。"""
routes = {
"/items/series-1": Result(True, _item_row(1, kind="Series")),
"/items/series-1/episodes": Result(True, {"seasons": {"1": [1, 2], "2": [1]}}),
}
_, seasons = _client(routes).get_tv_episodes(item_id="series-1", season=2)
assert seasons == {2: [1]}
def test_get_tv_episodes_falls_back_to_title_when_cached_id_is_stale():
"""缓存的条目 ID 失效时退回按标题重新定位,不误判整部剧缺失。"""
routes = {
"/items/stale-id": Result(False, None, "not found", 404),
"/items": _paged_items([_item_row(7, kind="Series", title="剧A", year=2020)]),
"/items/id-7/episodes": Result(True, {"seasons": {"1": [1, 2]}}),
}
item_id, seasons = _client(routes).get_tv_episodes(item_id="stale-id", title="剧A", year="2020")
assert item_id == "id-7"
assert seasons == {1: [1, 2]}
def test_get_tv_episodes_returns_empty_when_series_absent():
"""剧集不在库中返回空季集:与 Emby 一致用 (None, {}) 表示"查得到但没有"。"""
routes = {"/items": _paged_items([])}
assert _client(routes).get_tv_episodes(title="不存在的剧") == (None, {})
def test_get_tv_episodes_returns_none_when_unreachable():
"""服务不可达时返回 None,避免被当成"这部剧一集都没有"。"""
routes = {"/items": lambda params, data: None}
assert _client(routes).get_tv_episodes(title="剧A") == (None, None)
def test_get_season_episode_ids_maps_episode_number_to_item_id():
"""季集条目 ID 映射先定位季,再遍历该季的分集。"""
def items(params, _data):
if params.get("kinds") == "Season":
return Result(True, {"items": [_item_row(1, kind="Season", season=1),
_item_row(2, kind="Season", season=2)], "total": 2})
if params.get("parent_id") == "id-2":
return Result(True, {"items": [_item_row(10, kind="Episode", season=2, episode=1),
_item_row(11, kind="Episode", season=2, episode=2)],
"total": 2})
return Result(True, {"items": [], "total": 0})
assert _client({"/items": items}).get_season_episode_ids("series-1", 2) == {
1: "id-10", 2: "id-11",
}
def test_get_season_episode_ids_returns_empty_for_missing_season():
"""季不存在时返回空映射。"""
client = _client({"/items": _paged_items([_item_row(1, kind="Season", season=1)])})
assert client.get_season_episode_ids("series-1", 9) == {}
# ── 条目转换 ────────────────────────────────────────────────────────
def test_iteminfo_extracts_identity_and_path_from_sources():
"""条目详情带媒体源时取文件路径,身份按 ProviderIds 优先级解析。"""
row = _item_row(1, tmdb_id=0, metadata_info={"original_title": "Dune",
"external_ids": {"imdb_id": "tt1160419"}},
sources=[{"id": "s1", "path": "/mnt/movies/Dune/Dune.mkv"}])
client = _client({"/items/id-1": Result(True, row)})
item = client.get_iteminfo("id-1")
assert item.media_source == MediaSource.IMDb
assert item.media_id == "tt1160419"
assert item.original_title == "Dune"
assert item.path == "/mnt/movies/Dune/Dune.mkv"
def test_iteminfo_prefers_tmdb_over_other_providers():
"""同时有 TMDB 与 IMDb 时按统一优先级取 TMDB。"""
row = _item_row(1, tmdb_id=438631, metadata_info={"external_ids": {"imdb_id": "tt1160419"}})
item = _client({"/items/id-1": Result(True, row)}).get_iteminfo("id-1")
assert (item.media_source, item.media_id) == (MediaSource.TMDB, "438631")
def test_iteminfo_returns_none_for_missing_item():
"""条目不存在返回 None。"""
assert _client({}).get_iteminfo("nope") is None
# ── 展示与图片 ──────────────────────────────────────────────────────
def test_get_resume_builds_episode_subtitle_and_percent():
"""继续观看的分集用剧名做标题,进度按播放位置换算。"""
row = _item_row(1, kind="Episode", season=2, episode=5, title="第五集",
series_id="series-1", series_name="剧A",
duration_ticks=1000, user_data={"position_ticks": 250})
client = _client({"/items": _paged_items([row])})
played = client.get_resume(num=5)[0]
assert played.title == "剧A"
assert played.subtitle == "S2:5 - 第五集"
assert played.type == MediaType.TV.value
assert played.percent == 25.0
# 分集海报取所属剧集,避免每集一张缩略图
assert "/items/series-1/image/primary" in played.image
def test_get_latest_backdrops_fills_up_to_requested_count():
"""没有背景图的条目不占名额,取满请求数量为止。"""
rows = [_item_row(i, has_backdrop=(i % 3 == 0)) for i in range(60)]
client = _client({"/items": _paged_items(rows)})
assert len(client.get_latest_backdrops(num=10)) == 10
def test_get_latest_backdrops_uses_play_host_when_remote():
"""外网场景改用播放地址拼图片链接。"""
rows = [_item_row(0, has_backdrop=True)]
client = _client({"/items": _paged_items(rows)}, play_host="https://mv.example.com")
assert client.get_latest_backdrops(num=1, remote=True)[0].startswith("https://mv.example.com")
assert client.get_latest_backdrops(num=1, remote=False)[0].startswith("http://mv.local")
# ── 入库刷新 ────────────────────────────────────────────────────────
def test_refresh_library_by_items_scans_only_matched_libraries():
"""入库路径命中哪个媒体库就只扫哪个,同一媒体库不重复排队。"""
routes = {
"/libraries": Result(True, {"items": [
{"id": "lib-1", "name": "电影", "root_paths": ["/mnt/movies"]},
{"id": "lib-2", "name": "剧集", "root_paths": ["/mnt/tv"]},
]}),
"/libraries/lib-1/scan-task": Result(True, {}),
"/libraries/lib-2/scan-task": Result(True, {}),
}
client = _client(routes)
assert client.refresh_library_by_items([
RefreshMediaItem(title="A", target_path=Path("/mnt/movies/A (2020)")),
RefreshMediaItem(title="B", target_path=Path("/mnt/movies/B (2021)")),
]) is True
scanned = [call["api"] for call in client._api.calls if call["api"].endswith("scan-task")]
assert scanned == ["/libraries/lib-1/scan-task"]
def test_refresh_library_by_items_falls_back_to_full_scan_when_unmatched():
"""路径落在所有媒体库之外时退回全库扫描,避免新片一直不入库。"""
routes = {
"/libraries": Result(True, {"items": [{"id": "lib-1", "root_paths": ["/mnt/movies"]}]}),
"/libraries/lib-1/scan-task": Result(True, {}),
}
client = _client(routes)
assert client.refresh_library_by_items([
RefreshMediaItem(title="C", target_path=Path("/data/other/C")),
]) is True
assert [call["api"] for call in client._api.calls if "scan-task" in call["api"]] == [
"/libraries/lib-1/scan-task"
]
def test_refresh_library_by_items_returns_none_when_unreachable():
"""媒体库列表拿不到时返回 None,交由上层判定为服务不可用。"""
client = _client({"/libraries": None})
assert client.refresh_library_by_items([RefreshMediaItem(title="A", target_path=Path("/x"))]) is None
def test_refresh_root_library_queues_every_library():
"""全库刷新对每个媒体库各排一次后台扫描。"""
routes = {
"/libraries": Result(True, {"items": [{"id": "lib-1"}, {"id": "lib-2"}]}),
"/libraries/lib-1/scan-task": Result(True, {}),
"/libraries/lib-2/scan-task": Result(True, {}),
}
client = _client(routes)
assert client.refresh_root_library() is True
assert [call["api"] for call in client._api.calls if "scan-task" in call["api"]] == [
"/libraries/lib-1/scan-task", "/libraries/lib-2/scan-task",
]
assert all(call["method"] == "post" for call in client._api.calls if "scan-task" in call["api"])
# ── 连接与认证 ──────────────────────────────────────────────────────
def test_reconnect_marks_inactive_when_credentials_rejected():
"""凭据被拒时标记为失活,交给定时重连重试。"""
client = _client({"/libraries": Result(False, None, "unauthorized", 401)})
assert client.reconnect() is False
assert client.is_inactive() is True
assert client.is_authenticated() is False
def test_unconfigured_client_never_reports_inactive():
"""配置不完整的实例不参与重连,避免定时任务空转。"""
client = _client({})
client._apikey = None
assert client.is_configured() is False
assert client.is_inactive() is False
assert client.reconnect() is False
def test_authenticate_posts_to_user_auth_and_returns_token():
"""用户认证走 MediaVault 账号体系,返回访问令牌。"""
routes = {"/login": Result(True, {"access_token": "jwt-token", "token": "legacy"})}
client = _client(routes)
assert client.authenticate("someone", "secret") == "jwt-token"
call = client._api.calls[0]
assert (call["base_path"], call["method"]) == ("/api/v1/user-auth", "post")
assert call["data"] == {"username": "someone", "password": "secret"}
def test_authenticate_returns_none_on_rejection():
"""认证失败返回 None,不把错误响应当成令牌。"""
assert _client({"/login": Result(False, None, "bad credentials", 401)}).authenticate("a", "b") is None
assert _client({}).authenticate("", "") is None
def test_disconnect_closes_session():
"""断开时释放底层会话。"""
client = _client({})
client.disconnect()
assert client._api.closed is True
assert client.is_authenticated() is False