测试¶
服务器的测试套件位于 apps/server/tests/,使用
pytest + pytest-asyncio + respx(HTTP mock)。
运行测试套件¶
# From repo root:
uv run --directory apps/server pytest
# With a specific reporter (e.g. short traceback):
uv run --directory apps/server pytest --tb=short
# Single file:
uv run --directory apps/server pytest apps/server/tests/test_tools.py
# Single test:
uv run --directory apps/server pytest apps/server/tests/test_tools.py::test_generate_image_calls_client
# With coverage report:
uv run --directory apps/server pytest --cov-report=term-missing
# With JUnit XML output (CI-style):
uv run --directory apps/server pytest --junitxml=test-results/pytest.xml
测试布局¶
apps/server/tests/
├── conftest.py # Shared fixtures (png_bytes, settings, fake_client, fake_app, mcp_client)
├── _helpers.py # Constants + helpers (PNG_BYTES)
├── test_audit.py # Append-only audit trail: record shape, redaction, header cap
├── test_cli.py # CLI subcommands
├── test_client.py # NovelAIClient HTTP layer (uses respx)
├── test_errors.py # Error-body parsing + code/explanation propagation
├── test_features.py # Insiders feature registry + resolution rules
├── test_http.py # Chrome TLS + header fingerprint factory (create_http_client)
├── test_insiders.py # X-MCP-Insiders header parser
├── test_insiders_http.py # End-to-end HTTP: real server + real headers (routing, audit, scoped output, emotion gate)
├── test_mcp_auth.py # Optional bearer-token auth (unit + live HTTP)
├── test_middleware.py # Tool-call logging middleware
├── test_models.py # Pydantic models
├── test_output.py # save_image + resolve_output_path
├── test_payload.py # build_generation_payload
├── test_prompts.py # novelai_* prompt templates
├── test_release_tooling.py # Release tooling in scripts/ (version sync, release notes)
├── test_resources.py # novelai://... resources and templates
├── test_routing.py # Header-driven routing context + route sanitisation
├── test_server.py # FastMCP lifespan, metadata + transport selection
├── test_settings.py # Settings surface + insiders/routing dependency providers
└── test_tools.py # Each MCP tool's happy path + error cases
Fixture¶
conftest.py 提供以下 fixture:
Fixture |
类型 |
用途 |
|---|---|---|
|
|
最小的 1×1 PNG(透明黑)。 |
|
|
同一张 PNG 的 base64 形式(线格式)。 |
|
|
mock 客户端方法返回的预置图像。 |
|
|
带 token + 临时输出目录的 settings。 |
|
|
被 mock 的 |
|
|
工具通过 |
|
|
基于生产 |
覆写 fake_client 各方法上的 return_value / side_effect
即可定制单个测试的行为:
from fastmcp.exceptions import ToolError
async def test_generate_image_handles_provider_error(fake_app, fake_client):
fake_client.generate.side_effect = NovelAIProviderError("rate limited")
with pytest.raises(ToolError, match="rate limited"):
await generate.generate_image(prompt="1girl", app=fake_app)
预期失败会以 ToolError 的形式出现(服务器以
mask_error_details=True 运行,因此其他异常都会被屏蔽 —— 见
tools/_errors.py)。
HTTP mock¶
respx 会 mock 测试套件中所有 httpx 请求 —— 不会发起真实的 NovelAI
API 调用。模式:
import respx
from httpx import Response
@respx.mock
async def test_get_subscription():
respx.get("https://image.novelai.net/user/subscription").mock(
return_value=Response(200, json={"tier": 3, "active": True})
)
sub = await client.get_subscription()
assert sub["tier"] == 3
异步约定¶
asyncio_mode = "auto"—— 异步测试函数不需要@pytest.mark.asyncio。asyncio_default_fixture_loop_scope = "session"—— 整个会话共用一个事件 循环(更快,没有每测试的循环开销)。异步 fixture 直接使用
async def。
覆盖率¶
下限:70%(由
--cov-fail-under=70强制执行)。报告:
term-missing(终端)+xml:test-results/coverage.xml(CI)。排除:
pragma: no cover、if TYPE_CHECKING:、raise NotImplementedError、if __name__ == .__main__.:。源码范围:
apps/server/src/novelai_image_mcp/。
CI¶
GitHub Actions 在每次 PR 以及推送到 main/dev 时运行该测试套件,
覆盖三个操作系统(Ubuntu、Windows、macOS)。见
ci.yml。
docker-build job 以 SMOKE_TEST=true 构建生产镜像,并在其中运行
apps/server/docker/smoke-test.py —— 验证容器确实能启动、且工具能注册。
编写新测试¶
# apps/server/tests/test_tools.py
async def test_generate_image_with_v4_model(fake_app, fake_client):
"""generate_image should pass through V4 model ids."""
from novelai_image_mcp.tools import generate
fake_client.generate.return_value = (
NovelAIImage(filename="test.png", data=PNG_BYTES),
)
# Direct call: asserts the request and the returned content blocks.
result = await generate.generate_image(
prompt="1girl",
model=Model.V4,
app=fake_app,
)
assert len(result) == 2
assert result[0].data == PNG_BYTES # fastmcp Image helper holds raw bytes
assert "Saved 1 image" in result[1]
对于只有 FastMCP 才能证明的东西 —— schema 校验、依赖
注入、注解、Image→ImageContent 转换 —— 请改走
客户端:
async def test_generate_image_serializes(mcp_client, fake_client, nai_image):
from mcp_types import ImageContent
fake_client.generate.return_value = (nai_image,)
result = await mcp_client.call_tool("generate_image", {"prompt": "1girl"})
assert any(isinstance(block, ImageContent) for block in result.content)
运行它:
uv run --directory apps/server pytest apps/server/tests/test_tools.py::test_generate_image_with_v4_model -v