Co-authored-by: Azeem Shaikh <azeems@google.com>
2.6 KiB
How to write a check
The steps to writting a check are as follow:
-
Create a file under
checks/
folder, saychecks/mycheck.go
-
Give the check a name and register the check:
// Note: export the name: start its name with an upper-case letter. const CheckMyCheckName string = "My-Check" func init() { registerCheck(CheckMyCheckName, EntryPointMyCheck) }
-
Log information that is benfical to the user using
checker.DetailLogger
:- Use
checker.DetailLogger.Warn()
to provide detail on low-score results. This is showed when the user supplies theshow-results
option. - Use
checker.DetailLogger.Info()
to provide detail on high-score results. This is showed when the user supplies theshow-results
option. - Use
checker.DetailLogger.Debug()
to provide detail in verbose mode: this is showed only when the user supplies the--verbosity Debug
option.
- Use
-
If the checks fails in a way that is irrecoverable, return a result with
checker.CreateRuntimeErrorResult()
function: For example, if an error is returned from an API you call, use the function. -
Create the result of the check as follow:
- Always provide a high-level sentence explaining the result/score of the check.
- If the check runs properly but is unable to determine a score, use
checker.CreateInconclusiveResult()
function. - For proportional results, use
checker.CreateProportionalScoreResult()
. - For maximum score, use
checker.CreateMaxScoreResult()
; for min score usechecker.CreateMinScoreResult()
. - If you need more flexibility and need to set a specific score, use
checker.CreateResultWithScore()
with one of the constants declared, such aschecker.HalfResultScore
.
-
Dealing with errors: see ../errors/errors.md.
-
Create unit tests for both low, high and inconclusive score. Put them in a file
checks/mycheck_test.go
. -
Create e2e tests in
e2e/mycheck_test.go
. Use a dedicated repo that will not change over time, so that it's reliable for the tests. -
Update the
checks/checks.yaml
with the description of your check. -
Generate
docs/check.md
usingmake generate-docs
. This will validate and generatedocs/check.md
. -
Update the README.md with a short description of your check.
For actual examples, look at checks/binary_artifact.go, checks/code_review.go and checks/frozen_deps.go.