Documentation
¶
Overview ¶
Package report renders the result of a workflow run as files for machines and for people: JSON, JUnit XML, Markdown and the GitHub Actions job summary.
Index ¶
Constants ¶
const ( Passed = "passed" Failed = "failed" Skipped = "skipped" Untested = "untested" // A step that ran but has no test expression )
Report statuses for the workflow, jobs and steps.
const ( FailureAssertion = "assertion" // The test expression evaluated to false FailureTestError = "test_error" // The test expression could not be evaluated FailureTestType = "test_type" // The test expression did not evaluate to a boolean FailureAction = "action" // The action itself returned an error )
Failure kinds, the reasons a step fails.
Variables ¶
var ErrNoStepSummary = errors.New("GITHUB_STEP_SUMMARY is not set; skipping the github-summary report")
ErrNoStepSummary is returned for a github-summary report when no path was given and GITHUB_STEP_SUMMARY is not set, as on a machine outside GitHub Actions. It is not a failure: the same command line can run anywhere.
var ErrStepSummaryFull = errors.New("the job summary has no room left under GitHub's 1 MiB limit; skipping the github-summary report")
ErrStepSummaryFull is returned when earlier writes have left no room in the job summary for even a shortened page. Writing anyway would push it past GitHub's limit and lose what the earlier steps wrote, so nothing is written.
Functions ¶
This section is empty.
Types ¶
type Count ¶
type Count struct {
Total int `json:"total"`
Passed int `json:"passed"`
Failed int `json:"failed"`
Skipped int `json:"skipped"`
Untested int `json:"untested,omitempty"`
}
Count is a tally by status.
type Failure ¶
type Failure struct {
Kind string `json:"kind"`
Message string `json:"message"`
Request map[string]any `json:"request,omitempty"`
Response map[string]any `json:"response,omitempty"`
}
Failure says why a step failed.
type Job ¶
type Job struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
StartedAt time.Time `json:"started_at"`
DurationMs int64 `json:"duration_ms"`
Steps []Step `json:"steps"`
}
Job is one job of a Report.
type Repeat ¶
type Repeat struct {
Total int `json:"total"`
Success int `json:"success"`
Failure int `json:"failure"`
}
Repeat records the outcome of every iteration of a repeated job.
type Report ¶
type Report struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Status string `json:"status"`
StartedAt time.Time `json:"started_at"`
FinishedAt time.Time `json:"finished_at"`
DurationMs int64 `json:"duration_ms"`
Summary Summary `json:"summary"`
Jobs []Job `json:"jobs"`
}
Report is the result of a workflow run in a form meant for machines: the JSON file is this structure as is, and the other formats are rendered from it.
func (*Report) AddJob ¶
AddJob appends a job, counts it and its steps in the summary, and fails the report when the job failed.
func (*Report) Mask ¶
Mask hides secrets in every text the report carries, and credential headers in failed steps' requests and responses. It masks the data before it is rendered, because JSON and XML escape quotes, backslashes and ampersands, and a secret containing one would no longer match in the rendered file.
func (*Report) Write ¶
Write renders the report in the target's format and writes it to the target's path, creating parent directories as needed.
func (*Report) WriteJUnit ¶
WriteJUnit writes the report as JUnit XML.
func (*Report) WriteMarkdown ¶
WriteMarkdown writes the report as a Markdown page: a summary line, a table of jobs, and a section for every failed step with its test, the reason it failed, and the request and response. The page is meant to be read as is, for example as a GitHub job summary or by a coding agent.
type Step ¶
type Step struct {
Index int `json:"index"`
Name string `json:"name"`
Status string `json:"status"`
Test string `json:"test,omitempty"`
DurationMs int64 `json:"duration_ms"`
Retry *Retry `json:"retry,omitempty"`
Repeat *Repeat `json:"repeat,omitempty"`
Echo string `json:"echo,omitempty"`
Failure *Failure `json:"failure,omitempty"`
}
Step is one step of a Job.
type Target ¶
Target is one report file to write after a run.
func ParseTargets ¶
ParseTargets parses a comma separated list of format[=path] entries, such as "junit=out/junit.xml,json". A format without a path is written to its default file name in the current directory.
Source Files