pre-alpha

2.7 · Tutorial

6. Run and test it

Settings and serving

The Tracker example's factory assembles the HTTP routes, rules and MCP tool; the database field of its settings opens the database. It uses typed TrackerSettings; local SQLite is the default and TRACKER_DATABASE__URL selects another database.

from tracker import api
from tracker.rules import tracker_rules
from tracker.security import member_only
from tracker.settings import TrackerSettings
from hinoki import Hinoki
from hinoki.ai.mcpapp import expose_as_mcp


def create_app(database_url: str | None = None) -> Hinoki:
    overrides = {"database": {"url": database_url}} if database_url is not None else {}
    app_settings = TrackerSettings.load(overrides=overrides)
    app = Hinoki(
        settings=app_settings,
        title="Tracker",
        openapi_url="/openapi.json",
        docs_url="/docs",
        redoc_url="/redoc",
        rules=tracker_rules,
    )
    app.include(api.health, api.tasks)
    app.include(
        *expose_as_mcp(app, tools=[f"{api.__name__}.list_tasks"], access=member_only)
    )
    return app
# Omit these variables to use .hinoki/local.sqlite3.
export TRACKER_DATABASE__URL='postgresql://user:password@127.0.0.1:5432/tracker'
export HINOKI_DATABASE_URL="$TRACKER_DATABASE__URL"
uv run --project .. hinoki migrations status
uv run --project .. hinoki migrations sql --app tracker 0001-initial
uv run --project .. hinoki migrations sql --app tracker 0002-indexes
uv run --project .. hinoki migrations apply --app tracker
uv run --project .. hinoki dev tracker.app:create_app

The Tracker example already includes its initial and index migrations, so this command sequence inspects and applies those checked-in files. After changing a model, generate a new migration with hinoki migrations plan --app tracker and review its SQL before applying it to a disposable database; do not expect the planner to recreate the existing initial migration. dev reloads on change; serve runs without reload and takes host, port and workers from the server settings (serving). Open /docs or /redoc.

Test it

Operations need no HTTP at all, so test them directly; then drive the whole stack with the in-process client. The repository test fixture applies the migrations and creates the Ann and Ben members used by the bearer tokens below: tests/trackertest.py.

import os

import pytest

from tracker.app import create_app
from tracker.models import Member
from hinoki.testing import ASGIClient

URL = os.environ.get("HINOKI_TEST_DATABASE_URL")
needs_database = pytest.mark.skipif(URL is None, reason="no database")


@needs_database
async def test_tracker_api(members: tuple[Member, Member]) -> None:
    assert URL is not None
    async with ASGIClient(create_app(URL), strict_errors=True) as client:
        made = await client.post("/tasks", json={"title": "x"}, token="ann-token")
        path = f"/tasks/{made.body['id']}"
        assert (await client.post(f"{path}/complete", token="ben-token")).status == 404
        assert (await client.post(f"{path}/complete", token="ann-token")).status == 200
        assert (await client.post(f"{path}/complete", token="ann-token")).status == 409

This is an excerpt of test_every_business_error_of_the_tracker_is_declared; its members fixture creates the two users and provides a fresh migrated database. Run the repository test with a disposable PostgreSQL URL:

HINOKI_TEST_DATABASE_URL="$TRACKER_DATABASE__URL" uv run pytest tests/trackertest.py

strict_errors=True fails the test if an action answers an error it did not declare. For tests without async, use SyncClient.

Where next

Patterns and best practices, the application MCP (the tracker already exposes list_tasks to MCP clients), and development tools.