blacksmith-testbox

Blacksmith Testbox

Umfang

Verwenden Sie Testbox, wenn Sie Remote-CI-Parität, injizierte Secrets, gehostete Dienste oder ein Betriebssystem-/Laufzeit-Image benötigen, das Ihre lokale Maschine nicht günstig bereitstellen kann.

Für OpenClaw ist Crabbox eine unterstützte Alternative, wenn Blacksmith nicht verfügbar ist oder genutzte Cloud-Kapazität bevorzugt wird.

Nutzen Sie Testbox nicht standardmäßig für jede lokale Test-/Build-Schleife. Wenn das Repository dokumentierte lokale Befehle für normale Iterationen hat, verwenden Sie diese zuerst, damit Sie warme Caches, lokalen Build-Status und schnelles Feedback behalten.

Testbox ist der teure Pfad. Greifen Sie bewusst darauf zurück.

OpenClaw-Maintainer können sich für die Testbox-zuerst-Validierung entscheiden, indem sie OPENCLAWC_TESTBOX=1 in ihrer Umgebung oder in festgelegten Agentenregeln setzen. Dieser Modus ist nur für Maintainer gedacht und erfordert Blacksmith-Zugriff.

Wenn OPENCLAWC_TESTBOX=1 in OpenClaw gesetzt ist:

• Wärmen Sie eine Testbox frühzeitig für längere, breitere oder unsichere Arbeiten vor.
• Bevorzugen Sie Testbox für pnpm-Gates, e2e, paketähnliche Nachweise und breite Suiten.
• Verwenden Sie dieselbe Testbox-ID für jeden Ausführungsbefehl in derselben Aufgabe/Sitzung.
• Verwenden Sie lokale Befehle nur, wenn die Aufgabe explizit OPENCLAWC_LOCAL_CHECK_MODE=throttled|full setzt oder wenn der Benutzer nach einem lokalen Nachweis fragt.

CLI installieren

Wenn blacksmith nicht installiert ist, installieren Sie es:

curl -fsSL https://get.blacksmith.sh | sh

Für den Canary-Kanal (neueste Entwicklungen):

BLACKSMITH_CHANNEL=canary sh -c 'curl -fsSL https://get.blacksmith.sh | sh'

Dann authentifizieren Sie sich:

blacksmith auth login

Agenten-gesteuerte Browser-Authentifizierung (nicht interaktiv)

Wenn ein Agent sicherstellen muss, dass der Benutzer authentifiziert ist, bevor Testbox-Befehle ausgeführt werden (z. B. Warmup, Run), verwenden Sie die browserbasierte Authentifizierung im nicht-interaktiven Modus. Dies öffnet den Browser, damit der Benutzer sich anmelden kann; der Agent interagiert nicht mit dem Browser. Die Organisationsauswahl im Dashboard wird übersprungen, sodass der Benutzer nur den Anmeldevorgang sieht.

Erforderlicher Befehl (--organization ist mit --non-interactive erforderlich):

blacksmith auth login --non-interactive --organization <org-slug>

Der Org-Slug kann aus der Umgebungsvariable BLACKSMITH_ORG oder dem globalen Flag --org stammen. Wenn keines gesetzt ist, sollte der Agent die bekannte Organisation des Projekts verwenden (z. B. aus der Repo-Konfiguration oder dem Benutzerkontext). Beispiel:

blacksmith auth login --non-interactive --organization acme-corp
blacksmith --org acme-corp auth login --non-interactive --organization acme-corp

Ablauf: Die CLI startet einen lokalen Callback-Server, öffnet den Browser zur Dashboard-Authentifizierungsseite und wartet bis zu 2 Minuten. Der Benutzer schließt die Anmeldung und Autorisierung im Browser ab. Das Dashboard leitet zu localhost mit dem Token weiter; die CLI speichert die Anmeldeinformationen und beendet sich. Der Agent fährt dann fort.

