Tests ausführen & CI

Tests ad hoc ausführen

# YAML Suites rekursiv unter tests/ finden,
# jeden Case im ausgewählten Environment ausführen und
# mit Status 0 beenden, wenn alle Cases bestanden haben.
connic test

connic test verwendet die test_environment_id der standardmäßig ausgewählten Standardumgebung, falls sie gesetzt ist, siehe Environments. Andernfalls verwendet der Befehl das Environment selbst. Überschreibe oder filtere die Auswahl nach Bedarf:

# Nur Cases ausführen, deren Name den Substring enthält
connic test --filter adds_two_numbers

# Bestimmtes Environment für die Ausführung auswählen
connic test --env <environment-id>

# Maschinenlesbarer Output für CI
connic test --json

# Lokale Coverage pro Agent ausgeben, ohne Agent Tests auszuführen
connic test --coverage

Sobald Testfälle abgeschlossen sind, gibt die CLI eine Ergebnistabelle und einen Dashboard-Link aus. Öffne ihn für Agent Runs, Traces, Tool-Aufrufe und Ausgaben pro Testfall.

Der Exitcode ist 0, wenn jeder Testfall bestanden hat, 1 bei einem fehlgeschlagenen oder abgebrochenen Testlauf oder einem Fehler bei einer CLI-Anfrage und 2 bei einem Infrastruktur- oder Serverfehler.

Coverage Report

connic test --coverage erstellt einen statischen Bericht aus den lokalen Dateien in agents/ und tests/ und zeigt, für welche Agenten Testsuiten existieren und welche Tools deren Assertions abdecken. Der Bericht benötigt keine Zugangsdaten und führt keine Agententests aus.

Das Modell ist bewusst einfach:

• Jeder Agent zählt gleich. Einer von zehn vollständig abgedeckten Agenten ergibt insgesamt 10%, unabhängig von der Tool-Anzahl. So bleibt die Kennzahl aussagekräftig, wenn ein Agent 20 Tools und ein anderer 2 besitzt.
• Score pro Agent = abgedeckte Tools / alle Tools. Ein Tool gilt als abgedeckt, wenn es mindestens einmal in einem expected_tool_calls Eintrag des Agenten als Name oder Mapping oder in expected_tool_call_order erscheint. Für 100% muss jedes Tool des Agenten in mindestens einem Testfall vorkommen.
• Keine Testdatei → 0%. Ein Agent ohne passende Datei tests/<agent>.yaml trägt 0 zum Durchschnitt bei.
• Agenten ohne Tools → 100%, wenn eine Testdatei existiert. Sequential-Agenten und Orchestrators haben auf Tool-Ebene nichts abzudecken, daher genügt eine einzige Testdatei.
• A/B-Varianten werden übersprungen. Testvarianten wie support-test-fast teilen die Tools des Basisagenten und werden nicht mitgezählt.
• Discoverable Tools zählen ebenfalls. Sowohl tools als auch discoverable_tools sind Teil des Nenners.

Nicht abgedeckte Tools werden unter der Tabelle aufgeführt. Für den search-agent oben: web.fetch, web.summarize.

Kombiniere den Befehl mit --json, um einen maschinenlesbaren Bericht ({overall, agents: [{name, type, has_tests, tools_total, tools_covered, uncovered_tools, percent, parse_error}], error?}) für eine CI-Prüfung zu erhalten. Lass den Build zum Beispiel fehlschlagen, wenn die Gesamt-Coverage unter einen Schwellenwert fällt, der Bericht einen error enthält oder ein Agent einen parse_error meldet. Anders als connic test ist Coverage ein Bericht und kein Gate. Der Befehl mit formatierter Textausgabe endet nur dann mit einem Exitcode ungleich null, wenn die lokalen Eingaben für die Coverage-Analyse nicht geparst werden können.

PR Testing

Führe die Testsuite vor dem Merge gegen vorgeschlagene Änderungen aus Branches im verbundenen Repository aus. Wird ein Pull Request oder Merge Request geöffnet oder sein Head aktualisiert, checkt Connic den Head-Commit aus, führt dieselbe Pipeline wie connic test gegen das Environment aus, dessen Branch zum Zielbranch passt, und meldet das Ergebnis als Commit-Status. Pull Requests und Merge Requests aus Forks lösen keinen Run aus.

PR Testing unterstützt GitHub und GitLab und benötigt mindestens eine YAML-Datei unter tests/.

Das Deploy Gate

Ein Deployment mit erkannten YAML-Testsuiten durchläuft diese dreistufige Pipeline, unabhängig davon, ob connic deploy oder ein Git-Push zum verbundenen Branch es auslöst:

• 1. Build: Projekt validieren und die Dateien zu einem Deployment-Bundle zusammenstellen.
• 2. Tests: Jeden erkannten Testfall ausführen und seine Ergebnisse erfassen.
• 3. Deploy to {env name}: Nur aktivieren, wenn jeder Testfall bestanden hat. Andernfalls wird das Deployment als FAILED markiert.

Der Ablauf ist live auf der Deployment-Detailseite im Dashboard sichtbar. Jeder Schritt zeigt pending → in progress → done. Der Testschritt lässt sich aufklappen und zeigt dann jeden Testfall mit seinen einzelnen Aufrufen. Ein Klick auf einen Aufruf öffnet die Run-Detailansicht.

Test Environment überschreiben

Standardmäßig laufen Tests in der Deployment-Umgebung. Um sie von produktiven Abrechnungs-APIs und Daten zu isolieren, verweise unter Settings → Git & Environments → Test environment auf eine separate Umgebung desselben Projekts mit Test-Zugangsdaten und Verbindungen. Das Deploy Gate verwendet dieses Environment für den Testschritt und aktiviert das Deployment in der Zielumgebung, sobald jeder Testfall bestanden hat.

