| name | gotit-add-helper |
| description | Register a programmatic Go function under tests/e2e/helpers/ that builds a test repository with custom commit history, then wire it into runner_test.go's RepoHelpers map. Invoke when a spec needs renames, multi-commit history, branches, or other state a static fixture cannot express. |
| version | 1 |
gotit-add-helper
Add a RepoHelper — a Go function that builds a test repo programmatically.
When to use a helper vs a fixture
Use a helper when the test needs any of:
- Multiple commits with specific messages, authors, or order.
- File renames detected by
git log --follow.
- Co-change windows — N commits touching the same files.
- Branches, conflicts, or merges.
- Time-deterministic commits.
Otherwise prefer a fixture (see gotit-add-fixture).
Steps
-
Pick a name describing the repo shape (e.g. two-commit-rename, co-change-trio, branch-conflict).
-
Create the helper package if it doesn't exist: tests/e2e/helpers/helpers.go. The package name is helpers.
-
Write the function with this exact signature:
import (
"github.com/shivamstaq/gotit/runner"
)
func TwoCommitRename(_, workDir string, _ map[string]any) error {
if err := runner.GitInit(workDir); err != nil {
return err
}
if err := runner.WriteFile(filepath.Join(workDir, "old.txt"), "hello\n"); err != nil {
return err
}
if err := runner.GitCommitAll(workDir, "initial"); err != nil {
return err
}
if err := runner.RunGit(workDir, "mv", "old.txt", "new.txt"); err != nil {
return err
}
return runner.GitCommitAll(workDir, "rename: old.txt -> new.txt")
}
The runner ships GitInit, GitCommitAll, RunGit, WriteFile, CopyDir as helpers — use them rather than re-shelling.
-
Register in tests/e2e/runner_test.go:
RepoHelpers: map[string]runner.RepoHelper{
"two-commit-rename": helpers.TwoCommitRename,
},
The map key is what specs reference; it can differ from the Go function name.
-
Reference from a spec:
repo:
helper: two-commit-rename
-
Verify: run a spec that uses the helper.
Anti-patterns
- Helpers that depend on global state (working directory of the host process, env vars beyond what the runner sets). They run inside an isolated temp dir; everything must be relative to
workDir.
- Helpers that re-implement
git init / git commit by hand. Use the runner's helpers — they set deterministic env (GIT_AUTHOR_*, GIT_CONFIG_NOSYSTEM=1).
- Catch-all helpers with
if args[...] branches for ten different shapes. One helper per repo shape; common setup goes in unexported helpers.
References
