Test

Test YAML

Das vollständige Schema für Testsuiten, dateiweite Standardwerte, Testfälle, Assertions, Fixtures, Mocks und Freigabeentscheidungen.

Zuletzt aktualisiert 20. August 2026

Auf dieser Seite

YAML-Format

Jede Datei definiert einen oder mehrere Testfälle. Dateiweite defaults gelten für jeden Fall; Felder am einzelnen Fall überschreiben sie.

tests/stress-tester.yaml

version: "1.0"

# Standardwerte auf Dateiebene gelten für jeden Case.
# Angaben im einzelnen Case überschreiben diese Werte.
defaults:
  runs: 5                     # Agenten je Case fünfmal aufrufen
  success_threshold: 80       # vier von fünf Aufrufen müssen bestehen
  timeout_s: 60               # maximale Laufzeit je Aufruf

tests:
  - name: adds_two_numbers
    payload: '{"message": "add 4 and 6", "a": 4, "b": 6}'
    expected_result: status == "completed"
    expected_tool_calls:
      - math.calculator.add: invocations >= 1

  - name: plain_message_no_tools
    payload: "say hello"
    expected_result: status == "completed"
    expected_no_tool_calls:
      - math.calculator.add

  - name: high_concurrency_smoke
    payload: '{"message": "stress ping"}'
    runs: 20                  # override file default for this case
    success_threshold: 95
    expected_result: status == "completed"

Für mehrere Testsuiten desselben Agenten lässt sich der vom Dateinamen abgeleitete Standard mit dem Feld agent: überschreiben. Die beiden Dateien hier zielen jeweils auf stress-tester:

tests/stress-tester-load.yaml

# Eine zweite Suite für den Agenten stress-tester. Der Dateiname kann nicht ebenfalls
# stress-tester.yaml lauten (bereits vergeben), daher gibt diese Datei den Agenten
# explizit an und verwendet einen aussagekräftigeren Namen.
agent: stress-tester

defaults:
  runs: 50
  success_threshold: 90

tests:
  - name: sustained_burst
    payload: '{"message": "stress ping"}'
    expected_result: status == "completed"

Feldreferenz

