# 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

```python
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.

```python
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.

```python
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](https://sailfork.com/docs/sdk-python-errors).
- 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.

```python
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](https://sailfork.com/docs/sdk-typescript-testing).

---

Every docs page: https://sailfork.com/llms.txt
