Capture action locations.

CHANGELOG.md

@@ -18,6 +18,7 @@ should continue to work without modification.
 ### Added
 
 - **[BC]** Added `PredicateOptions` to `PredicateScope`
+- **[BC]** Added `Action.Location()` method
 
 ### Changed
 

action.advancetime.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/dogmatiq/testkit/engine"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // AdvanceTime returns an Action that simulates the passage of time by advancing
@@ -26,7 +27,10 @@ func AdvanceTime(adj TimeAdjustment) Action {
 		panic("AdvanceTime(<nil>): adjustment must not be nil")
 	}
 
-	return advanceTimeAction{adj}
+	return advanceTimeAction{
+		adj,
+		location.OfCall(),
+	}
 }
 
 // A TimeAdjustment describes a change to the test's virtual clock.
@@ -65,6 +69,7 @@ func ByDuration(d time.Duration) TimeAdjustment {
 // clock.
 type advanceTimeAction struct {
 	adj TimeAdjustment
+	loc location.Location
 }
 
 func (a advanceTimeAction) Banner() string {
@@ -74,6 +79,10 @@ func (a advanceTimeAction) Banner() string {
 	)
 }
 
+func (a advanceTimeAction) Location() location.Location {
+	return a.loc
+}
+
 func (a advanceTimeAction) ConfigurePredicate(o *PredicateOptions) {
 }
 

action.advancetime_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/dogmatiq/testkit/internal/testingmock"
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/gomega"
+	. "github.com/onsi/gomega/gstruct"
 )
 
 var _ = Describe("func AdvanceTime()", func() {
@@ -91,6 +92,17 @@ var _ = Describe("func AdvanceTime()", func() {
 		}).To(PanicWith("AdvanceTime(<nil>): adjustment must not be nil"))
 	})
 
+	It("captures the location that the action was created", func() {
+		act := advanceTime(ByDuration(10 * time.Second))
+		Expect(act.Location()).To(MatchAllFields(
+			Fields{
+				"Func": Equal("github.com/dogmatiq/testkit_test.advanceTime"),
+				"File": HaveSuffix("/action.linenumber_test.go"),
+				"Line": Equal(50),
+			},
+		))
+	})
+
 	When("passed a ToTime() adjustment", func() {
 		targetTime := time.Date(2100, 1, 2, 3, 4, 5, 6, time.UTC)
 

action.call.go

@@ -1,6 +1,10 @@
 package testkit
 
-import "context"
+import (
+	"context"
+
+	"github.com/dogmatiq/testkit/location"
+)
 
 // Call is an Action that invokes a user-defined function within the context of
 // a test.
@@ -20,19 +24,27 @@ func Call(fn func()) Action {
 		panic("Call(<nil>): function must not be nil")
 	}
 
-	return callAction{fn}
+	return callAction{
+		fn,
+		location.OfCall(),
+	}
 }
 
 // callAction is an implementation of Action that invokes a user-defined
 // function.
 type callAction struct {
-	fn func()
+	fn  func()
+	loc location.Location
 }
 
 func (a callAction) Banner() string {
 	return "CALLING USER-DEFINED FUNCTION"
 }
 
+func (a callAction) Location() location.Location {
+	return a.loc
+}
+
 func (a callAction) ConfigurePredicate(o *PredicateOptions) {
 	o.MatchDispatchCycleStartedFacts = true
 }

action.call_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/dogmatiq/testkit/internal/testingmock"
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/gomega"
+	. "github.com/onsi/gomega/gstruct"
 )
 
 var _ = Describe("func Call()", func() {
@@ -186,4 +187,15 @@ var _ = Describe("func Call()", func() {
 			Call(nil)
 		}).To(PanicWith("Call(<nil>): function must not be nil"))
 	})
+
+	It("captures the location that the action was created", func() {
+		act := call(func() {})
+		Expect(act.Location()).To(MatchAllFields(
+			Fields{
+				"Func": Equal("github.com/dogmatiq/testkit_test.call"),
+				"File": HaveSuffix("/action.linenumber_test.go"),
+				"Line": Equal(51),
+			},
+		))
+	})
 })

action.dispatch.command_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/dogmatiq/testkit/internal/testingmock"
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/gomega"
+	. "github.com/onsi/gomega/gstruct"
 )
 
 var _ = Describe("func ExecuteCommand()", func() {
@@ -139,4 +140,15 @@ var _ = Describe("func ExecuteCommand()", func() {
 			ExecuteCommand(nil)
 		}).To(PanicWith("ExecuteCommand(<nil>): message must not be nil"))
 	})
+
+	It("captures the location that the action was created", func() {
+		act := executeCommand(MessageC1)
+		Expect(act.Location()).To(MatchAllFields(
+			Fields{
+				"Func": Equal("github.com/dogmatiq/testkit_test.executeCommand"),
+				"File": HaveSuffix("/action.linenumber_test.go"),
+				"Line": Equal(52),
+			},
+		))
+	})
 })

action.dispatch.event_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/dogmatiq/testkit/internal/testingmock"
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/gomega"
+	. "github.com/onsi/gomega/gstruct"
 )
 
 var _ = Describe("func RecordEvent()", func() {
@@ -141,4 +142,15 @@ var _ = Describe("func RecordEvent()", func() {
 			RecordEvent(nil)
 		}).To(PanicWith("RecordEvent(<nil>): message must not be nil"))
 	})
+
+	It("captures the location that the action was created", func() {
+		act := recordEvent(MessageE1)
+		Expect(act.Location()).To(MatchAllFields(
+			Fields{
+				"Func": Equal("github.com/dogmatiq/testkit_test.recordEvent"),
+				"File": HaveSuffix("/action.linenumber_test.go"),
+				"Line": Equal(53),
+			},
+		))
+	})
 })

