144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# runner-agents.md — test-samurai Runner-API
|
|
|
|
Ziel: Diese Datei beschreibt die öffentliche Runner-API, die ein neuer Runner
|
|
implementieren muss, damit alle Commands vollständig unterstützt werden.
|
|
|
|
## Modulform (Pflicht)
|
|
|
|
- Der Runner ist ein Lua-Modul, das eine Table mit Funktionen zurückgibt.
|
|
- Beispiel:
|
|
- `local runner = {}`
|
|
- `return runner`
|
|
|
|
## Pflichtfunktionen (volle Command-Unterstützung)
|
|
|
|
- `is_test_file(bufnr) -> boolean`
|
|
- Wird für die Runner-Auswahl genutzt.
|
|
- `find_nearest(bufnr, row, col) -> spec|nil, err?`
|
|
- Für `TSamNearest`.
|
|
- `spec.file` muss gesetzt sein.
|
|
- Bei Fehler/kein Treffer: `nil, "reason"` zurückgeben.
|
|
- `build_command(spec) -> command_spec`
|
|
- Für `TSamNearest`.
|
|
- `build_file_command(bufnr) -> command_spec`
|
|
- Für `TSamFile`.
|
|
- `build_all_command(bufnr) -> command_spec`
|
|
- Für `TSamAll`.
|
|
- `build_failed_command(last_command, failures, scope_kind) -> command_spec`
|
|
- Für `TSamFailedOnly`.
|
|
|
|
## Output-Parsing (Listing + Summary)
|
|
|
|
Genau eine der folgenden Varianten muss vorhanden sein:
|
|
|
|
- `parse_results(output) -> results`
|
|
- `results` muss enthalten:
|
|
- `passes` (Array von Namen)
|
|
- `failures` (Array von Namen)
|
|
- `skips` (Array von Namen)
|
|
- Optional:
|
|
- `display = { passes = {}, failures = {}, skips = {} }`
|
|
- `failures_all` (für Streaming-Parser, um alle bisherigen Failures zu liefern)
|
|
- Wenn `display` fehlt, werden `passes/failures/skips` direkt im Listing angezeigt.
|
|
- oder `output_parser() -> { on_line, on_complete }`
|
|
- `on_line(line, state)` kann `results` liefern (siehe oben).
|
|
- `on_complete(output, state)` kann `results` liefern (siehe oben).
|
|
|
|
## Detail-Output (TSamShowOutput / <cr> im Listing)
|
|
|
|
- `parse_test_output(output) -> table`
|
|
- Rückgabeform:
|
|
- `{ [test_name] = { "line1", "line2", ... } }`
|
|
- `test_name` muss mit `results.*` korrespondieren (gleiches Namensschema).
|
|
|
|
## Quickfix-Unterstützung (Failures)
|
|
|
|
- `collect_failed_locations(failures, command, scope_kind) -> items`
|
|
- `items`: Array von Quickfix-Items
|
|
- `{ filename = "...", lnum = <number>, col = <number>, text = "..." }`
|
|
|
|
## Erwartete Datenformen
|
|
|
|
- `command_spec`:
|
|
- `{ cmd = { "binary", "arg1", ... }, cwd = "..." }`
|
|
- `cmd` darf nicht leer sein.
|
|
- `cwd` ist optional; wenn nicht gesetzt, nutzt der Core das aktuelle CWD.
|
|
- `spec` (von `find_nearest`):
|
|
- Muss mindestens `file` enthalten, z. B.:
|
|
- `{ file = "...", cwd = "...", test_name = "...", full_name = "...", kind = "..." }`
|
|
|
|
## Optional empfohlene Metadaten
|
|
|
|
- `name` (String)
|
|
- Wird in Fehlermeldungen und Logs angezeigt.
|
|
- `framework` (String)
|
|
- Wird zur Framework-Auswahl (z. B. JS) genutzt.
|
|
|
|
## Prompt-Beispiel
|
|
|
|
"Erstelle mir anhand der `runner-agents.md` einen neuen Runner für Rust."
|
|
|
|
## Minimaler Runner-Skeleton (Template)
|
|
|
|
```lua
|
|
local runner = {
|
|
name = "my-runner",
|
|
framework = "my-framework",
|
|
}
|
|
|
|
function runner.is_test_file(bufnr)
|
|
return false
|
|
end
|
|
|
|
function runner.find_nearest(bufnr, row, col)
|
|
return nil, "no test call found"
|
|
end
|
|
|
|
function runner.build_command(spec)
|
|
return { cmd = { "echo", "not-implemented" }, cwd = spec.cwd }
|
|
end
|
|
|
|
function runner.build_file_command(bufnr)
|
|
return { cmd = { "echo", "not-implemented" } }
|
|
end
|
|
|
|
function runner.build_all_command(bufnr)
|
|
return { cmd = { "echo", "not-implemented" } }
|
|
end
|
|
|
|
function runner.build_failed_command(last_command, failures, scope_kind)
|
|
return { cmd = { "echo", "not-implemented" }, cwd = last_command and last_command.cwd or nil }
|
|
end
|
|
|
|
function runner.parse_results(output)
|
|
return { passes = {}, failures = {}, skips = {}, display = { passes = {}, failures = {}, skips = {} } }
|
|
end
|
|
|
|
function runner.parse_test_output(output)
|
|
return {}
|
|
end
|
|
|
|
function runner.collect_failed_locations(failures, command, scope_kind)
|
|
return {}
|
|
end
|
|
|
|
return runner
|
|
```
|
|
|
|
## Checkliste für neue Runner
|
|
|
|
- is_test_file implementiert
|
|
- find_nearest implementiert (setzt `spec.file`)
|
|
- build_command implementiert
|
|
- build_file_command implementiert
|
|
- build_all_command implementiert
|
|
- build_failed_command implementiert
|
|
- parse_results oder output_parser implementiert
|
|
- parse_test_output implementiert
|
|
- collect_failed_locations implementiert
|
|
- command_spec `{ cmd, cwd }` korrekt zurückgegeben
|
|
|
|
## Repository-Hinweis
|
|
|
|
- `README.md` bei Änderungen am Runner immer mit aktualisieren.
|