Add chasm test engine for unit tests by awln-temporal · Pull Request #9882 · temporalio/temporal

awln-temporal · 2026-04-09T00:11:13Z

What changed?

Add chasm test engine for unit tests

Why?

Currently, CHASM library unit tests need to create mock chasm engine behavior, manually wire expected framework calls to the CHASM tree/node to CloseTransaction/generate any state needed for validation. Instead, unit tests should behave similar to how they are implemented, and delegate any chasm tree creation and reading component state to chasm engine methods.

This change introduces an implementation of the test CHASM engine that mocks the NodeBackend, but implements all methods that mutate or create Component state.

How did you test it?

bergundy · 2026-04-09T21:17:13Z

+)
+
+type (
+	Option[T chasm.RootComponent] func(*Engine[T])


nit: Call this EngineOption

bergundy · 2026-04-09T21:17:27Z

+type (
+	Option[T chasm.RootComponent] func(*Engine[T])
+
+	Engine[T chasm.RootComponent] struct {


Why does the engine need to be typed?

doesn't, it was only added for the helper func to get the Root component, but definitely not needed, removing this along with other accessor methods as mentioned below

bergundy · 2026-04-09T21:17:59Z

+	return e
+}
+
+func WithRoot[T chasm.RootComponent](


Not needed, StartExecution should be used here instead to create a root.

bergundy · 2026-04-09T21:18:21Z

+	}
+}
+
+func WithExecutionKey[T chasm.RootComponent](key chasm.ExecutionKey) Option[T] {


That will also be part of StartExecution.

bergundy · 2026-04-09T21:18:42Z

+	}
+}
+
+func (e *Engine[T]) Root() T {


We can use ReadComponent to extract whatever we need from the engine.

bergundy · 2026-04-10T21:03:43Z

+		registry   *chasm.Registry
+		logger     log.Logger
+		metrics    metrics.Handler
+		executions map[executionLookupKey]*execution


We can start with this but you'll want to expand it to handle multiple runs and have a way to locate the current run for completeness.

This limits what can be tested today and we'll have to rely on functional test coverage for ID policy enforcement for example.

i'm wondering if this these cases should be in scope of functional tests. In this case, it's testing for the real behavior of handling conflicting IDs, while the TestEngine and real chasm_engine.go have technically different implementations.

bergundy · 2026-04-10T21:05:05Z

+func (e *Engine) EngineContext() context.Context {
+	return chasm.NewEngineContext(context.Background(), e)
+}


Don't add this, tests have their own context that they'll want to install the engine on.

bergundy · 2026-04-10T21:06:30Z

+	return chasm.StartExecutionResult{
+		ExecutionKey: execution.key,
+		ExecutionRef: serializedRef,
+		Created:      true,


This should be false when using UseExisting policy.

hm right now the implementation just assumes there can be one execution at a time, ig same discussion as below, do we want to handle conflict policies in this engine, or should we just go with a simpler solution? When would unit tests want to test out conflicting execution behavior?

I would implement a more complete solution. You basically are implementing a full in-memory CHASM engine. It should have the same semantics as the history chasm engine.

bergundy · 2026-04-10T21:07:19Z

+	return serviceerror.NewUnimplemented("chasmtest.Engine.DeleteExecution")
+}
+
+func (e *Engine) NotifyExecution(chasm.ExecutionKey) {}


Is this intentionally not implemented?

no, I wanted to review the important methods first to make sure we're aligned on the contract, will add DeleteExecution impl.

for NotifyExecution, I don't see a case where we need to signal PollingComponent especially in a unit test. I'm also not sure we need PollComponent if callers can just validate state they need? Could be missing something for PollComponent though.

Put a comment in code please.

bergundy · 2026-04-10T21:08:38Z

+		HandleNextTransitionCount: func() int64 { return 2 },
+		HandleGetCurrentVersion:   func() int64 { return 1 },
+		HandleGetWorkflowKey: func() definition.WorkflowKey {
+			return definition.NewWorkflowKey(key.NamespaceID, key.BusinessID, key.RunID)
+		},
+		HandleIsWorkflow: func() bool { return false },
+		HandleCurrentVersionedTransition: func() *persistencespb.VersionedTransition {
+			return &persistencespb.VersionedTransition{
+				NamespaceFailoverVersion: 1,
+				TransitionCount:          1,
+			}
+		},


You're going to want to increment the current version on every transaction (UpdateComponent, StartExecution, UpdateWithStartExecution).

hm ok, yeah I left this part out since the backend is not even accessible right now. Should we discuss what verifications would be useful to check on the MockNodeBackend?

If we don't really care about verifications on transition counts and rather that be in scope of functional tests, should we just leave the MockNodeBackend impl as is?

The engine should be as close to the real engine as possible. Ideally it would have the exact same behavior.

bergundy · 2026-04-10T21:10:21Z

+		key.NamespaceID = "test-namespace-id"
+	}
+	if key.BusinessID == "" {
+		key.BusinessID = "test-workflow-id"


Suggested change

key.BusinessID = "test-workflow-id"

key.BusinessID = "test-business-id"

bergundy · 2026-04-10T21:11:12Z

+	}
+}
+
+func normalizeExecutionKey(key chasm.ExecutionKey) chasm.ExecutionKey {


I would just ask test authors to create a valid execution key instead of implicitly adding defaults.

bergundy · 2026-04-10T21:13:20Z

+	return chasm.NewEngineContext(context.Background(), e)
+}
+
+func (e *Engine) Ref(component chasm.Component) chasm.ComponentRef {


Not needed IMHO. Test authors should already have refs to components they create using start execution.

how would they get the ref to the component within StartExecution or after? Subcomponents only get set in valueToNode map after syncSubComponents when SetRootComponent is called, so we'd either need to return this map as a result of StartExecution or something similar.

I would expect chasm.Ref(c) to work.

bergundy · 2026-04-10T21:14:46Z

+func readCallbackFromEngine(
+	t *testing.T,
+	testEngine *chasmtest.Engine,
+	callback *Callback,
+) *Callback {


What is this supposed to do? If I already have a callback component, isn't this just returning the same callback? Seems confusing to me.

yeah not sure what I was thinking, removed

bergundy · 2026-04-10T21:16:37Z


 			// Verify the outcome and tasks
-			tc.assertOutcome(t, callback, err)
+			tc.assertOutcome(t, readCallbackFromEngine(t, testEngine, callback), err)


I would just wrap this call in chasm.ReadComponent

bergundy

I would expect the test framework to be as comprehensive as our SDKs' test frameworks. Library authors should be able to test their code and get the same behavior as if they were using the "real thing".

I can approve because this is far better than what we had previously but it still feels incomplete to me and I would rather spend more time on this before declaring this task done.

bergundy · 2026-04-15T00:32:57Z

These helpers are a bit redundant to me but no strong objection to keep them.

bergundy · 2026-04-15T00:35:08Z

+	return chasm.NewEngineContext(context.Background(), e)
+}
+
+func (e *Engine) Ref(component chasm.Component) chasm.ComponentRef {


I would expect chasm.Ref(c) to work.

bergundy · 2026-04-15T00:36:05Z

+	return chasm.StartExecutionResult{
+		ExecutionKey: execution.key,
+		ExecutionRef: serializedRef,
+		Created:      true,


I would implement a more complete solution. You basically are implementing a full in-memory CHASM engine. It should have the same semantics as the history chasm engine.

bergundy · 2026-04-15T00:36:41Z

+	return serviceerror.NewUnimplemented("chasmtest.Engine.DeleteExecution")
+}
+
+func (e *Engine) NotifyExecution(chasm.ExecutionKey) {}


Put a comment in code please.

bergundy · 2026-04-15T00:37:10Z

+		HandleNextTransitionCount: func() int64 { return 2 },
+		HandleGetCurrentVersion:   func() int64 { return 1 },
+		HandleGetWorkflowKey: func() definition.WorkflowKey {
+			return definition.NewWorkflowKey(key.NamespaceID, key.BusinessID, key.RunID)
+		},
+		HandleIsWorkflow: func() bool { return false },
+		HandleCurrentVersionedTransition: func() *persistencespb.VersionedTransition {
+			return &persistencespb.VersionedTransition{
+				NamespaceFailoverVersion: 1,
+				TransitionCount:          1,
+			}
+		},


The engine should be as close to the real engine as possible. Ideally it would have the exact same behavior.

Use ctx.Ref(component) + DeserializeComponentRef inside a ReadComponent callback instead, which is the idiomatic approach available on the public chasm.Context interface. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add chasm test engine for engine-backed tests

ea21b9b

awln-temporal requested review from a team as code owners April 9, 2026 00:11

Fix test engine root component constraint

171cdf0

awln-temporal force-pushed the awln/chasm-test-engine-base branch from 19cf028 to 171cdf0 Compare April 9, 2026 16:41

bergundy reviewed Apr 9, 2026

View reviewed changes

awln-temporal changed the title ~~Add chasm test engine for engine-backed tests~~ Add chasm test engine for unit tests Apr 10, 2026

awln-temporal added 2 commits April 10, 2026 11:13

Remove unnecessary helper to create Root

267e896

Merge branch 'main' into awln/chasm-test-engine-base

9c6bf52

bergundy reviewed Apr 10, 2026

View reviewed changes

awln-temporal added 2 commits April 10, 2026 17:42

Address comments

54ecfd9

Address comments

ab0e979

awln-temporal force-pushed the awln/chasm-test-engine-base branch from 8a834bc to f502701 Compare April 13, 2026 14:14

fix formatting in tasks_test.go

2e57fc9

awln-temporal force-pushed the awln/chasm-test-engine-base branch from f502701 to 2e57fc9 Compare April 14, 2026 15:07

awln-temporal requested a review from bergundy April 14, 2026 16:27

Merge branch 'main' into awln/chasm-test-engine-base

1693f89

bergundy reviewed Apr 15, 2026

View reviewed changes

awln-temporal and others added 2 commits April 15, 2026 12:24

Remove Ref() helper from chasmtest.Engine

66b376f

Use ctx.Ref(component) + DeserializeComponentRef inside a ReadComponent callback instead, which is the idiomatic approach available on the public chasm.Context interface. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add conflict policy handling and fuller impl of MockNodeBackend

e7b13aa

awln-temporal force-pushed the awln/chasm-test-engine-base branch from db2c277 to e7b13aa Compare April 15, 2026 17:49

	key.BusinessID = "test-workflow-id"
	key.BusinessID = "test-business-id"

Conversation

awln-temporal commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed?

Why?

How did you test it?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bergundy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

awln-temporal commented Apr 9, 2026 •

edited

Loading