Testing Python code that uses Sailfork
Answer the SDK's requests from an httpx.MockTransport so tests of your code run without the network, for the sync and async clients.
The constructor takes your own httpx client, so a test can answer from an httpx.MockTransport and never touch the network. Pass token, so no lookup of the CLI's token runs, and a host of your choosing.
A sync test
import httpx
from sailfork import Held, NotFoundError, Sailfork
def handler(request: httpx.Request) -> httpx.Response:
if request.url.path == "/api/repos/acme/api/pulls/1/merge":
return httpx.Response(
202,
json={
"held": "req_1",
"kind": "merge",
"summary": "Merge #1",
"url": "/requests",
"message": "HELD FOR A PERSON: merge #1",
},
)
return httpx.Response(404, json={"code": "not_found", "error": "not found"})
sf = Sailfork(
"test-token",
host="https://sailfork.test",
http_client=httpx.Client(transport=httpx.MockTransport(handler)),
)
merge = sf.repo("acme/api").pull(1).merge()
assert isinstance(merge, Held)
assert merge.url == "https://sailfork.test/requests"
try:
sf.repo("acme/api").pull(2).get()
except NotFoundError as err:
assert err.status == 404 The SDK does not close a client you pass, so close it yourself when the test ends.
An async test
Pass an httpx.AsyncClient to AsyncSailfork. The handler stays a plain function.
import asyncio
import httpx
from sailfork import AsyncSailfork, NotFoundError
def handler(request: httpx.Request) -> httpx.Response:
return httpx.Response(404, json={"code": "not_found", "error": "not found"})
async def main() -> None:
http = httpx.AsyncClient(transport=httpx.MockTransport(handler))
async with AsyncSailfork("test-token", host="https://sailfork.test", http_client=http) as sf:
try:
await sf.repo("acme/api").pull(2).get()
except NotFoundError as err:
assert err.code == "not_found"
await http.aclose()
asyncio.run(main()) Check what your code sent
The handler receives the request, so a test can assert on the path, query, body and headers.
import json
import httpx
from sailfork import Sailfork
seen: list[httpx.Request] = []
def handler(request: httpx.Request) -> httpx.Response:
seen.append(request)
return httpx.Response(200, json={"changes": [], "dryRun": False})
sf = Sailfork(
"test-token",
host="https://sailfork.test",
http_client=httpx.Client(transport=httpx.MockTransport(handler)),
)
sf.repo("acme/api").caisson("c_1").batch(changes=[{"path": "a.txt", "content": "x"}])
request = seen[0]
assert request.method == "POST"
assert request.url.path == "/api/orgs/acme/caissons/c_1/batch"
assert json.loads(request.content) == {"changes": [{"path": "a.txt", "content": "x"}]}
assert request.headers["authorization"] == "Bearer test-token"
assert request.headers["sailfork-version"] == "2026-12-01"
assert request.headers["idempotency-key"] Answers and errors
- A canned answer has to match the model of the method you call. A bare
{}forpulls.getraises a pydanticValidationError, so copy a real answer, or call a method whose model has few required fields. - An error answer is JSON with
code,errorand optionallyparam,hint,docUrlandrequestId. The class raised follows thecode, as in Errors and retries. - A 202 body with
heldandmessagemakespulls.mergereturnHeld, as above. On any method that cannot be held, the same body raisesUnexpectedHeldErrorwithcode == "held". - Retries run against a mock, with real waits. Give a test of an error path
max_retries=0, or answer with a status that is not retried.
sf = Sailfork(
"test-token",
host="https://sailfork.test",
max_retries=0,
http_client=httpx.Client(transport=httpx.MockTransport(handler)),
) Tool loops
sailfork.tools.run(name, input, client=sf) takes the client, so a model loop is tested with the same mock. With client left out, run builds a client from the environment, which in a test would reach the network.
Next to the TypeScript version of this page: TypeScript testing.