Add ToExecuteCommandType[T]() and ToRecordEventType[T]() expectat…

…ions.

CHANGELOG.md

@@ -10,6 +10,18 @@ The format is based on [Keep a Changelog], and this project adheres to
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
 
+## [0.15.4] - 2024-08-16
+
+### Added
+
+- Added `ToExecuteCommandType[T]()` and `ToRecordEventType[T]()` expectations.
+
+### Deprecated
+
+- Marked `ToExecuteCommandOfType()` and `ToRecordEventOfType()` as deprecated.
+  These functions will be removed in a future release; use the new generic
+  versions instead.
+
 ## [0.15.3] - 2024-08-16
 
 ### Changed
@@ -402,6 +414,7 @@ guide][0.11.0 migration guide] for detailed instructions.
 [0.15.1]: https://github.com/dogmatiq/testkit/releases/tag/v0.15.1
 [0.15.2]: https://github.com/dogmatiq/testkit/releases/tag/v0.15.2
 [0.15.3]: https://github.com/dogmatiq/testkit/releases/tag/v0.15.3
+[0.15.4]: https://github.com/dogmatiq/testkit/releases/tag/v0.15.4
 
 <!-- contributors -->
 

expectation.message.event_test.go

@@ -12,7 +12,7 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = g.Describe("func ToExecuteCommandOfType()", func() {
+var _ = g.Describe("func ToExecuteCommandType()", func() {
 	var (
 		testingT *testingmock.T
 		app      dogma.Application

expectation.messagetype.command_test.go

@@ -12,7 +12,7 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = g.Describe("func ToExecuteCommandOfType()", func() {
+var _ = g.Describe("func ToExecuteCommandType()", func() {
 	var (
 		testingT *testingmock.T
 		app      dogma.Application
@@ -97,7 +97,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"command type executed as expected",
 			RecordEvent(MessageE1),
-			ToExecuteCommandOfType(MessageC{}),
+			ToExecuteCommandType[MessageC](),
 			expectPass,
 			expectReport(
 				`✓ execute any 'fixtures.MessageC' command`,
@@ -106,7 +106,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no matching command types executed",
 			RecordEvent(MessageE1),
-			ToExecuteCommandOfType(MessageX{}),
+			ToExecuteCommandType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ execute any 'fixtures.MessageX' command`,
@@ -121,7 +121,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no messages produced at all",
 			RecordEvent(MessageN1),
-			ToExecuteCommandOfType(MessageC{}),
+			ToExecuteCommandType[MessageC](),
 			expectFail,
 			expectReport(
 				`✗ execute any 'fixtures.MessageC' command`,
@@ -136,7 +136,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no commands produced at all",
 			ExecuteCommand(MessageR1),
-			ToExecuteCommandOfType(MessageC{}),
+			ToExecuteCommandType[MessageC](),
 			expectFail,
 			expectReport(
 				`✗ execute any 'fixtures.MessageC' command`,
@@ -151,7 +151,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no matching command type executed and all relevant handler types disabled",
 			RecordEvent(MessageN1),
-			ToExecuteCommandOfType(MessageC{}),
+			ToExecuteCommandType[MessageC](),
 			expectFail,
 			expectReport(
 				`✗ execute any 'fixtures.MessageC' command`,
@@ -169,7 +169,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"command of a similar type executed",
 			RecordEvent(MessageE1),
-			ToExecuteCommandOfType(&MessageC{}), // note: message type is pointer
+			ToExecuteCommandType[*MessageC](), // note: message type is pointer
 			expectFail,
 			expectReport(
 				`✗ execute any '*fixtures.MessageC' command`,
@@ -188,8 +188,8 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 			"does not include an explanation when negated and a sibling expectation passes",
 			RecordEvent(MessageE1),
 			NoneOf(
-				ToExecuteCommandOfType(MessageC{}),
-				ToExecuteCommandOfType(MessageX{}),
+				ToExecuteCommandType[MessageC](),
+				ToExecuteCommandType[MessageX](),
 			),
 			expectFail,
 			expectReport(
@@ -204,7 +204,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		test := Begin(testingT, app)
 		test.Expect(
 			noop,
-			ToExecuteCommandOfType(MessageU{}),
+			ToExecuteCommandType[MessageU](),
 		)
 
 		Expect(testingT.Failed()).To(BeTrue())
@@ -217,7 +217,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		test := Begin(testingT, app)
 		test.Expect(
 			noop,
-			ToExecuteCommandOfType(MessageE{}),
+			ToExecuteCommandType[MessageE](),
 		)
 
 		Expect(testingT.Failed()).To(BeTrue())
@@ -230,18 +230,12 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		test := Begin(testingT, app)
 		test.Expect(
 			noop,
-			ToExecuteCommandOfType(MessageR{}),
+			ToExecuteCommandType[MessageR](),
 		)
 
 		Expect(testingT.Failed()).To(BeTrue())
 		Expect(testingT.Logs).To(ContainElement(
 			"no handlers execute commands of type fixtures.MessageR, it is only ever consumed",
 		))
 	})
-
-	g.It("panics if the message is nil", func() {
-		Expect(func() {
-			ToExecuteCommandOfType(nil)
-		}).To(PanicWith("ToExecuteCommandOfType(<nil>): message must not be nil"))
-	})
 })

expectation.messagetype.commandcall_test.go

@@ -12,7 +12,7 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = g.Describe("func ToExecuteCommandOfType() (when used with the Call() action)", func() {
+var _ = g.Describe("func ToExecuteCommandType() (when used with the Call() action)", func() {
 	var (
 		testingT *testingmock.T
 		app      dogma.Application
@@ -105,7 +105,7 @@ var _ = g.Describe("func ToExecuteCommandOfType() (when used with the Call() act
 		g.Entry(
 			"command type executed as expected",
 			executeCommandViaExecutor(MessageR1),
-			ToExecuteCommandOfType(MessageR{}),
+			ToExecuteCommandType[MessageR](),
 			expectPass,
 			expectReport(
 				`✓ execute any 'fixtures.MessageR' command`,
@@ -114,7 +114,7 @@ var _ = g.Describe("func ToExecuteCommandOfType() (when used with the Call() act
 		g.Entry(
 			"no messages produced at all",
 			Call(func() {}),
-			ToExecuteCommandOfType(MessageC{}),
+			ToExecuteCommandType[MessageC](),
 			expectFail,
 			expectReport(
 				`✗ execute any 'fixtures.MessageC' command`,
@@ -129,7 +129,7 @@ var _ = g.Describe("func ToExecuteCommandOfType() (when used with the Call() act
 		g.Entry(
 			"no matching command type executed and all relevant handler types disabled",
 			executeCommandViaExecutor(MessageR1),
-			ToExecuteCommandOfType(MessageC{}),
+			ToExecuteCommandType[MessageC](),
 			expectFail,
 			expectReport(
 				`✗ execute any 'fixtures.MessageC' command`,
@@ -148,7 +148,7 @@ var _ = g.Describe("func ToExecuteCommandOfType() (when used with the Call() act
 		g.Entry(
 			"command of a similar type executed",
 			executeCommandViaExecutor(MessageR1),
-			ToExecuteCommandOfType(&MessageR{}), // note: message type is pointer
+			ToExecuteCommandType[*MessageR](), // note: message type is pointer
 			expectFail,
 			expectReport(
 				`✗ execute any '*fixtures.MessageR' command`,

expectation.messagetype.event_test.go

@@ -12,7 +12,7 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = g.Describe("func ToExecuteCommandOfType()", func() {
+var _ = g.Describe("func ToRecordEventType()", func() {
 	var (
 		testingT *testingmock.T
 		app      dogma.Application
@@ -100,7 +100,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"event type recorded as expected",
 			ExecuteCommand(MessageR1),
-			ToRecordEventOfType(MessageE{}),
+			ToRecordEventType[MessageE](),
 			expectPass,
 			expectReport(
 				`✓ record any 'fixtures.MessageE' event`,
@@ -109,7 +109,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no matching event type recorded",
 			ExecuteCommand(MessageR1),
-			ToRecordEventOfType(MessageX{}),
+			ToRecordEventType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageX' event`,
@@ -125,7 +125,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no matching event type recorded and all relevant handler types disabled",
 			ExecuteCommand(MessageR1),
-			ToRecordEventOfType(MessageX{}),
+			ToRecordEventType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageX' event`,
@@ -145,7 +145,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no matching event type recorded and no relevant handler types engaged",
 			ExecuteCommand(MessageR1),
-			ToRecordEventOfType(MessageX{}),
+			ToRecordEventType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageX' event`,
@@ -165,7 +165,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no messages produced at all",
 			ExecuteCommand(MessageN1),
-			ToRecordEventOfType(MessageX{}),
+			ToRecordEventType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageX' event`,
@@ -181,7 +181,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"no events recorded at all",
 			RecordEvent(MessageE1),
-			ToRecordEventOfType(MessageX{}),
+			ToRecordEventType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageX' event`,
@@ -197,7 +197,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		g.Entry(
 			"event of a similar type recorded",
 			ExecuteCommand(MessageR1),
-			ToRecordEventOfType(&MessageE{}), // note: message type is pointer
+			ToRecordEventType[*MessageE](), // note: message type is pointer
 			expectFail,
 			expectReport(
 				`✗ record any '*fixtures.MessageE' event`,
@@ -216,8 +216,8 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 			"does not include an explanation when negated and a sibling expectation passes",
 			ExecuteCommand(MessageR1),
 			NoneOf(
-				ToRecordEventOfType(MessageE{}),
-				ToRecordEventOfType(MessageX{}),
+				ToRecordEventType[MessageE](),
+				ToRecordEventType[MessageX](),
 			),
 			expectFail,
 			expectReport(
@@ -232,7 +232,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		test := Begin(testingT, app)
 		test.Expect(
 			noop,
-			ToRecordEventOfType(MessageU{}),
+			ToRecordEventType[MessageU](),
 		)
 
 		Expect(testingT.Failed()).To(BeTrue())
@@ -245,7 +245,7 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		test := Begin(testingT, app)
 		test.Expect(
 			noop,
-			ToRecordEventOfType(MessageR{}),
+			ToRecordEventType[MessageR](),
 		)
 
 		Expect(testingT.Failed()).To(BeTrue())
@@ -258,18 +258,12 @@ var _ = g.Describe("func ToExecuteCommandOfType()", func() {
 		test := Begin(testingT, app)
 		test.Expect(
 			noop,
-			ToRecordEventOfType(MessageO{}),
+			ToRecordEventType[MessageO](),
 		)
 
 		Expect(testingT.Failed()).To(BeTrue())
 		Expect(testingT.Logs).To(ContainElement(
 			"no handlers record events of type fixtures.MessageO, it is only ever consumed",
 		))
 	})
-
-	g.It("panics if the message is nil", func() {
-		Expect(func() {
-			ToRecordEventOfType(nil)
-		}).To(PanicWith("ToRecordEventOfType(<nil>): message must not be nil"))
-	})
 })

expectation.messagetype.eventcall_test.go

@@ -11,7 +11,7 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = g.Describe("func ToRecordEventOfType() (when used with the Call() action)", func() {
+var _ = g.Describe("func ToRecordEventType() (when used with the Call() action)", func() {
 	var (
 		testingT *testingmock.T
 		app      dogma.Application
@@ -107,7 +107,7 @@ var _ = g.Describe("func ToRecordEventOfType() (when used with the Call() action
 		g.Entry(
 			"no matching event types recorded",
 			executeCommandViaExecutor(MessageR1),
-			ToRecordEventOfType(MessageX{}),
+			ToRecordEventType[MessageX](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageX' event`,
@@ -124,7 +124,7 @@ var _ = g.Describe("func ToRecordEventOfType() (when used with the Call() action
 		g.Entry(
 			"no messages produced at all",
 			Call(func() {}),
-			ToRecordEventOfType(MessageE{}),
+			ToRecordEventType[MessageE](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageE' event`,
@@ -139,7 +139,7 @@ var _ = g.Describe("func ToRecordEventOfType() (when used with the Call() action
 		g.Entry(
 			"no events produced at all",
 			executeCommandViaExecutor(MessageN1),
-			ToRecordEventOfType(MessageE{}),
+			ToRecordEventType[MessageE](),
 			expectFail,
 			expectReport(
 				`✗ record any 'fixtures.MessageE' event`,

expectation.messagetype.go

@@ -10,8 +10,19 @@ import (
 	"github.com/dogmatiq/testkit/internal/typecmp"
 )
 
+// ToExecuteCommandType returns an expectation that passes if a command of type
+// T is executed.
+func ToExecuteCommandType[T dogma.Command]() Expectation {
+	return &messageTypeExpectation{
+		expectedType: message.TypeFor[T](),
+		expectedRole: message.CommandRole,
+	}
+}
+
 // ToExecuteCommandOfType returns an expectation that passes if a command of the
 // same type as m is executed.
+//
+// Deprecated: Use [ToExecuteCommandType] instead.
 func ToExecuteCommandOfType(m dogma.Command) Expectation {
 	if m == nil {
 		panic("ToExecuteCommandOfType(<nil>): message must not be nil")
@@ -23,8 +34,19 @@ func ToExecuteCommandOfType(m dogma.Command) Expectation {
 	}
 }
 
+// ToRecordEventType returns an expectation that passes if an event of type T is
+// recorded.
+func ToRecordEventType[T dogma.Event]() Expectation {
+	return &messageTypeExpectation{
+		expectedType: message.TypeFor[T](),
+		expectedRole: message.EventRole,
+	}
+}
+
 // ToRecordEventOfType returns an expectation that passes if an event of the
 // same type as m is recorded.
+//
+// Deprecated: Use [ToRecordEventType] instead.
 func ToRecordEventOfType(m dogma.Command) Expectation {
 	if m == nil {
 		panic("ToRecordEventOfType(<nil>): message must not be nil")