Test-Suites und Prüfungen

Eine ganze Test-Suite aus der Oberfläche, der CLI oder per MCP ausführen, die antwortende Agent-Version wählen und prüfen, was der Agent tatsächlich getan hat.

Eine Test-Suite ist eine geordnete Liste von Testfällen, die als ein Testlauf ausgeführt wird. Jeder Testfall kann Prüfungen tragen: Regeln darüber, was der Agent getan hat. Sie werden aus dem Lauf selbst gelesen, nicht aus dem, was der Agent gesagt hat. Mit beidem lässt sich ein Agent jedes Mal gleich testen, zum Beispiel bei jeder neuen Version.

Eine Suite ausführen

Derselbe Lauf lässt sich an drei Stellen starten. Jede führt die Testfälle der Suite so aus, wie sie jetzt sind, in der Reihenfolge der Suite.

Web: Testing → Tests öffnen, Run Tests wählen und die Suite auswählen.
CLI: masaic test run --suite <suite-id> --wait endet mit einem Fehler, wenn der Lauf nicht bestanden ist. masaic test suites listet die Suites.
MCP: run-test-suite mit test_suite_id aufrufen und das Ergebnis mit get-test-run-result lesen. list-test-suites listet die Suites.

Eine Suite legt man mit masaic test suite create -f suite.yaml an (oder ändert sie mit update), per MCP mit create-test-suite und update-test-suite. Eine Suite-Datei braucht einen name und die geordneten testCaseIds; update braucht zusätzlich die id der Suite.

Die antwortende Agent-Version wählen

Jeder Testfall nennt einen Agenten und eine Umgebung und spricht standardmäßig mit der Version, die in dieser Umgebung deployt ist. Ein Testfall kann in seinem Formular auch auf eine Version festgelegt werden; die Version auf Auto lassen, außer der Testfall soll nur diese eine Version testen. Ein Lauf kann die Version für alle Testfälle auf einmal überschreiben, die Umgebung nicht:

Web: die Versionsauswahl im Dialog zum Starten, sobald die gewählten Testfälle zu einem Agenten gehören. Configured on test case behält die Festlegung jedes Testfalls, Latest active version ignoriert sie und nimmt, was in der Umgebung des Testfalls deployt ist, und eine gelistete Version (auch ein Entwurf) beantwortet jedes Gespräch.
CLI: --agent-version configured, latest oder <agent-version-id>.
MCP: agent_version_target (configured, latest oder specific), bei specific mit agent_version_id.

Um einen Entwurf zu testen, bevor er live geht, genau diese Version wählen: latest bedeutet die deployte Version, nicht die neueste.

Jedes Ergebnis nennt die Version, die in jedem Gespräch geantwortet hat. Das ist die Agent version in den Details des Gesprächs auf der Laufseite, agentVersionId in masaic test result und agent_version_id in get-test-run-result.

Prüfungen

Eine Prüfung besteht oder scheitert für sich, neben dem KI-Bewerter. Ein Testfall besteht nur, wenn jede Prüfung bestanden hat, die angewendet werden konnte. Eine Prüfung, die auf einen Lauf nicht anwendbar ist, wird mit Begründung übersprungen. Bewerten nur die Prüfungen und wurden alle übersprungen, gilt der Testfall als technischer Fehler, nicht als bestanden.

Prüfung	Besteht, wenn
Tool was called / not called	der Agent das genannte Tool aufgerufen (oder nie aufgerufen) hat. Das Tool so benennen, wie das Formular es listet, zum Beispiel `create-prompt`.
Tool ordering	das erste Tool vor dem zweiten aufgerufen wurde.
No write before tool	vor dem genannten Tool kein Tool lief, das Daten ändert. Ein Tool, das weder „nur lesend“ noch „zerstörend“ deklariert, lässt die Prüfung überspringen: Sie kann es nicht entscheiden.
Skill was used / not used	der Agent den genannten Skill genutzt (oder nie genutzt) hat.
Conversation ended as	das Gespräch als `goal_achieved`, `exit_intent` oder `max_turns_reached` endete. Nur bei Persona-, Mehrpersonen- und Sprachläufen.
Workspace object exists afterwards	nach dem Gespräch in diesem Workspace ein Prompt, Agent, Skill oder Testfall dieses Namens existiert, wahlweise während des Gesprächs erstellt.
Workspace object does not exist afterwards	nach dem Gespräch kein solches Objekt existiert.