Verwenden Sie nicht --api-token für diesen Ablauf – das ist für die tokenbasierte Authentifizierung ohne Benutzeroberfläche gedacht. Dieser Skill konzentriert sich auf die browserbasierte Authentifizierung, wenn der Benutzer die Anmeldung über die Weboberfläche bevorzugt.

Optionale Flags:

• --dashboard-url <url> – Dashboard-URL überschreiben (z. B. für Staging)

Entscheiden Sie zuerst: lokal oder Testbox

Bevor Sie etwas vorwärmen, überprüfen Sie die eigenen Anweisungen des Repositorys.

Bevorzugen Sie lokale Befehle, wenn:

• das Repository einen unterstützten lokalen Test-/Build-Workflow dokumentiert
• Sie an Unit-Tests, Linting, Typprüfung, Formatierung oder anderen lokalen Validierungen iterieren
• der Wert aus warmen lokalen Caches und schnellen Wiederholungen kommt
• der Befehl keine Remote-Secrets, gehosteten Dienste oder CI-Only-Images benötigt

Bevorzugen Sie Testbox, wenn:

• das Repository explizit CI-Parität oder Remote-Validierung erfordert
• der Befehl Secrets, Service-Container oder bereitgestellte Infrastruktur benötigt
• Sie CI-Only-Fehler reproduzieren
• Sie die genaue Workflow-Image/Job-Umgebung aus GitHub Actions benötigen

Speziell für OpenClaw bleibt die normale lokale Iteration lokal, es sei denn, der Maintainer-Testbox-Modus ist mit OPENCLAWC_TESTBOX=1 aktiviert:

• pnpm check:changed
• pnpm test:changed
• pnpm test <path-or-filter>
• pnpm test:serial
• pnpm build

Wenn OPENCLAWC_TESTBOX=1 aktiviert ist, führen Sie dieselben Repo-Befehle innerhalb der warmen Testbox aus. Wenn der Benutzer für einen Befehl einen laptopfreundlichen lokalen Nachweis wünscht, verwenden Sie die explizite Ausweichmöglichkeit OPENCLAWC_LOCAL_CHECK_MODE=throttled.

Für den Nachweis installierbarer Pakete bevorzugen Sie den GitHub Package Acceptance-Workflow gegenüber einem ad-hoc Testbox-Befehl. Er löst einen Paketkandidaten auf (source=npm, source=ref, source=url oder source=artifact), lädt ihn als package-under-test hoch und führt die wiederverwendbaren Docker E2E-Strecken gegen dieses genaue Tarball auf GitHub/Blacksmith-Runnern aus. Verwenden Sie workflow_ref für den vertrauenswürdigen Workflow/Harness-Code und package_ref für den Quell-Ref, der beim Testen eines älteren vertrauenswürdigen Branches, Tags oder SHAs gepackt werden soll.

Einrichtung: Vorwärmen vor dem Codieren

Wenn Sie sich für Testbox entschieden haben, wärmen Sie eine frühzeitig vor. Dies gibt sofort eine ID zurück und startet die CI-Umgebung im Hintergrund, während Sie arbeiten:

blacksmith testbox warmup ci-check-testbox.yml
# → tbx_01jkz5b3t9...

Speichern Sie diese ID in der aktuellen Sitzung. Sie benötigen sie für jeden run-Befehl. Behandeln Sie blacksmith testbox list als Diagnose, nicht als wiederverwendbare Arbeitswarteschlange. Aufgelistete Boxen können auf Org-/Repo-Ebene sichtbar sein, während sie dennoch unbrauchbar oder veraltet für die aktuelle lokale Agentenstrecke sind.

Für den OpenClaw-Maintainer-Testbox-Modus wärmen Sie zu Beginn längerer oder breiterer Aufgaben vor:

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
pnpm testbox:claim --id <ID>

Verwenden Sie das Vorwärmen mit Build-Artefakten, wenn e2e-/Paket-/Build-Nachweise von gesäten dist/, dist-runtime/ und Build-All-Caches profitieren:

blacksmith testbox warmup ci-build-artifacts-testbox.yml --ref main --idle-timeout 90
pnpm testbox:claim --id <ID>

