Ein Akzeptanz-Manifest im Repository anlegen

Das Akzeptanz-Manifest ist eine kleine JSON-Datei in Ihrem Repository. Sie sagt kanman, wie Ihre Anwendung in einer frischen Umgebung startet und wie die Akzeptanz-Spec einer Story läuft. Damit kann das Outcome-Gate jede Änderung belegen: Die Spec muss vor Beginn der Arbeit fehlschlagen und auf einem frischen Checkout bestehen, bevor der Pull Request mergebar wird.

Ohne Manifest lässt nur das Preset Testphase kanman arbeiten, und jedes Nachweispaket sagt, dass kein Ergebnisnachweis vorliegt.

Für eine typische Webanwendung brauchen Sie etwa 30 Minuten. Die vollständige Referenz aller Schlüssel steht unter .kanman/acceptance.json und .kanman/verify.json.

Was Sie hinzufügen

.kanman/
  acceptance.json        wie die App bereitgestellt und die Spec einer Story ausgeführt wird
  verify.json            Ihr lokaler Prüfbefehl (Lint, Typecheck, Tests)
  acceptance/
    README.md            optional: erklärt Ihrem Team den Ordner
    <KEY>/               ein Ordner pro Story, geschrieben von kanman

Die beiden JSON-Dateien schreiben Sie einmal. Die Specs unter .kanman/acceptance/<KEY>/ schreibt kanman aus dem Demonstrate-Block jeder Story.

Schritt 1: Die App mit einem Befehl starten

kanman braucht einen Weg, Ihre App von Grund auf zu starten, in einer Umgebung, in der sonst nichts läuft. Zwei Möglichkeiten:

Bei Docker Compose legen Sie eine eigene Datei an, zum Beispiel docker-compose.acceptance.yml, mit einem Health-Check, damit kanman weiß, wann die App bereit ist:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      PORT: "3000"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/health').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 2s
      timeout: 3s
      retries: 30

Legen Sie Testdaten in der Compose-Datei oder beim Start an. Specs müssen gegen die echte App laufen, nie gegen Mocks von ihr.

Schritt 2: .kanman/acceptance.json schreiben

Das ist das Manifest des öffentlichen Demo-Repositorys, das Playwright-Specs gegen eine Fastify-App ausführt:

{
  "version": 1,
  "provision": {
    "type": "docker_compose",
    "file": "docker-compose.acceptance.yml",
    "up": "docker compose -f docker-compose.acceptance.yml up -d --build --wait",
    "down": "docker compose -f docker-compose.acceptance.yml down -v"
  },
  "ready_url": "http://localhost:3000/api/invoices",
  "ready_timeout_seconds": 120,
  "setup": "npm ci && npx playwright install --with-deps chromium",
  "run": {
    "command": "npx playwright test",
    "spec_arg": ".kanman/acceptance/{KEY}/",
    "env": {
      "BASE_URL": "http://localhost:3000"
    }
  },
  "spec_dir": ".kanman/acceptance/{KEY}",
  "artifacts": [
    "test-results/**/trace.zip",
    "test-results/**/*.png",
    "test-results/**/*.webm",
    "test-results/results.json",
    "playwright-report/**"
  ]
}

Was die Teile bewirken:

• provision startet und stoppt die Umgebung.
• ready_url wird abgefragt, bis es antwortet; ready_timeout_seconds ist die maximale Wartezeit.
• setup installiert, was die Specs brauchen.
• run.command plus run.spec_arg führt die Specs einer Story aus. {KEY} wird zum Story-Key, zum Beispiel SBX-12.
• artifacts sind die Dateien, die kanman als Nachweis speichert: Traces, Screenshots, Videos, Berichte. Den einfachen Pfad test-results/results.json liest kanman als JSON-Bericht, daraus stammen die Testzahlen im Nachweispaket.

Schritt 3: .kanman/verify.json schreiben

Das Verify-Manifest ist der Befehl, den eine Entwicklerin vor dem Push ausführt. Er ist dafür gedacht, nach der Umsetzung vor den langsameren Gates zu laufen. kanman führt ihn noch nicht aus (siehe .kanman/verify.json), dieser Schritt ist also vorerst optional:

{
  "version": 1,
  "cwd": ".",
  "setup": "npm ci",
  "command": "npm run lint && npm run typecheck && npm test",
  "env": {
    "CI": "true"
  },
  "ci_var_keys": []
}

Brauchen Ihre Tests Werte aus der CI (etwa einen Lizenzschlüssel für ein Testwerkzeug), tragen Sie in ci_var_keys nur die Namen ein. Die Werte bleiben in Ihren CI-Einstellungen. kanman gibt diese Variablen noch nicht an den Executor weiter.

Schritt 4: Lokal ausprobieren

Führen Sie aus, was kanman ausführen wird, mit der Beispiel-Spec aus dem Demo-Repository oder einer eigenen:

docker compose -f docker-compose.acceptance.yml up -d --build --wait
npx playwright test .kanman/acceptance/EXAMPLE-1/
docker compose -f docker-compose.acceptance.yml down -v

Funktioniert das auf einem frischen Klon Ihres Repositorys, funktioniert es auch für kanman.

Schritt 5: Den Spec-Ordner schützen

Die Akzeptanz-Specs sind der Schiedsrichter, die Umsetzung darf sie also nie ändern. kanman setzt das selbst durch: Executors können nie in .kanman/acceptance/** schreiben, und der Diff-Wächter stoppt einen Run, wenn ein Commit den Ordner berührt. Wir empfehlen trotzdem eine zweite Sicherung in Ihrem Git-Host:

# .github/CODEOWNERS (GitHub) oder CODEOWNERS (GitLab)
/.kanman/ @your-org/tech-leads

Machen Sie außerdem den Commit-Status kanman/outcome-gate in Ihrem Branch-Schutz zum Pflicht-Status. Dann lässt sich ein Pull Request erst mergen, wenn das Outcome-Gate bestanden ist.

Schritt 6: Über einen Pull Request committen

Fügen Sie die Dateien in einem normalen Pull Request hinzu und mergen Sie ihn. Ab der nächsten Story wird kanman:

1. aus dem Demonstrate-Block eine Spec schreiben, wenn die Story Richtung Ready geht
2. prüfen, dass die Spec fehlschlägt und ihr eigenes Ziel nicht mockt, und sie dann auf den Branch kanman/spec/<KEY> committen
3. sie nach der Umsetzung gegen eine frische Umgebung ausführen, danach noch einmal auf einem frischen Checkout
4. die Artefakte speichern und im Nachweispaket verlinken

Andere Frameworks als Playwright

Das Manifest ist frameworkunabhängig. Setzen Sie framework auf playwright, vitest, jest, pytest oder other und richten Sie run.command auf Ihren Test-Runner:

{
  "version": 1,
  "provision": { "type": "docker_compose", "file": "docker-compose.acceptance.yml" },
  "ready_url": "http://localhost:8000/health",
  "run": { "command": "pytest", "spec_arg": ".kanman/acceptance/{KEY}/" },
  "framework": "pytest",
  "artifacts": ["reports/**"]
}

Häufige Probleme