Skip to content

Testing

Conformance is the bar

opennvr-adapter validate .                    # in-process, no server
opennvr-adapter conform http://localhost:9001 --token $TOKEN

validate drives the real ASGI app through FastAPI's test client, so it needs no port and belongs in CI on every commit. A green run means KAI-C will accept the adapter — the only assurance available without a deployment to try it in.

As a test:

def test_the_adapter_conforms_to_the_contract():
    """What `opennvr-adapter validate .` runs, as a test — so a change
    that breaks the contract fails in CI rather than at install time.

    The runner's client is duck-typed, so TestClient drives the real
    ASGI app with no port bound and no network."""
    base_url = "http://adapter.test"
    with TestClient(adapter.app, base_url=base_url) as client:
        report = ConformanceRunner(base_url, client=client).run_all()

    assert report.is_green, [
        (r.name, r.detail) for r in report.results
        if r.outcome == CheckOutcome.FAIL
    ]

The four tests worth writing about your model

  1. It answers in the contract shape, with coordinates in 0–1.
  2. A body the model cannot use is a 400, not a 500 — the distinction decides whether KAI-C retries.
  3. /capabilities advertises a task and a fingerprint — without the first the adapter gets no work, without the second it is exempt from drift detection.
  4. Health is honest about a failed load.

The scaffold ships all four; keep them green as the handler becomes real.

Before you ship

opennvr-adapter dev             # watch the model answer
opennvr-adapter validate .      # the conformance run
opennvr-adapter spec            # the OpenAPI document you will publish

dev picks its sample body from the handler you registered — a JPEG for @on_image, a WAV for @on_audio, a plain JSON body for @on_text — so an audio or text adapter is exercised through the field it actually declares. --image PATH substitutes your own file.

validate FAILs when /health reports error and WARNs when it reports loading, so a conformance run cannot go green on an adapter that never loaded.

Full example: 07_testing_and_conformance.py.