Documentation
¶
Overview ¶
discover.go provides adapter-declared artefact discovery for the execute command's lazy automation-record creation (ENH-136).
When gtms execute encounters a test case with no automation record, the execute command calls TryAutoCreateRecord. If the resolved adapter declares an artefact-glob pattern, DiscoverArtefact walks the project tree to find matching artefact files. On exactly one match, CreateAutomationRecord is called to create the missing record so execution can continue.
The glob pattern supports {testcase} variable substitution and ** for recursive directory matching. filepath.Glob does NOT support **, so this package uses filepath.Walk with custom matching.
identity.go provides the executed-by precedence resolver introduced by ENH-125. The chain is:
- CLI flag (--executed-by)
- Environment variable (GTMS_EXECUTED_BY)
- git config user.name from the project repo
An empty result is acceptable — the field stays unset on records and the YAML marshaller omits the key via `omitempty`.
migrate.go provides a one-shot migration function for pre-release automation records that still use the old field names (ENH-123).
The migration renames YAML keys:
last-formal-result -> result last-formal-run -> executed_artefact last-formal-run-at -> executed_at log -> notes log-spill -> notes-spill defect (string) -> defect ([]string)
New fields (executed_by, environment) are left blank. The migration is idempotent: records already using new names are skipped.
Package pipeline bridges transient result contracts to permanent git-committed records. It creates automation records from completed automate tasks and updates them with execution results.
record.go provides a reusable record-write primitive for creating automation records from caller-supplied options. This is the shared logic used by gtms link (ENH-111) and, in the future, gtms automate (ENH-112/113).
The existing BuildAutomationRecord function in pipeline.go is tightly coupled to TaskFile + ResultContract. CreateAutomationRecord takes a RecordOptions struct instead, making it usable from any caller that has the required data.
Index ¶
- func AbsArtefactPath(projectRoot, artefactPath string) string
- func BuildAutomationRecord(projectRoot string, tf *task.TaskFile, rc *result.ResultContract) error
- func CreateAutomationRecord(projectRoot string, opts RecordOptions) error
- func DiscoverArtefact(projectRoot, globPattern, testCaseID string) (string, error)
- func HashBytes(data []byte) string
- func HashFile(path string) (string, error)
- func MigrateAutomationRecords(projectRoot string) (int, error)
- func ResolveArtefact(projectRoot, storedPath, testCaseID string) (string, error)
- func ResolveExecutedBy(ctx context.Context, projectRoot, flag string) string
- func UpdateExecutionResult(projectRoot string, tf *task.TaskFile, rc *result.ResultContract) error
- func WriteAutomationRecord(path string, record *AutomationRecord) error
- type AutoCreateOptions
- type AutomationRecord
- type RecordCommon
- type RecordOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AbsArtefactPath ¶ added in v0.2.0
AbsArtefactPath returns the absolute path for an artefact, resolving relative paths against projectRoot.
func BuildAutomationRecord ¶
BuildAutomationRecord creates or updates an automation record from a completed automate task. The record is stored at gtms/automation/records/{tc-id}.automation.md.
func CreateAutomationRecord ¶ added in v0.2.0
func CreateAutomationRecord(projectRoot string, opts RecordOptions) error
CreateAutomationRecord creates or overwrites an automation record. Shared logic:
- Ensure gtms/automation/records/ directory exists
- Check for existing record -- refuse without Force, increment cycle with Force
- Normalise artefact path (filepath.ToSlash)
- Compute artefact SHA-256 hash
- Build AutomationRecord struct with caller values + computed fields
- Write via WriteAutomationRecord
Returns an error if the record already exists and Force is false.
func DiscoverArtefact ¶ added in v0.2.0
DiscoverArtefact performs adapter-declared artefact discovery for a test case. It substitutes {testcase} in the glob pattern, walks the project tree, and returns exactly one project-relative artefact path.
Returns ("", nil) when globPattern is empty (no discovery configured). Returns ("", error) on zero matches, multiple matches, or path-safety violations.
The glob pattern supports:
- Standard filepath.Match wildcards (*, ?)
- ** for recursive directory matching (zero or more levels)
- {testcase} variable substitution
The walk skips .git/, .gtms/, and the sentinel parent directory per ADR-014.
func HashBytes ¶ added in v0.4.0
HashBytes returns the SHA-256 hash of data after line-ending normalization, truncated to 16 hex characters.
func HashFile ¶ added in v0.2.0
HashFile returns the SHA-256 hash of the file at path, truncated to 16 hex chars. Used by execute (to store) and reader commands (to compare).
func MigrateAutomationRecords ¶ added in v0.2.0
MigrateAutomationRecords walks gtms/automation/records/ and migrates any records that still use the old field names to the new ENH-123 schema. Returns the count of records migrated. Records already in the new format are skipped (idempotent).
func ResolveArtefact ¶ added in v0.2.0
ResolveArtefact returns the actual path to an artefact file. It tries storedPath first (fast, exact). If the file exists on disk at the stored path, it is returned immediately — the basename is NOT checked for the TC ID (ENH-110: the basename check was dropped to support shared-file frameworks like Playwright grouped tests where the TC ID lives only in the test name, not the filename).
When the stored path is empty or the file does not exist on disk, the function falls back to globbing for files whose name contains the TC ID, excluding .git/, .gtms/, and the sentinel-discovered parent directory per ADR-014 + ENH-098/ADR-017.
Directory exclusion rules:
- .git/ and .gtms/: basename-matched at any depth (historically safe).
- Sentinel parent (e.g. "gtms/" or "testing/"): root-anchored only via filepath.Rel — nested directories with the same name are NOT excluded.
layout.ParentDir reads a synchronized snapshot of the configured layout.
Returns the resolved path, or error if zero or multiple matches found.
func ResolveExecutedBy ¶ added in v0.2.0
ResolveExecutedBy applies the ENH-125 precedence chain to determine the identity to record on permanent records. The function never returns an error: any failure (no git, no user.name configured, etc.) yields an empty string and the caller writes nothing.
projectRoot is used as the working directory for the git invocation so repository-local config overrides global config consistently.
func UpdateExecutionResult ¶
UpdateExecutionResult updates an automation record with execution results.
func WriteAutomationRecord ¶
func WriteAutomationRecord(path string, record *AutomationRecord) error
WriteAutomationRecord writes an automation record to the given path as markdown with YAML frontmatter.
Types ¶
type AutoCreateOptions ¶ added in v0.2.0
type AutoCreateOptions struct {
TestCaseID string // required: TC ID (e.g. "tc-abc12345")
Framework string // required: framework name from adapter resolution
AdapterName string // required: resolved adapter name for provenance
Branch string // optional: current git branch
ArtefactGlob string // the glob pattern from adapter config (empty = no discovery)
}
AutoCreateOptions carries caller-provided values for lazy record creation at execute time. The execute command populates this from the resolved adapter and current git state.
type AutomationRecord ¶
type AutomationRecord struct {
RecordCommon `yaml:",inline"`
Artefact string `yaml:"artefact,omitempty"`
Adapter string `yaml:"adapter,omitempty"`
LastDevResult string `yaml:"last-dev-result,omitempty"` // pass, fail, or error
Attempts int `yaml:"attempts,omitempty"`
Summary string `yaml:"summary,omitempty"`
NotesSpill string `yaml:"notes-spill,omitempty"` // ENH-077: relative path to .gtms/logs/{task-id}.log when notes was truncated (was log-spill)
Cycle int `yaml:"cycle"`
ExecutedArtefact string `yaml:"executed_artefact,omitempty"` // path to executed artefact (was last-formal-run)
ArtefactHash string `yaml:"artefact-hash,omitempty"`
TestCaseHash string `yaml:"testcase-hash,omitempty"` // ENH-117: SHA-256 of the test case spec at record-write time
ResultsFile string `yaml:"results-file,omitempty"` // ENH-109: pointer to per-test results YAML in gtms/execution/
}
AutomationRecord represents a permanent automation record stored in gtms/automation/records/. It embeds RecordCommon for the shared field schema and adds automation-specific fields.
func FindAutomationRecord ¶
func FindAutomationRecord(projectRoot, testCaseID, framework string) (*AutomationRecord, string, error)
FindAutomationRecord looks for a framework-qualified automation record for the given test case ID. The framework parameter determines which record to find (e.g. "bats" -> tc-xxx--bats.automation.md). Returns the record and its path, or nil if not found.
func ReadAutomationRecord ¶
func ReadAutomationRecord(path string) (*AutomationRecord, error)
ReadAutomationRecord reads an automation record from the given path.
func TryAutoCreateRecord ¶ added in v0.2.0
func TryAutoCreateRecord(projectRoot string, opts AutoCreateOptions) (*AutomationRecord, string, error)
TryAutoCreateRecord attempts lazy record creation when no automation record exists and the resolved adapter declares artefact discovery. Called by the execute command at both missing-record gates.
Returns the created record and its path, or (nil, "", nil) when auto-create is not applicable (empty glob pattern). Returns (nil, "", error) on discovery or creation failure.
type RecordCommon ¶ added in v0.2.0
type RecordCommon struct {
TestCase string `yaml:"testcase"`
Framework string `yaml:"framework,omitempty"`
Status string `yaml:"status"` // developed, accepted
Result string `yaml:"result,omitempty"` // pass, fail, error, or skipped (was last-formal-result)
ExecutedAt string `yaml:"executed_at,omitempty"` // RFC3339 UTC timestamp (was last-formal-run-at)
ExecutedBy string `yaml:"executed_by,omitempty"` // CI runner identity or tester name
Environment string `yaml:"environment,omitempty"` // target environment (staging, production, etc.)
Branch string `yaml:"branch,omitempty"`
Defect []string `yaml:"defect,omitempty"` // linked defect IDs (was string; ENH-123 changed to array)
Notes string `yaml:"notes,omitempty"` // diagnostic output / tester notes (was log)
}
RecordCommon holds fields shared between automation records and (future) manual result records. Both embed RecordCommon to share a uniform schema for dashboard rendering. Introduced by ENH-123 as a CON-020 prerequisite.
type RecordOptions ¶ added in v0.2.0
type RecordOptions struct {
TestCase string // required: TC ID (e.g. "tc-abc123")
Framework string // required: framework name (e.g. "playwright")
Artefact string // required: path to test file
Adapter string // required: provenance (e.g. "manual-link", "claude-playwright")
LastDevResult string // required: "linked", "verified", "pass", "fail", "error"
Branch string // optional: current git branch
Summary string // optional: adapter output summary
Log string // optional: adapter log output
Environment string // ENH-125: optional target environment (e.g. staging, production)
ExecutedBy string // ENH-125: optional pre-resolved identity (flag → env → git user.name)
Force bool // if true, overwrite existing record and clear execute history
}
RecordOptions carries caller-provided values for record creation. The primitive handles shared plumbing: directory creation, existing-record detection, cycle counting, path normalisation, artefact hashing, write.