Feld	Typ	Status	Beschreibung
version	string	Optional	Schema-Version.Standard: `"1.0"`
agent	string	Optional	Agent, auf den die Testsuite zielt. Standardmäßig wird der Dateiname ohne Endung verwendet (zum Beispiel tests/foo.yaml → foo). Das Feld lässt sich explizit festlegen, um eine große Testsuite für einen Agenten auf mehrere Dateien aufzuteilen.
defaults	object	Optional	Dateiweite Standardwerte, die für jeden Fall gelten. Felder am einzelnen Fall überschreiben sie.
runs	integer	Optional	Wie oft jeder Fall den Agenten aufruft. Bereich: 1–100.Standard: `1`
success_threshold	integer	Optional	Prozentanteil der Runs, die erfolgreich sein müssen, damit der Fall insgesamt besteht. Bereich: 1–100.Standard: `100`
timeout_s	integer	Optional	Zeitlimit für die gesamte Dauer eines Aufrufs in Sekunden. Bereich: 1–3600.Standard: `120`
mocks	string	Optional	Standardmodul zum Ersetzen von eigenem Code für jeden Fall in der Datei. Ein `mocks`-Wert im einzelnen Testfall überschreibt es. Siehe Tools und Lifecycle-Code mocken.
strict_mocks	boolean	Optional	Bei true schlägt ein Fall fehl, wenn der Agent ein nicht gemocktes eigenes dateibasiertes Tool aufruft. Diese Prüfung gilt nur für Tools; separate Flags legen fest, ob auch Middleware, Hooks und eigene Guardrails gemockt werden müssen. Ein `strict_mocks`-Wert im einzelnen Testfall überschreibt diesen. Siehe Tools und Lifecycle-Code mocken.Standard: `false`
strict_hook_mocks	boolean	Optional	Bei true schlägt ein Fall fehl, bevor eine konfigurierte Hook-Phase, die Mocks unterstützt, ohne passenden Ersatz ausgeführt wird. Fehlende Hook-Phasen sind ausgenommen. Ein `strict_hook_mocks`-Wert im einzelnen Testfall überschreibt diesen.Standard: `false`
strict_middleware_mocks	boolean	Optional	Bei true schlägt ein Fall fehl, bevor eine konfigurierte Middleware-Phase ohne passenden Mock ausgeführt wird. Fehlende Middleware-Phasen sind ausgenommen. Ein `strict_middleware_mocks`-Wert im einzelnen Testfall überschreibt diesen.Standard: `false`
strict_guardrail_mocks	boolean	Optional	Bei true schlägt ein Fall fehl, bevor ein konfigurierter eigener Guardrail ohne passenden Mock ausgeführt wird. Fehlende Phasen und integrierte Guardrails sind ausgenommen. Ein `strict_guardrail_mocks`-Wert im einzelnen Testfall überschreibt diesen.Standard: `false`
strict_approval_decisions	boolean	Optional	Bei true schlägt der Testfall fehl, wenn für eine ausstehende Freigabe keine passende Entscheidung hinterlegt ist oder nach der Ausführung ungenutzte Entscheidungen übrig bleiben. Ein `strict_approval_decisions`-Wert im einzelnen Testfall überschreibt diesen. Siehe Approvals testen.Standard: `false`
tests	object[]	Erforderlich	Testfälle. Mindestens einer ist erforderlich.
name	string	Erforderlich	Kennung des Testfalls innerhalb der Datei. Muss eindeutig sein und wird als Zeilentitel im Pipeline-Panel des Dashboards angezeigt.
payload	string	Optional	Agent-Input als String. JSON-Strings werden zu strukturiertem Input. Bei JSON-Ausgaben des Agenten unterstützt `expected_result` Punktzugriff, zum Beispiel `output.id == 10`. Erforderlich, sofern `builder` nicht gesetzt ist.
files	string[]	Optional	Einfache Dateinamen, die unter `tests/files/` liegen. Jede Datei wird Base64-codiert und unter `files` angehängt. Wenn `payload` ein JSON-Objekt ist oder ein `builder` ein Dictionary zurückgibt, bleiben dessen Schlüssel neben `files` auf oberster Ebene. Andere Payloads werden als `{message: payload}` übergeben. Siehe Dateianhänge.Standard: `[]`
builder	string	Optional	Name eines Python-Moduls unter `tests/builders/` (mit oder ohne Endung `.py`). Ersetzt das statische `payload` durch den Rückgabewert von `build(context, builder_args, test_name, payload, files)`. Siehe Dynamische Payload Builder.
builder_args	object	Optional	Beliebige Keyword-Argumente, die als Argument `builder_args` an `build()` und `cleanup()` weitergegeben werden. Damit lassen sich Fixtures variieren, ohne für jeden Fall einen eigenen Builder zu schreiben.
mocks	string	Optional	Name eines Python-Moduls unter `tests/mocks/` (mit oder ohne Endung `.py`), das Ersatzfunktionen für eigene dateibasierte Tools, Middleware-Phasen, Tool-Hooks und eigene Guardrails enthält. Eine passende Funktion ersetzt die jeweilige Phase. Ohne sie wird der reale Code ausgeführt, sofern das zugehörige Strict-Mock-Flag nicht aktiv ist. Vordefinierte und `api:`-Tool-Implementierungen sowie integrierte Guardrails werden real ausgeführt. Ausgehende Verbindungen aus Agenten-Tools und Middleware bilden die Ausnahme: Sie werden ohne Auslieferung erfasst. Siehe Tools und Lifecycle-Code mocken.
strict_mocks	boolean	Optional	Überschreibt `defaults.strict_mocks` für diesen Testfall. Bei true schlägt der Fall fehl, wenn er ein nicht gemocktes eigenes dateibasiertes Tool aufruft. Middleware-, Hook- oder Custom-Guardrail-Ersetzungen werden davon nicht gesteuert.
strict_hook_mocks	boolean	Optional	Überschreibt `defaults.strict_hook_mocks` für diesen Testfall. Der Testfall schlägt vor der Ausführung einer konfigurierten Hook-Phase fehl, wenn diese Mocks unterstützt und kein passender Mock vorhanden ist. Nicht konfigurierte Hook-Phasen sind ausgenommen.
strict_middleware_mocks	boolean	Optional	Überschreibt `defaults.strict_middleware_mocks` für diesen Testfall. Der Testfall schlägt vor der Ausführung einer konfigurierten Middleware-Phase fehl, wenn kein passender Mock vorhanden ist. Nicht konfigurierte Phasen sind ausgenommen.
strict_guardrail_mocks	boolean	Optional	Überschreibt `defaults.strict_guardrail_mocks` für diesen Testfall. Der Testfall schlägt vor der Ausführung eines konfigurierten eigenen Guardrails fehl, wenn kein passender Mock vorhanden ist. Nicht konfigurierte Phasen und integrierte Guardrails sind ausgenommen.
approval_decisions	object[]	Optional	Skriptbasierte HITL-Antworten. Jeder Eintrag enthält ein kanonisches `tool`, eine `decision` (`approve`, `reject` oder `timeout`) sowie optional einen `params`-Ausdruck und einen `reason`. Siehe Approvals testen.Standard: `[]`
strict_approval_decisions	boolean	Optional	Überschreibt `defaults.strict_approval_decisions` für diesen Testfall.
runs	integer	Optional	Überschreibt defaults.runs für diesen Testfall.
success_threshold	integer	Optional	Überschreibt defaults.success_threshold für diesen Testfall.
timeout_s	integer	Optional	Überschreibt defaults.timeout_s für diesen Testfall.
expected_result	string	Optional	Ausdruck, der mit den Variablen `output`, `error`, `status` und `context` ausgewertet wird. Fehlt das Feld, besteht der Fall, sobald der Run `completed` erreicht. Siehe Assertions und Expressions.
expected_tool_calls	list	Optional	Entweder einfache Tool-Namen (mindestens einmal aufgerufen) oder Mappings mit einem Schlüssel `{tool: <expr on invocations, params, and/or context>}`. Gemischte Einträge sind in derselben Liste erlaubt. Dasselbe Tool darf in mehreren Einträgen vorkommen, um unterschiedliche Argumentgruppen unabhängig zu prüfen.Standard: `[]`
expected_tool_call_order	string[]	Optional	Tool-Namen, die im Trace der Tool-Aufrufe des Runs in dieser relativen Reihenfolge erscheinen müssen. Dazwischen dürfen andere Tool-Aufrufe stattfinden.Standard: `[]`
expected_no_tool_calls	string[]	Optional	Tool-Namen, die während des Runs NICHT aufgerufen werden dürfen. Nützlich, um bei einer bedingten Tool-Auswahl unerwünschte Aufrufe auszuschließen.Standard: `[]`
expected_child_agents	object	Optional	Mapping aus dem Namen eines gestarteten Agenten auf Assertions für diesen untergeordneten Run. Jeder Eintrag akzeptiert dieselben Felder `expected_result` / `expected_tool_calls` / `expected_tool_call_order` / `expected_no_tool_calls` wie der Parent sowie ein eigenes verschachteltes `expected_child_agents` für tiefere Trigger-Ketten. Siehe Assertions für gestartete Agenten.Standard: `null`
expected_triggered	integer	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Mindestanzahl, wie oft der benannte untergeordnete Agent gestartet werden muss. Nützlich, wenn der Parent nur prüfen kann, ob ein Fire-and-Forget-Trigger stattgefunden hat.Standard: `1`
expected_payload	string	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Ausdruck, der mit dem Input ausgewertet wird, den der Parent an `trigger_agent` übergeben hat. Bindings: `payload` (als JSON geparst, wenn der Parent einen JSON-String übergeben hat, sonst der Rohwert), `payload_raw` (Stringdarstellung, `""`, falls nicht anwendbar) und `context`. Funktioniert auch bei Fire-and-Forget-Triggern, da die Payload beim Aufruf erfasst wird.
expected_result	string	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Dieselbe Ausdrucksgrammatik wie beim Feld auf oberster Ebene, ausgewertet mit der Ausgabe des untergeordneten Runs. Erfordert mindestens einen `wait_for_response=True`-Trigger.
expected_tool_calls	list	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Dieselbe Grammatik wie beim Feld auf oberster Ebene, ausgewertet mit den Tool-Aufrufen des untergeordneten Runs.Standard: `[]`
expected_tool_call_order	string[]	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Tool-Namen, die im Trace der Tool-Aufrufe des untergeordneten Runs in dieser relativen Reihenfolge erscheinen müssen.Standard: `[]`
expected_no_tool_calls	string[]	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Tools, die der untergeordnete Agent NICHT aufrufen darf.Standard: `[]`
expected_child_agents	object	Optional	(Innerhalb eines `expected_child_agents`-Eintrags.) Rekursive Assertions für Agenten, die dieser untergeordnete Agent seinerseits startet. Die Verschachtelung kann so tief sein wie die Trigger-Kette.Standard: `null`

Testing fortsetzen

Ersten Test schreiben

Ersten Agent-Test schreiben und ausführen

Assertions

Ausgaben, Tool-Aufrufe und untergeordnete Agenten prüfen

Fixtures und Mocks

Dateien, Zustand, Seiteneffekte und Freigaben steuern

Tests ausführen

CLI, Coverage-Bericht und Test-Gate verwenden