From 32f7b56d5d3c910da289a819d55eaf77cf601f89 Mon Sep 17 00:00:00 2001
From: James Harris <mailjamesharris@gmail.com>
Date: Sat, 28 Nov 2020 19:15:50 +1000
Subject: [PATCH] Add `Action.Caption()`

---
 action.advancetime.go | 7 +++++++
 action.call.go        | 4 ++++
 action.dispatch.go    | 7 +++++++
 action.go             | 9 +++++++++
 action_test.go        | 1 +
 5 files changed, 28 insertions(+)

diff --git a/action.advancetime.go b/action.advancetime.go
index 5378a53b..358bd92a 100644
--- a/action.advancetime.go
+++ b/action.advancetime.go
@@ -72,6 +72,13 @@ type advanceTimeAction struct {
 	loc location.Location
 }
 
+func (a advanceTimeAction) Caption() string {
+	return fmt.Sprintf(
+		"advancing time %s",
+		a.adj.Description(),
+	)
+}
+
 func (a advanceTimeAction) Banner() string {
 	return fmt.Sprintf(
 		"ADVANCING TIME (%s)",
diff --git a/action.call.go b/action.call.go
index a3ff7847..e5fc631f 100644
--- a/action.call.go
+++ b/action.call.go
@@ -37,6 +37,10 @@ type callAction struct {
 	loc location.Location
 }
 
+func (a callAction) Caption() string {
+	return "calling user-defined function"
+}
+
 func (a callAction) Banner() string {
 	return "CALLING USER-DEFINED FUNCTION"
 }
diff --git a/action.dispatch.go b/action.dispatch.go
index 4d1414fb..a56acbb4 100644
--- a/action.dispatch.go
+++ b/action.dispatch.go
@@ -44,6 +44,13 @@ type dispatchAction struct {
 	loc location.Location
 }
 
+func (a dispatchAction) Caption() string {
+	return inflect.Sprintf(
+		a.r,
+		"<producing> %t <message>",
+		a.m,
+	)
+}
 func (a dispatchAction) Banner() string {
 	return inflect.Sprintf(
 		a.r,
diff --git a/action.go b/action.go
index 81b5f391..d5a1261d 100644
--- a/action.go
+++ b/action.go
@@ -15,11 +15,20 @@ import (
 // Actions always attempt to cause some state change within the engine or
 // application.
 type Action interface {
+	// Caption returns the caption that should be used for this action in the
+	// test report.
+	//
+	// It must be formatted according to the documentation on the
+	// report.Step.Caption field.
+	Caption() string
+
 	// Banner returns a human-readable banner to display in the logs when this
 	// action is performed.
 	//
 	// The banner text should be in uppercase, and worded in the present tense,
 	// for example "DOING ACTION".
+	//
+	// DEPRECATED: TODO: remove
 	Banner() string
 
 	// Location returns the location within the code that the action was
diff --git a/action_test.go b/action_test.go
index 057da312..cb176ba3 100644
--- a/action_test.go
+++ b/action_test.go
@@ -16,6 +16,7 @@ type noopAction struct {
 	err error
 }
 
+func (a noopAction) Caption() string                             { return "[no-op]" }
 func (a noopAction) Banner() string                              { return "[NO-OP]" }
 func (a noopAction) Location() location.Location                 { return location.Location{Func: "<noop>"} }
 func (a noopAction) ConfigurePredicate(*PredicateOptions)        {}