Das Vorwärmen startet einen GitHub Actions-Workflow, der eine VM mit der vollständigen CI-Umgebung bereitstellt: installierte Abhängigkeiten, gestartete Dienste, injizierte Secrets und ein sauberes Checkout des Repositorys auf dem Standard-Branch.

In OpenClaw sind rohe Commit-SHAs keine zuverlässigen Dispatch-Refs für warmup --ref; verwenden Sie einen Branch oder Tag. Der Build-Artefakt-Workflow löst openclaw@beta und openclaw@latest intern in SHA-Cache-Schlüssel auf.

Optionen:

--ref <branch|tag>     Git-Ref, gegen den ausgelöst wird (Standard: Standard-Branch des Repos)
--job <name>           Bestimmter Job innerhalb des Workflows (falls mehrere vorhanden)
--idle-timeout <min>   Leerlauf-Timeout in Minuten (Standard: 30)

KRITISCH: Immer vom Repo-Stammverzeichnis aus ausführen

Führen Sie blacksmith testbox-Befehle IMMER aus dem Stammverzeichnis des Git-Repositorys aus. Die CLI synchronisiert das aktuelle Arbeitsverzeichnis mit der Testbox über rsync mit --delete. Wenn Sie von einem Unterverzeichnis aus ausführen (z. B. cd backend && blacksmith testbox run ...), spiegelt rsync nur dieses Unterverzeichnis und löscht alles andere auf der Testbox – und entfernt damit andere Verzeichnisse wie dashboard/, cli/ usw.

# RICHTIG – vom Repo-Stammverzeichnis aus ausführen, Pfade im Befehl verwenden
blacksmith testbox run --id <ID> "cd backend && php artisan test"
blacksmith testbox run --id <ID> "cd dashboard && npm test"

# FALSCH – nicht in ein Unterverzeichnis wechseln, bevor die CLI aufgerufen wird
cd backend && blacksmith testbox run --id <ID> "php artisan test"

Wenn sich Ihre Shell in einem Unterverzeichnis befindet, wechseln Sie zuerst zurück zum Repo-Stammverzeichnis:

cd "$(git rev-parse --show-toplevel)"
blacksmith testbox run --id <ID> "cd backend && php artisan test"

Befehle ausführen

blacksmith testbox run --id <ID> "<command>"

Der run-Befehl wartet automatisch darauf, dass die Testbox bereit ist, falls sie noch startet. Sie können run also sofort nach dem Vorwärmen aufrufen, ohne den Status zuerst überprüfen zu müssen.

In OpenClaw bevorzugen Sie den abgesicherten Runner-Wrapper, damit veraltete/wiederverwendete IDs fehlschlagen, bevor die Blacksmith-CLI Zeit mit Synchronisieren verbringt oder eine verwirrende Fehlermeldung über fehlende Schlüssel ausgibt:

pnpm testbox:run --id <ID> -- "OPENCLAWC_TESTBOX=1 pnpm check:changed"

Der Wrapper weigert sich auszuführen, wenn der lokale Testbox-spezifische Schlüssel fehlt oder wenn die ID nicht von diesem OpenClaw-Checkout mit pnpm testbox:claim --id <ID> beansprucht wurde. Behandeln Sie das als erwartete Behebung, nicht als GitHub-Konto- oder normales SSH-Schlüsselproblem. Ein lokaler Schlüssel allein reicht nicht; eine bereite Box kann dennoch veralteten rsync-Status von einer anderen Strecke mit sich führen.

Wenn der Agent abstürzt, verlässt sich die Remote-Box auf den Leerlauf-Timeout von Blacksmith. Die lokale OpenClaw-Claim-Markierung wird nicht automatisch gelöscht, daher behandelt der Wrapper Claims, die älter als 12 Stunden sind, als veraltet. Überschreiben Sie dies nur für absichtlich langlebige Arbeiten mit OPENCLAWC_TESTBOX_CLAIM_TTL_MINUTES=<minutes>.

