Enhancement: entity unit-testing support in azure-functions-durable v2.x

[andystaples]

Summary

azure-functions-durable v2.x supports host-free unit testing for orchestrators and client (trigger) functions, matching the patterns in Unit testing Durable Functions and Durable Task SDKs. There is no equivalent story for entities. This issue tracks adding first-class entity unit-testing support, including the v2.x-new class-based DurableEntity.

Current state (what works today)

• Orchestrators — azure.durable_functions.testing.orchestrator_generator_wrapper drives an orchestrator generator with mocked task results, and orchestration_trigger-decorated functions expose .orchestrator_function via .build().get_user_function().
• Client functions — durable_client_input-decorated functions expose .client_function, so the raw trigger function can be invoked directly with a mocked client.

Both of the above are being added in the current v2.0.0b1 work as they are required for v1.x compatibility.

The gap

There is no documented or supported way to unit test an entity without a running Functions host or a Durable Task backend. Specifically:

1. No test harness to drive an entity operation. Given an operation name, an input, and an initial state, there is no simple, supported way to invoke the entity and assert on:
   • the operation's return value,
   • the resulting state after the operation,
   • any signals / orchestrations the operation scheduled.
2. entity_trigger handle exposes .entity_function, mirroring .orchestrator_function, but there is no wrapper/harness equivalent to orchestrator_generator_wrapper that simulates the entity batch-execution + state-shim behavior for a single operation in-process.

v2.x-specific consideration: class-based entities

DurableEntity (class-based entities) are new in v2.x and change the authoring shape (operations are methods; state is accessed via the entity context / state shim rather than the v1 function-style context.get_state()/set_state()). Any entity testing story needs to cover both:

• v1-style function entities (def entity(context) / def entity(ctx, input)), and
• v2.x class-based DurableEntity subclasses.

Design questions to resolve:

• How does a customer instantiate/drive a DurableEntity subclass in a unit test — do they construct it directly and call the operation method, and if so how is the entity context (state get/set, signal_entity, start_new_orchestration, etc.) mocked or provided?
• Should we ship a small azure.durable_functions.testing helper (e.g. an entity test harness that wraps the state shim and returns (result, new_state, actions)), analogous to orchestrator_generator_wrapper, so both entity styles are testable with a consistent API?
• What is the minimal, documented pattern we want customers to use, and should it be added to the Learn article's Python / Durable Functions tab (which currently has no entity testing example)?

Proposed direction

• Provide an entity unit-testing helper in azure.durable_functions.testing that executes a single entity operation in-process (reusing the existing entity state shim) and surfaces the return value, the mutated state, and scheduled actions (signals/orchestrations) for assertions.
• Ensure it works for both function-style and class-based (DurableEntity) entities.
• Add unit tests covering both styles and, once the API settles, propose an entity example for the docs.

Notes

Deferred out of the large v2.0.0b1 PR to keep that change scoped to the orchestrator/client compatibility work. This is a net-new v2.x capability rather than a v1 compatibility requirement.