Go Test

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Run a Go module’s or workspace’s tests, scoped to whatever the caller asked for, and report a compact pass/fail summary parsed from the go test -json event stream. It is a report-only skill: it never fixes a failing test, modifies source or test code, edits go.mod/go.sum, re-vendors, or starts containers unless asked to as a follow-up.

Purpose

Go projects differ in layout and in how their tests are split. iru-go-test detects the toolchain, tells modules from go.work workspaces (where ./…​ does not cross module boundaries), respects vendored dependencies (-mod=vendor is automatic, and inconsistent vendoring is reported rather than bypassed with -mod=mod), and decides whether the race detector can run. It separates fast, container-free tests from container-backed ones behind the integration build tag, runs exactly the requested selection with -count=1 so cached results are never reported as a fresh run, and parses the event stream with an embedded stdlib Python parser. Only leaf subtests are counted and listed, in-process testscript failures are reported by their FAIL: <script>.txtar:<line> line, and build failures, package-level failures (timeouts, TestMain) and packages with no test files are reported separately and plainly, never as "0 tests".

For a Bubble Tea project it also applies the catalog’s UI contract (see Building user interfaces): the project’s UI tests are ordinary in-process tests that write the stripped view as .txt into .ui-screenshots/, so Step 4a only prepares the directory (UI_SCREENSHOTS_DIR, default <repo root>/.ui-screenshots, prefixed onto the go test/gotestsum command), clears it only on a full unscoped run, reads the accessibility level from .ui-quality.yml (none or off means the checks are not applicable and are reported as "accessibility: opted out" or "accessibility checks off", never unverified or failed), and afterwards validates capture names and counts captures and accessibility rule ids with an embedded stdlib Python script. No lock is needed. == Purpose group

Go Development Tooling

Plugin

Shipped by the iru-go plugin of the ai-catalog marketplace (install with /plugin install iru-go@ai-catalog; see Plugins).

Invocation

/iru-go-test
/iru-go-test <package patterns>

Optional key: value lines may follow the package patterns.

Inputs

Argument Required Description Default

package patterns

No

Space- or comma-separated patterns such as ./internal/cli/…​, ./internal/greet or a full import path. A .go file path is mapped to its directory.

./…​ (expanded to one ./<dir>/…​ per module when a go.work root is not itself a module).

run: <regex>

No

Passed as -run; / separates subtest levels (for example TestScripts/greet).

Not set — all tests.

skip: <regex>

No

Passed as -skip.

Not set.

tags: <comma list>

No

Passed as -tags. integration selects the container-backed tests.

Not set — the fast, container-free selection.

race: yes|no

No

Whether to run with the race detector.

yes when cgo is available or on macOS, otherwise no with a note.

junit: yes|no

No

Write build/test-results/go-test.xml through gotestsum when it is installed.

no

ui: auto|yes|no

No

Whether to apply Step 4a (terminal-UI captures, .ui-quality.yml level, capture-name validation). yes forces it, no skips it.

auto — applied when go.mod requires Bubble Tea (v2 charm.land/bubbletea/v2 or v1).

lock: held

No

A line passed by a calling skill that already holds .integration-test.lock, so this skill neither acquires nor releases it.

Not set — the skill takes the lock itself for container-backed runs.

Outputs

  • A plain-text summary in the conversation: the Go version, module and scope, flags used (-race, -count=1, fast or integration selection), counts of packages, tests, passed, failed and skipped, and for each failing leaf test <package>.<Test/sub> with the first line of its message.

  • Build failures ([build failed], [setup failed]) and package-level failures outside any test (timeouts, TestMain, os.Exit) listed separately; packages with no test files summarized in one line.

  • A run that matched nothing is reported as "no test files" or "`run:` matched no test", and a missing race detector or gotestsum is said plainly.

  • An integration run that could not happen is reported as unverified (Docker unavailable, blocked by a concurrent run), never as passed or as failed tests; environment failures such as an unreachable Docker daemon are classified as such.

  • Wiring problems (inconsistent vendoring, missing go.sum entry, toolchain too old) are named as such, never papered over.

  • For a terminal-UI project (Step 4a): the capture directory and whether it was cleared (full run) or kept (scoped run), captures per kind (component/screen/flow), malformed names (count + first few paths), accessibility violations as counts per rule id (from failing tests under enforce, from a11y-report.txt under report) and the .ui-quality.yml level applied. Terminal UIs have no automated accessibility audit; the checks are the asserted tui-color-only, tui-help-line and tui-keyboard ones, and the report says so.

  • build/test-results/go-test.json (and go-test.xml with junit: yes), kept when build/ is gitignored.

  • No source or test code is ever modified.

Execution flow

flowchart TD A["Start /iru-go-test\n(optional patterns and key: value lines)"] --> B["Step 0: parse patterns,\nrun, skip, tags, race, junit, lock"] B --> C["Step 1: detect toolchain,\nmodule vs workspace, vendoring"] C --> D{"Go installed and\ntest files present?"} D -- no --> E["Stop: report toolchain missing\nor no test files"] D -- yes --> F["Step 2: decide on\nthe race detector"] F --> G["Step 3: classify fast vs\nintegration"] G --> G2["Step 4a: terminal UI project?\nresolve UI_SCREENSHOTS_DIR, clear on full run,\nread .ui-quality.yml level"] G2 --> H["Step 4: build the go test -json\ncommand, optional gotestsum JUnit"] H --> I{"Container-backed\nrun?"} I -- no --> K["Run go test once,\nwrite the JSON event stream"] I -- yes --> J["Step 5: check Docker and\nacquire .integration-test.lock"] J --> L{"Docker up and\nlock acquired?"} L -- no --> M["Report integration as\nunverified"] L -- yes --> K K --> N["Release the lock\non every exit path"] N --> O["Step 6: read exit code and\nparse the event stream"] O --> O2["Step 4a: validate capture names,\ncount captures and a11y rule ids"] O2 --> P["Step 7: report counts, failing\nleaf tests, build and package failures"] M --> O2

Dependencies

Invokes

None — iru-go-test is a leaf skill; it only runs go, optional gotestsum, a stdlib Python parser and the lock commands, and reports on their output.

Invoked by

  • Go Code One Task Group — scoped tests per bucket, the full fast suite with the race detector (with ui: yes for a terminal-UI project, as the full UI run that clears and refills .ui-screenshots/), and the container-backed run (tags: integration with lock: held), via the iru-gate-runner agent.

Its flag handling, toolchain detection and Step 6 event parsing are also reused by Go Coverage, and its module and workspace layout rules by Go Code Quality.

Related agents

  • iru-gate-runner — calling skills normally run it inside this sub-agent. It spawns no agents itself.

Source

SKILL.md on GitHub — the file this page was generated from.