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 FailureTemplate = "template" // A template in the step's with, vars or name could not be evaluated // The response broke the contract the action checked it against, such // as an OpenAPI document. FailureContractResponse = "contract_response" // The request broke the contract the action checked it against: the // workflow sent what the contract does not allow. FailureContractRequest = "contract_request" // The guard of the run, such as --read-only, refused what the step was // to do. FailureRefused = "refused" )
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 Contract ¶ added in v1.20.0
type Contract struct {
Spec string `json:"spec"` // The contract, such as the path of an OpenAPI document
Operation string `json:"operation"` // Such as GET /users/{id}
Response string `json:"response,omitempty"` // Such as 200, 2XX or default; empty when none is declared
}
Contract is what a response was matched to in a contract, which a report of the coverage of the contract counts.
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"`
// Violations are what broke the contract, when Kind is a contract's.
Violations []Violation `json:"violations,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"`
// RunID names the run, as actions are told it, such as in the trace
// header of the http action.
RunID string `json:"run_id,omitempty"`
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"`
// Contract is what the action matched the response to in the contract
// it checked it against, such as an operation of an OpenAPI document.
Contract *Contract `json:"contract,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.
type Violation ¶ added in v1.20.0
type Violation struct {
In string `json:"in"` // Where it was found: request or response
Field string `json:"field,omitempty"` // The field, such as /items/0/id
Reason string `json:"reason,omitempty"`
Message string `json:"message"`
}
Violation is one thing a contract does not allow.
Source Files