action.dispatch.go

@@ -7,6 +7,7 @@ import (
 	"github.com/dogmatiq/configkit/message"
 	"github.com/dogmatiq/dogma"
 	"github.com/dogmatiq/testkit/internal/inflect"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // ExecuteCommand returns an Action that executes a command message.
@@ -15,7 +16,11 @@ func ExecuteCommand(m dogma.Message) Action {
 		panic(fmt.Sprintf("ExecuteCommand(%T): %s", m, err))
 	}
 
-	return dispatchAction{message.CommandRole, m}
+	return dispatchAction{
+		message.CommandRole,
+		m,
+		location.OfCall(),
+	}
 }
 
 // RecordEvent returns an Action that records an event message.
@@ -24,14 +29,19 @@ func RecordEvent(m dogma.Message) Action {
 		panic(fmt.Sprintf("RecordEvent(%T): %s", m, err))
 	}
 
-	return dispatchAction{message.EventRole, m}
+	return dispatchAction{
+		message.EventRole,
+		m,
+		location.OfCall(),
+	}
 }
 
 // dispatchAction is an implementation of Action that dispatches a message to
 // the engine.
 type dispatchAction struct {
-	r message.Role
-	m dogma.Message
+	r   message.Role
+	m   dogma.Message
+	loc location.Location
 }
 
 func (a dispatchAction) Banner() string {
@@ -42,6 +52,10 @@ func (a dispatchAction) Banner() string {
 	)
 }
 
+func (a dispatchAction) Location() location.Location {
+	return a.loc
+}
+
 func (a dispatchAction) ConfigurePredicate(o *PredicateOptions) {
 }
 

action.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/dogmatiq/configkit"
 	"github.com/dogmatiq/testkit/engine"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // Action is an interface for any action that can be performed within a test.
@@ -20,6 +21,10 @@ type Action interface {
 	// for example "DOING ACTION".
 	Banner() string
 
+	// Location returns the location within the code that the action was
+	// constructed.
+	Location() location.Location
+
 	// ConfigurePredicate updates o with any options required by the action.
 	//
 	// It is called before Do() when the action is used with Test.Expect().

action.linenumber_test.go

@@ -0,0 +1,53 @@
+package testkit_test
+
+// This file contains definitions used within tests that check for specific line
+// numbers. To minimize test disruption edit this file as infrequently as
+// possible.
+//
+// New additions should always be made at the end so that the line numbers of
+// existing definitions do not change. The padding below can be removed as
+// imports statements added.
+
+import (
+	"github.com/dogmatiq/dogma"
+	. "github.com/dogmatiq/testkit"
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+	// import padding
+)
+
+func advanceTime(adj TimeAdjustment) Action { return AdvanceTime(adj) }
+func call(fn func()) Action                 { return Call(fn) }
+func executeCommand(m dogma.Message) Action { return ExecuteCommand(m) }
+func recordEvent(m dogma.Message) Action    { return RecordEvent(m) }

action_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 
 	. "github.com/dogmatiq/testkit"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // noop is an Action that does nothing.
@@ -16,5 +17,6 @@ type noopAction struct {
 }
 
 func (a noopAction) Banner() string                              { return "[NO-OP]" }
+func (a noopAction) Location() location.Location                 { return location.Location{Func: "<noop>"} }
 func (a noopAction) ConfigurePredicate(*PredicateOptions)        {}
 func (a noopAction) Do(ctx context.Context, s ActionScope) error { return a.err }

engine/internal/aggregate/controller.go

@@ -10,7 +10,7 @@ import (
 	"github.com/dogmatiq/testkit/engine/internal/panicx"
 	"github.com/dogmatiq/testkit/envelope"
 	"github.com/dogmatiq/testkit/fact"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // Controller is an implementation of engine.Controller for

engine/internal/aggregate/scope.go

@@ -9,7 +9,7 @@ import (
 	"github.com/dogmatiq/testkit/engine/internal/panicx"
 	"github.com/dogmatiq/testkit/envelope"
 	"github.com/dogmatiq/testkit/fact"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // scope is an implementation of dogma.AggregateCommandScope.

engine/internal/integration/scope.go

@@ -9,7 +9,7 @@ import (
 	"github.com/dogmatiq/testkit/engine/internal/panicx"
 	"github.com/dogmatiq/testkit/envelope"
 	"github.com/dogmatiq/testkit/fact"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // scope is an implementation of dogma.IntegrationCommandScope.

engine/internal/panicx/unexpectedbehavior.go

@@ -5,7 +5,7 @@ import (
 
 	"github.com/dogmatiq/configkit"
 	"github.com/dogmatiq/dogma"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // UnexpectedBehavior is a panic value that occurs when a handler exhibits some

engine/internal/panicx/unexpectedmessage.go

@@ -5,7 +5,7 @@ import (
 
 	"github.com/dogmatiq/configkit"
 	"github.com/dogmatiq/dogma"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // UnexpectedMessage is a panic value that provides more context when a handler

engine/internal/process/controller.go

@@ -12,7 +12,7 @@ import (
 	"github.com/dogmatiq/testkit/engine/internal/panicx"
 	"github.com/dogmatiq/testkit/envelope"
 	"github.com/dogmatiq/testkit/fact"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // Controller is an implementation of engine.Controller for

engine/internal/process/scope.go

@@ -10,7 +10,7 @@ import (
 	"github.com/dogmatiq/testkit/engine/internal/panicx"
 	"github.com/dogmatiq/testkit/envelope"
 	"github.com/dogmatiq/testkit/fact"
-	"github.com/dogmatiq/testkit/internal/location"
+	"github.com/dogmatiq/testkit/location"
 )
 
 // scope is an implementation of dogma.ProcessEventScope and