# AGENTS.md — test-samurai-vitest-runner

## Entwicklungsrichtlinien

### Rolle

TDD-first Entwickler. Jede neue Funktion, jedes neue Kommando und jede
Verhaltensänderung muss durch Tests abgesichert sein.

### Tests ausführen

```bash
bash run_test.sh
```

Tests nach jeder Code-Änderung ausführen. Bei Fehlern korrigieren, bis alles grün ist.

### Nicht raten

Bei unklaren oder mehrdeutigen Anforderungen Arbeit stoppen und Klarstellung
verlangen. `TODO`/`NOTE` im Code ist zulässig, stilles Raten nicht.

### Keine stillen Änderungen

Bestehende Features dürfen nicht unbemerkt geändert oder ersetzt werden.
Notwendige Anpassungen zur Koexistenz mehrerer Features müssen klar erkennbar sein.

### Sprache

Antworten immer auf Deutsch. Code-Bezeichner und `README.md` bleiben englisch.

## Runner-API

Der Runner implementiert alle 10 Pflichtfunktionen der test-samurai Runner-API.
Vollständige Spezifikation: `test-samurai/runner-agents.md`.

## Reporter

`reporter/test_samurai_vitest_reporter.js` ist ein ESM-Modul für Vitest 2.x.
Es emittiert pro Test eine Zeile `TSAMURAI_RESULT <json>` auf stdout.

### Payload-Schema

```json
{
  "name":     "Describe/Subtest",
  "status":   "passed | failed | skipped",
  "file":     "/absoluter/pfad/zur/test.ts",
  "location": { "line": 1, "column": 1 },
  "output":   ["Fehlermeldung Zeile 1", "Stack Trace ..."]
}
```

`name` verbindet die Describe-Hierarchie mit `/` (Beispiel: `MyComponent/renders/the slot`).

## Web-Components-Hinweise

Für Shadow-DOM-Tests benötigt Vitest eine geeignete DOM-Umgebung. Empfohlen:

- `happy-dom` oder `jsdom` als `environment` in `vitest.config.ts`
- Custom-Element-Registrierung in `vitest.setup.ts`

Der Runner erkennt `vitest.setup.ts` / `vitest.setup.js` automatisch und übergibt
sie via `--setupFiles`.

## Gitea CI

Der Workflow unter `.gitea/workflows/tests.yml` installiert Neovim per AppImage
(ARM64, Raspberry Pi 5) und führt `bash run_test.sh` aus.