From a8eca22392004bc1b052b58c89b81bde7fcb8ba0 Mon Sep 17 00:00:00 2001 From: James Harris Date: Sun, 29 Nov 2020 07:14:22 +1000 Subject: [PATCH] Add report builder interfaces. --- internal/report/builder.go | 12 ------------ internal/report/finding.go | 36 ++++++++++++++++++++++++++++++++++++ internal/report/report.go | 16 ++++++++++++++++ internal/report/stage.go | 34 ++++++++++++++++++++++++++++++++++ 4 files changed, 86 insertions(+), 12 deletions(-) delete mode 100644 internal/report/builder.go diff --git a/internal/report/builder.go b/internal/report/builder.go deleted file mode 100644 index 13d867e8..00000000 --- a/internal/report/builder.go +++ /dev/null @@ -1,12 +0,0 @@ -package report - -// Builder is a utility for constructing test reprots. -type Builder struct { - Log func(string) -} - -func (b *Builder) AddFinding(f Finding) { -} - -func (b *Builder) Finalize() { -} diff --git a/internal/report/finding.go b/internal/report/finding.go index cfde81a9..36f4754a 100644 --- a/internal/report/finding.go +++ b/internal/report/finding.go @@ -62,3 +62,39 @@ const ( // Negative findings were discovered. Positive FindingPolarity = +1 ) + +// FindingBuilder is an interface for building a finding, which is a discovery +// made by observing the engine throughout the lifetime of a test. +type FindingBuilder interface { + // Summary adds an optional human-readable summary of the finding. + // + // If the Finding is a result of a failed Expectation the summary should + // give the best explanation as to why the failure occurred. + // + // For example, use "The handler that records this event has been disabled." + // in preference to "The expected event was not recorded.". + Summary(s string) + + // Evidence adds a "evidentiary" finding to this finding. + // + // An evidentiary finding is some finding that is used as supporting + // evidence for another finding. + Evidence() FindingBuilder + + // Content adds arbitrary content to the finding. + Content(heading, body string) + + // Suggestion adds a suggestion to the finding. + // + // A suggestion describes some recommended action that improves the Dogma + // application or otherwise fixes a problem encountered during a test. + // + // c is the suggestion caption, a brief description of what resulted in this + // activity. It must not be empty. It should be lower case without a + // trailing period, exclamation or question mark, similar to how Go error + // messages are formatted. + Suggestion(con SuggestionConfidence, c string) + + // Done marks the finding as complete. + Done() Finding +} diff --git a/internal/report/report.go b/internal/report/report.go index cbef250a..91b447a2 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -31,3 +31,19 @@ const ( // Passed indicates that a test passed. Passed ) + +// Builder is an interface for building a human-readable report on the +// behavior and result of a test. +type Builder interface { + // Stage adds a new "stage" to the report. A stage encapsulates the activity + // and findings that occurs within one part of the test. + // + // c is the stage's caption, a brief description of what resulted in this + // activity. It must not be empty. It should be lower case without a + // trailing period, exclamation or question mark, similar to how Go error + // messages are formatted. + Stage(c string) StageBuilder + + // Done marks the report as complete. + Done() Report +} diff --git a/internal/report/stage.go b/internal/report/stage.go index 8c707844..06b179ef 100644 --- a/internal/report/stage.go +++ b/internal/report/stage.go @@ -1,5 +1,7 @@ package report +import "github.com/dogmatiq/testkit/fact" + // Stage encapsulates the activity and findings that occurs within one part of // the test. type Stage struct { @@ -19,3 +21,35 @@ type Stage struct { // Findings is the set of discoveries made by analysing the transcript. Findings []Finding } + +// StageBuilder is an interface for building a report stage, which encapsulates +// the activity and findings that occurs within one part of the test. +type StageBuilder interface { + // TranscriptFact add a fact entry to the stage's transcript. + TranscriptFact(f fact.Fact) + + // TranscriptLog adds an arbitrary log message to the stage's transcript. + TranscriptLog(format string, args ...interface{}) + + // Content adds arbitrary content to the stage. + Content(heading, body string) + + // Finding adds a new finding to the stage. A finding is some discovery made + // by observing the engine throughout the lifetime of a test. + // + // c is the finding's caption, a brief description of what was discovered. + // It must not be empty. It should be lower case without a trailing period, + // exclamation or question mark, similar to how Go error messages are + // formatted. + // + // If the Finding is a result of an Expectation the caption should be + // phrased in terms of the expectation and not the cause of the + // expectation's passing or failing. + // + // For example, use "the expected DepositSubmitted event was not recorded" + // in preference to "no events were recorded at all". + Finding(p FindingPolarity, c string) FindingBuilder + + // Done marks the stage as complete. + Done() Stage +}