10. Testing¶
A server is used by a model that will try every argument you did not expect. Tests are how you find out first. Every stage of Shelf is tested in tests/test_book_shelf.py; this chapter walks through the patterns.
Calling tools in-process¶
await server.call_tool(name, arguments) runs a tool exactly as a client would, with shaping, policies and errors, but without a network:
result = await server.call_tool("books.search", {"query": "ada"})
assert result.structured_content["total"] > 0
assert result.meta["ouncemcp"]["result_tokens"] < 500
Use pytest with anyio (or pytest-asyncio) for async tests. Errors are results, not exceptions: check result.is_error and result.meta["ouncemcp"]["error"].
Writes: approvals and retries¶
A fresh server per test, and an approver that answers for the person:
@pytest.mark.anyio
async def test_step3_borrowing_needs_a_yes_and_happens_once():
step = module("step3_writes")
declined = step.build(approver=lambda request: False)
assert (
error_code(await call(declined, "loans.borrow", {"book_id": "b-001"}))
== "approval_declined"
)
assert declined.deps.writes == []
library = step.Library()
server = step.build(library, approver=lambda request: True)
loan = (await call(server, "loans.borrow", {"book_id": "b-002"})).structured_content
again = (await call(server, "loans.borrow", {"book_id": "b-002"})).structured_content
assert loan == again and library.writes == ["borrow b-002 by demo-member"] # replayed
mine = (await call(server, "loans.mine")).structured_content["loans"]
assert [l["loan_id"] for l in mine] == [loan["loan_id"]]
returned = (await call(server, "loans.return", {"loan_id": loan["loan_id"]})).structured_content
assert returned["returned"] and library.writes[-1] == f"return {loan['loan_id']}"
This one test checks the four things chapter 6 promised: a declined borrow changes nothing, an approved borrow happens, a repeated borrow is replayed rather than repeated, and returning works.
To test the question the person actually sees, connect a real FastMCP Client with an elicitation_handler and record the message; the book's tests check the exact preview text.
Callers and isolation¶
as_caller sets the verified identity for the code inside it, as if a token had been verified:
@pytest.mark.anyio
async def test_step4_members_see_only_their_branch_and_loans():
step = module("step4_secure")
server = step.build(approver=lambda request: True)
north_book = next(b.id for b in server.deps.books.values() if b.branch == "north")
with as_caller(**ANA):
loan = (await call(server, "loans.borrow", {"book_id": north_book})).structured_content
assert error_code(await call(server, "loans.open")) == "unknown_tool" # hidden from members
with as_caller(**BO):
assert error_code(await call(server, "books.get", {"id": north_book})) == "not_found"
assert (
error_code(await call(server, "loans.return", {"loan_id": loan["loan_id"]}))
== "not_found"
)
with as_caller(**LIBRARIAN):
open_loans = (await call(server, "loans.open")).structured_content["loans"]
assert [l["loan_id"] for l in open_loans] == [loan["loan_id"]]
assert server.deps.writes == [f"borrow {north_book} by ana"]
Write the intruder test for every tenant boundary: one tenant creates something, another tries to read, change or list it.
The security catalog¶
ouncemcp.eval.run_security_suite runs standard attacks against your server. It always probes guessed names for every tool with a policy, and runs the cases you add: cross-tenant reads, cursor and handle reuse, SSRF probes for URL arguments, and token passthrough.
@pytest.mark.anyio
async def test_step5_passes_the_security_catalog():
from ouncemcp.eval import CrossTenant, CursorReuse, run_security_suite
server = module("step5_complete").build(approver=lambda request: True)
report = await run_security_suite(
server,
[
CrossTenant("books.get", {"id": "b-002"}, owner=ANA, intruder=BO),
CursorReuse("books.search", {"query": "the", "limit": 1}, owner=ANA, intruder=BO),
],
)
assert report.passed, report.render_text()
Keeping definitions honest¶
Two more tests are worth having in every project:
from ouncemcp.cli import main
from ouncemcp.core.lints import lint_server
def test_check_passes():
assert main(["check", "server.py"]) == 0
assert lint_server(server) == []
Pin token counts too, if you care about them. await server.cost_report() measures the tools the current caller can see (for Shelf without a token, 1,109 tokens: the two librarian tools are hidden), and a test that fails when a definition grows makes the cost visible in review:
cost = await server.cost_report()
assert cost.total <= 1_200
assert {t.name: t.total for t in cost.tools}["books.search"] <= 250
Protocol conformance¶
OunceMCP itself is checked against the official MCP conformance suite in CI (ouncemcp.eval.conformance is the target server it runs against), so your server inherits a protocol layer that is known to conform. To test your own transport setup end to end, connect a FastMCP Client to the running server over HTTP or stdio in a test; see the testing guide.
Summary¶
server.call_toolruns a tool in-process with everything but the network.- Build a fresh server per test; answer approvals with
approver=. as_callersigns in as anyone; test every tenant boundary from both sides.- Run the security catalog and
checkin your test suite.