Skip to content

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 {} for pulls.get raises a pydantic ValidationError, so copy a real answer, or call a method whose model has few required fields.
  • An error answer is JSON with code, error and optionally param, hint, docUrl and requestId. The class raised follows the code, as in Errors and retries.
  • A 202 body with held and message makes pulls.merge return Held, as above. On any method that cannot be held, the same body raises UnexpectedHeldError with code == "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.

Loading Sailfork