Bevor Sie ein breites Gate mit einem manuell zusammengestellten Befehl durchführen, können Sie auch Folgendes ausführen:

pnpm testbox:sanity -- --id <ID>

Dateien von einer Testbox herunterladen

Verwenden Sie den download-Befehl, um Dateien oder Verzeichnisse von einer laufenden Testbox auf Ihre lokale Maschine abzurufen. Dies ist nützlich zum Abrufen von Build-Artefakten, Testergebnissen, Coverage-Berichten oder anderen Ausgaben, die auf der Testbox generiert wurden.

blacksmith testbox download --id <ID> <remote-path> [local-path]

Der Remote-Pfad ist relativ zum Testbox-Arbeitsverzeichnis (dasselbe wie bei run). Wenn kein lokaler Pfad angegeben wird, wird die Datei mit demselben Basisnamen im aktuellen Verzeichnis gespeichert.

Um ein Verzeichnis herunterzuladen, hängen Sie ein / an den Remote-Pfad an – dies löst den rekursiven Modus aus:

# Einzelne Datei herunterladen
blacksmith testbox download --id <ID> coverage/report.html

# Datei an einen bestimmten lokalen Pfad herunterladen
blacksmith testbox download --id <ID> build/output.tar.gz ./output.tar.gz

# Ein gesamtes Verzeichnis herunterladen
blacksmith testbox download --id <ID> test-results/ ./results/

Optionen:

--ssh-private-key <path>   Pfad zum SSH-Private-Key (falls beim Vorwärmen --ssh-public-key verwendet wurde)

Wie die Dateisynchronisation funktioniert

Das Verständnis dieses Modells ist entscheidend für die korrekte Verwendung von Testbox.

Wenn Sie run aufrufen, führt die CLI eine Delta-Synchronisation Ihrer lokalen Änderungen auf die Remote-Testbox durch, bevor Ihr Befehl ausgeführt wird:

1. Die Testbox-VM startet mit einem sauberen actions/checkout auf dem Vorwärm-Ref. Die Einrichtungsschritte des Workflows (z. B. npm install, pip install, composer install) werden während des Vorwärmens ausgeführt und füllen die Abhängigkeitsverzeichnisse auf der Remote-VM.

2. Bei jedem run verwendet die CLI git, um zu erkennen, welche Dateien sich seit der letzten Synchronisation lokal geändert haben. Sie synchronisiert NUR getrackte Dateien und nicht getrackte, nicht ignorierte Dateien (d. h. Dateien, die git ls-files meldet).

3. .gitignore'd Verzeichnisse werden nie synchronisiert. Dies bedeutet, dass Verzeichnisse wie node_modules/, vendor/, .venv/, build/, dist/ usw. NICHT von Ihrer lokalen Maschine übertragen werden. Die Testbox verwendet ihre eigenen Kopien dieser Verzeichnisse, die während der Workflow-Schritte des Vorwärmens gefüllt werden.

4. Wenn sich seit der letzten Synchronisation nichts geändert hat (gleicher Git-Commit und Arbeitsbaum-Status), wird die Synchronisation aus Geschwindigkeitsgründen vollständig übersprungen.

Warum dies wichtig ist

• Änderung von Abhängigkeiten: Wenn Sie package.json, requirements.txt, composer.json, go.mod oder ähnliche Abhängigkeitsmanifeste ändern, wird die Manifest-Datei synchronisiert, aber das tatsächliche Abhängigkeitsverzeichnis NICHT. Sie müssen den Installationsbefehl auf der Testbox erneut ausführen:

  blacksmith testbox run --id <ID> "npm install && npm test"
  blacksmith testbox run --id <ID> "pip install -r requirements.txt && pytest"
  blacksmith testbox run --id <ID> "composer install && phpunit"
  

• Generierte/Build-Artefakte: Wenn Ihre Tests von einem Build-Schritt abhängen (z. B. npm run build, make) und Sie Quelldateien geändert haben, die die Build-Ausgabe beeinflussen, führen Sie den Build auf der Testbox erneut aus, bevor Sie testen.