Die Workspace-Prüfungen lesen nur diesen Workspace: Ein gleichnamiges Objekt in einem anderen Workspace zählt nicht. Die Tool-Prüfungen kennen die Tools der Agentenversion, die geantwortet hat, auch wenn der Agent aus einem anderen Workspace bereitgestellt wird.

Namen, die in jedem Lauf neu sind: `{{run}}`

Ein Testfall, der den Agenten etwas anlegen lässt, träfe beim zweiten Lauf auf „existiert bereits“. Stattdessen {{run}} in den Namen schreiben, zum Beispiel in das Anliegen („lege einen Prompt namens qa-{{run}} an“), das erwartete Ergebnis und die Prüfungen. Jeder Lauf ersetzt {{run}} durch ein eigenes kurzes Kürzel, jedes weitere Gespräch desselben Testfalls hängt -2, -3 usw. an, sodass jedes Gespräch einen neuen Namen anlegt und prüft. Die Gesprächsschritte eines Golden-Gesprächs bekommen denselben Namen.

Gemockte Tool-Antworten

Ein Testfall kann einem Tool des Agenten eine feste Antwort geben. In den Testgesprächen des Testfalls antwortet dieses Tool mit dem, was der Testfall vorgibt, statt seinen MCP-Server aufzurufen; jedes andere Tool ruft seinen echten Server auf. So bekommt der Agent Daten, die es sonst nirgends gibt, und das erwartete Ergebnis und die Prüfungen können sie benennen: „list-agents liefert qa-mocked-agent-7f3 — der Agent muss genau das berichten".

Web: im Formular des Testfalls Mocked tool answers → Add mocked tool: MCP-Server und Tool wählen und die Antwort als JSON schreiben (ein Objekt, eine Liste oder ein Text).
CLI: mockedToolAnswers in der Datei für masaic test create -f, eine Liste aus mcpServerId, toolName und answer.
MCP: mocked_tool_answers bei create-test-case und update-test-case.

Jede Antwort muss ein Tool nennen, das der Server in diesem Workspace anbietet, und nur ein lesendes Tool kann gemockt werden. Die Antworten gehören dem eigenen Mock-User des Testfalls: Bekommt ein Testfall gemockte Antworten, erhält er eine Kopie des Mock-Users, den er spielt (für den Agenten dieselbe Person), an dessen Stelle verknüpft, und die Antworten werden zu MCP-Fixtures dieses Mock-Users. Andere Testfälle, die den ursprünglichen Mock-User spielen, werden nicht mitgemockt. Ein Testfall mit gemockten Antworten hat deshalb höchstens einen Mock-User.

Die Kopie bleibt unsichtbar: Der Editor des Testfalls zeigt und bietet den Mock-User an, den sie kopiert, und keine Liste von Mock-Usern, keine Auswahl und kein Fixture-Dialog zeigt sie, sodass kein anderer Testfall sie spielen kann. Wird der Testfall in eine andere Umgebung verschoben, ziehen seine Antworten mit und werden dort geprüft; prod wird abgelehnt. Leert man die Antworten, verschwinden die Fixtures der Kopie.

