Add report builder interfaces.

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
+}

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
+}

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
+}