• Neue nicht getrackte Dateien: Neue Dateien, die Sie lokal erstellen, werden synchronisiert (solange sie nicht gitignore'd sind). Sie müssen sie nicht zuerst git adden.

• Gelöschte Dateien: Dateien, die Sie lokal löschen, werden auch auf der Remote-Testbox gelöscht. Das Synchronisationsmodell hält die Remote mit Ihrem lokal verwalteten Dateisatz auf dem gleichen Stand.

KRITISCH: Lokale Tests nicht verbieten

Gehen Sie nicht davon aus, dass lokale Validierung verboten ist. Viele Repositories investieren absichtlich in schnelle, warme lokale Schleifen, und das Erzwingen jedes Durchlaufs über Testbox zerstört diesen Vorteil.

Verwenden Sie Testbox für die Prüfungen, die es tatsächlich benötigen: Remote-Parität, Secrets, Dienste, CI-Only-Runner oder Reproduzierbarkeit gegenüber dem Workflow-Image.

Wenn das Repository besagt, dass lokale Tests/Builds der normale Weg sind, folgen Sie dem Repository.

OpenClaw-Maintainer-Ausnahme: Wenn OPENCLAWC_TESTBOX=1 vom Benutzer oder der Agentenumgebung gesetzt ist, behandeln Sie Testbox als normalen Validierungspfad für dieses Repository. Verwenden Sie OPENCLAWC_LOCAL_CHECK_MODE=throttled|full als explizite lokale Ausweichmöglichkeit.

Wann zu verwenden

Verwenden Sie Testbox, wenn:

• Sie Datenbankmigrationen oder zerstörende Umgebungsprüfungen ausführen
• Sie Befehle ausführen, die von Secrets oder Umgebungsvariablen abhängen, die lokal nicht vorhanden sind
• Sie CI-Only-Fehler reproduzieren oder gegen das Workflow-Image validieren
• Sie Verhalten validieren, das bereitgestellte Dienste oder Remote-Runner benötigt
• Sie eine endgültige Paritätsprüfung vor dem Commit/Push durchführen, wenn das Repository oder der Benutzer dies wünscht

Kürzen Sie diese Liste basierend auf den Repository-Richtlinien. Wenn das Repository unterstützte lokale Tests/Builds dokumentiert, bevorzugen Sie lokale für Routineiterationen und behalten Sie Testbox für die Prüfungen, die Parität oder Remote-Status benötigen.

Workflow

1. Entscheiden Sie, ob die lokale Schleife des Repos die richtige Standardeinstellung ist. Für OpenClaw macht OPENCLAWC_TESTBOX=1 Testbox zum Maintainer-Standard.
2. Wenn Testbox gerechtfertigt ist, wärmen Sie frühzeitig vor: blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 → ID speichern, dann pnpm testbox:claim --id <ID>
3. Schreiben Sie Code, während die Testbox im Hintergrund startet.
4. Führen Sie den Remote-Befehl aus, wenn nötig: pnpm testbox:run --id <ID> -- "OPENCLAWC_TESTBOX=1 pnpm check:changed"
5. Wenn Tests fehlschlagen, korrigieren Sie den Code und führen Sie ihn erneut gegen dieselbe warme Box aus.
6. Wenn Sie Abhängigkeitsmanifeste (package.json usw.) geändert haben, stellen Sie den Installationsbefehl voran: blacksmith testbox run --id <ID> "npm install && npm test"
7. Wenn ein enger PR eine vollständige Synchronisation meldet oder die Box wiederverwendet/abgelaufen ist, überprüfen Sie die Remote-Kopie vor einem langsamen Gate auf Plausibilität: pnpm testbox:run --id <ID> -- "pnpm testbox:sanity". Wenn fehlende Stammdateien oder massenhafte gelöschte Trackte gemeldet werden, stoppen Sie die Box und wärmen Sie eine neue auf. Verwenden Sie OPENCLAWC_TESTBOX_ALLOW_MASS_DELETIONS=1 nur für eine absichtliche Bereinigung.