Gate überspringen

# Deploy erzwingen, auch wenn Tests fehlschlagen oder noch keine vorhanden sind.
# Nur in der CLI verfügbar; Git Auto-Deployments setzen diese Option nie.
connic deploy --skip-tests

--skip-tests ist nur in der CLI verfügbar und für Ausnahmefälle gedacht, etwa um einen Hotfix zu veröffentlichen, während ein unzuverlässiger Test untersucht wird. Git Auto-Deployments stellen die Option nie bereit.

Wo Testergebnisse erscheinen

• Deployments list: Jede Zeile enthält eine Tests-Spalte mit dem Pass-, Fail- oder Skipped-Status der Testsuite. Ad-hoc-Testläufe von connic test erscheinen mit einem violetten Test run Badge, das sie von regulären Deployments unterscheidet.
• Deployment detail → Pipeline: Die Timeline Build → Tests → Deploy mit Live-Status pro Step.
• Tests step (expanded): Eine Zeile pro Testfall mit Status, Success Ratio, Schwellenwert und einer anklickbaren Liste von Agenten-Run-IDs.
• Run history: Jeder Testaufruf landet in der Runs-Tabelle des Environments, in dem er ausgeführt wurde, und erhält ein violettes Badge zum Filtern oder Öffnen der Details.

Best Practices

Auch größere Testsuiten brauchen eine getrennte Testumgebung, verlässliches Aufräumen nach jedem Test und Assertions, die unerwünschte Verhaltensänderungen erkennen.

Separate Testumgebung einrichten

Erstelle unter Settings → Git & Environments eine separate Umgebung desselben Projekts, zum Beispiel staging-test, und verweise im Dropdown Test environment der Standardumgebung darauf. Das Deploy Gate und ad-hoc connic test verwenden diese Auswahl. Umgebungsvariablen, Verbindungen, Datenbankdaten, Retrieval-Inhalte und Agent Sessions sind nach Environment getrennt. Siehe Environments konfigurieren.

Übergib bei einmaligen CLI-Aufrufen --env <environment-id>, um das Environment explizit auszuwählen. Lass die meisten Testfälle bei runs: 1. Verwende mehr Runs mit einem niedrigeren success_threshold, wenn bei gleichen Eingaben unterschiedliche Ergebnisse zu erwarten sind.

Echte Tools mit Test-Zugangsdaten verwenden

Tests rufen konfigurierte Tools auf, sofern ein Testfall keine Mocks bereitstellt. Automatische ausgehende Verbindungen werden unterdrückt. Aufrufe ausgehender Verbindungen aus Agenten-Tools und Middleware werden als gemockte Tool-Aufrufe aufgezeichnet und nicht zugestellt. Verwende Test-Zugangsdaten und Test-Ressourcen für alle anderen externen Services wie Stripe und S3.

Verwende einen dynamischen Payload-Builder, wenn vor dem Agenten-Run Testdaten angelegt werden müssen, etwa ein Datensatz über eine API oder eine Webhook-Fixture. build() erstellt diese Testdaten und gibt den Input für den Agenten zurück. Variablen auf Modulebene werden im Builder für jeden Aufruf zurückgesetzt. Siehe Builder-Referenz.

Nach dynamischen Buildern aufräumen

Eine getrennte Testumgebung entfernt keine Testdaten aus externen APIs oder den Sandboxes anderer Anbieter. Implementiere cleanup(run, context, builder_args) neben build() und lösche angelegte Ressourcen anhand der in context gespeicherten IDs. cleanup() wird auch nach Timeouts und Fehlern des Agenten ausgeführt. Der Rückgabewert False lässt den Testfall fehlschlagen.

Agentenantwort und Tool-Aufrufe mit den Testdaten vergleichen

Auf die im Dictionary context gespeicherten Werte lässt sich über context.<key> auch in expected_result und expected_tool_calls zugreifen. Prüfe damit, ob der Agent genau die vom Builder erzeugte ID weitergereicht hat und nicht nur irgendeine ID im richtigen Format. Sonst könnte eine erfundene, aber formal gültige UUID den Test bestehen. Im folgenden Beispiel wird die ID im Builder gespeichert und dem Agenten in der Payload übergeben. Die Assertions vergleichen sowohl die Agentenantwort als auch die Tool-Argumente mit dieser ID:

tests:
  - name: fetches_the_row_we_just_inserted
    builder: insert_then_query
    expected_result: output.row.id == context.test_uuid
    expected_tool_calls:
      - db.fetch_row: params.uuid == context.test_uuid and invocations == 1

Der passende Builder steht unter Builder-Daten in YAML-Assertions prüfen.

Beide Zweige einer bedingten Tool-Auswahl prüfen

Wenn ein Agent anhand der Eingabe Tool A oder Tool B auswählt, schreibe zwei Testfälle: einen mit expected_tool_calls: [A] und expected_no_tool_calls: [B] und einen zweiten mit den umgekehrten Erwartungen. Ohne die Prüfung auf unerwünschte Aufrufe bestehen beide Testfälle, solange irgendein Tool aufgerufen wurde. Eine Regression, die A und B vertauscht, bleibt dann unentdeckt. Dasselbe Muster funktioniert für Freigaberegeln, bedingte Middleware und jede Verzweigung, bei der der tatsächlich ausgeführte Pfad geprüft werden muss.

Coverage als separaten PR Check behandeln

connic test --coverage --json läuft offline und führt keine Agententests aus. Ein separater CI-Job kann overall, den optionalen Top-Level error und jeden parse_error parsen und anschließend einen Coverage-Schwellenwert erzwingen oder fehlerhafte lokale Agenten und Testsuiten ablehnen. Siehe Format des Coverage-Berichts.