Die Antworten gelten dort, wo das Target des Servers in der Umgebung des Testfalls nach einer Fixture fragt: bei einem Pass-through-Mock (der Server behält seinen echten Endpunkt; ein Gespräch, das einen Mock-User mit einer Fixture für das Tool spielt, bekommt die Fixture, jeder andere Aufruf erreicht den echten Server) oder einem einfachen Mock. Einstellen lässt sich das unter MCP targets by environment am Server (Web), mit set-mcp-server-target und use_mock plus mock_pass_through (MCP) oder mit masaic mcp-target set <server> --env dev --mock --pass-through --endpoint <url> (CLI). Antworten für einen Server, der in der Umgebung des Testfalls nicht gemockt ist, werden beim Speichern abgelehnt, mit dem Target, das zu ändern ist. Nie in einer Live-Umgebung, und nicht auf einer Installation ohne Mock-Server (Produktion): Dort erreicht ein Pass-through-Target einfach den echten Server. Dieselben Fixtures antworten auch einem Chat mit diesem Mock-User im Playground: nichts daran ist testspezifisch.

Ein Ergebnis markiert jeden Aufruf, den eine Fixture beantwortet hat (mocked answer bei den Tools des Gesprächs auf der Run-Seite, mocked: true in den Tool-Aufrufen von masaic test result und get-test-run-result).

Wie eine Mock-Antwort sich verhält

Eine Mock-Antwort kann mehr, als sofort zu antworten. Jede Mock-Antwort eines MCP-Servers kann außerdem:

warten, bevor sie antwortet, mit einer zufälligen Streuung um die Wartezeit, um zu testen, wie ein Agent mit einem langsamen Tool umgeht. Eine Wartezeit über dem Zeitlimit des Tools (60, 120 oder 300 Sekunden je nach Runtime-Profil) lässt den Aufruf ablaufen; so prüft ein Test, wie der Agent mit Timeouts umgeht;
absichtlich fehlschlagen mit einem Fehler deiner Wahl, bei jedem Aufruf oder bei einem Anteil davon, optional mit Code und „erneut versuchen nach“ (ein Rate Limit). Der Agent erhält ihn als Tool-Fehler;
nach den Argumenten des Aufrufs antworten: Regeln wie „wenn from gleich CGN ist und passengers mindestens 3, antworte dies“. Die erste Regel, deren Bedingungen alle zutreffen, antwortet, mit eigener Antwort und eigenen Einstellungen. Passt keine, gilt die Antwort selbst, oder der Aufruf schlägt fehl und nennt die nächstliegende Regel, damit du siehst, welche Bedingung nicht zutraf. Bedingungen vergleichen (gleich, ungleich, enthält, beginnt mit, eines von, vorhanden, fehlt, größer oder kleiner als); reguläre Ausdrücke gibt es nicht;
Platzhalter füllen: {{args.from}}, {{now}}, {{today}} und {{uuid}} im Text der Antwort werden pro Aufruf gefüllt, so dient eine Antwort vielen Aufrufen;
kaputt (abgeschnittenes JSON, eine HTML-Fehlerseite oder leer) oder übergroß zurückkommen, um zu testen, wie ein Agent mit einem defekten Tool umgeht.

Einzustellen im Dialog der Mock-Antwort unter Wie es antwortet (Web), mit behaviour bei create-mcp-mock-fixture und update-mcp-mock-fixture (MCP) oder mit masaic mcp-fixture create|update und Flags wie --delay 1500 --jitter 500 --error "too many requests" --error-rate 0.2, oder --behaviour @rules.json für Regeln (CLI). Die Tabelle der Mock-Antworten fasst die Einstellungen jeder Antwort zusammen. Ein Trace markiert, wie lange ein Pass-through-Mock gewartet hat und welche Regel geantwortet hat.

Die Suites des Masaic Agent

Der Workspace masaic enthält zwei Suites für den Masaic Agent selbst:

MASAIC Agent smoke: sechs reine Lese-Abfragen, drei Prüfungen auf Angelegtes und eine Abfrage gegen gemockte Tool-Antworten, in wenigen Minuten. Bei jeder neuen Version des Agenten ausführen.
MASAIC Agent full suite: alle Testfälle zum Anlegen und Erkunden, die Testfälle mit gemockten Tool-Antworten und der Testfall, in dem der Masaic Agent einen Test ausführt und berichtet, wie er ausging.

masaic test run --suite <smoke-suite-id> --wait