Initial PR for Durable Functions unit testing docs

Author: andystaples

articles/azure-functions/.openpublishing.redirection.azure-functions.json

@@ -190,6 +190,11 @@
             "redirect_url": "/azure/azure-functions/durable/durable-functions-unit-testing",
             "redirect_document_id": false
         },
+        {
+            "source_path_from_root": "/articles/azure-functions/durable-functions-unit-testing-python.md",
+            "redirect_url": "/azure/azure-functions/durable/durable-functions-unit-testing-python",
+            "redirect_document_id": false
+        },
         {
             "source_path_from_root": "/articles/azure-functions/durable-functions-versioning.md",
             "redirect_url": "/azure/azure-functions/durable/durable-functions-versioning",

articles/azure-functions/durable/TOC.yml

@@ -155,8 +155,10 @@
       href: durable-functions-create-portal.md
     - name: Manage connections
       href: ../manage-connections.md?toc=/azure/azure-functions/durable/toc.json
-    - name: Unit testing
+    - name: Unit testing (C#)
       href: durable-functions-unit-testing.md
+    - name: Unit testing (Python)
+      href: durable-functions-unit-testing-python.md
     - name: Create as WebJobs
       href: durable-functions-webjobs-sdk.md
     - name: Durable entities in .NET

articles/azure-functions/durable/durable-functions-unit-testing-python.md

@@ -0,0 +1,170 @@
+# Unit Testing Durable Functions in Python
+
+## Introduction
+Unit testing Durable Functions is essential to ensure the correctness of individual components without relying on an actual Azure environment. By writing effective unit tests, developers can catch errors early, improve code maintainability, and increase confidence in their implementations.
+
+This guide provides an overview of unit testing Durable Functions in Python, covering the key components: starter functions, orchestrators, activity functions, and entity functions. It includes best practices and sample test cases to help you write robust and maintainable tests for your Durable Functions.
+
+## Prerequisites
+The examples in this article require knowledge of the following concepts and frameworks:
+
+* Unit testing
+* Durable Functions
+* Python [unittest](https://docs.python.org/3/library/unittest.html) 
+* [unittest.mock](https://docs.python.org/3/library/unittest.mock.html)
+
+## Setting Up the Test Environment
+To test Durable Functions, it's crucial to set up a proper test environment. This includes creating a test directory and installing unittest into your Python environment. For more info, see the Azure Functions Python unit testing overview [here](https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-python?tabs=get-started%2Casgi%2Capplication-level&pivots=python-mode-decorators#unit-testing).
+
+## Testing Durable Clients  
+Durable Client functions initiate orchestrations and external events. To test a client function:
+
+- Mock the `DurableOrchestrationClient` to simulate orchestration execution and status management.  
+- Replace `DurableOrchestrationClient` methods such as `start_new`, `get_status`, or `raise_event` with mock functions that return expected values.  
+- Invoke the client function directly with a mocked client as well as other necessary inputs such as a `req` (HTTP request object) for HTTP trigger client functions.  
+- Use assertions and `unittest.mock` tools to verify expected orchestration start behavior, parameters, and HTTP responses.
+
+**Sample Code:**
+```python
+import asyncio
+import unittest
+import azure.functions as func
+from unittest.mock import AsyncMock, Mock, patch
+
+from function_app import start_orchestrator
+
+class TestFunction(unittest.TestCase):
+  @patch('azure.durable_functions.DurableOrchestrationClient')
+  def test_chaining_orchestrator(self, client):
+    # Get the original method definition as seen in the function_app.py file
+    # func_call = chaining_orchestrator.build().get_user_function_unmodified()
+    func_call = start_orchestrator.build().get_user_function().client_function
+
+    req = func.HttpRequest(method='GET',
+                           body=None,
+                           url='/api/my_second_function',
+                           params={"orchestrator_name": "startOrchestrator"})
+
+    client.start_new = AsyncMock(return_value="instance_id")
+    client.create_check_status_response = Mock(return_value="check_status_response")
+
+    # Create a generator using the method and mocked context
+    result = asyncio.run(func_call(req, client))
+
+    client.start_new.assert_called_once_with("startOrchestrator")
+    client.create_check_status_response.assert_called_once_with(req, "instance_id")
+    self.assertEqual(result, "check_status_response")
+```
+
+## Testing Durable Orchestrators
+Durable Orchestrators manage the execution of multiple activity functions. To test an orchestrator:
+
+- Mock the `DurableOrchestrationContext` to control function execution.
+- Replace `DurableOrchestrationContext` methods needed for orchestrator execution like `call_activity` or `create_timer` with mock functions. These functions should have pre-determined behavior and should typically return Task objects with a `result` property. 
+- Call the orchestrator recursively, passing the result of the Task generated by the previous yield statement to the next. 
+- Use the results returned from the orchestrator, as well as `unittest.mock` methods to verify the orchestrator result. 
+
+**Sample Code:**
+```python
+import unittest
+from unittest.mock import Mock, patch, call
+from datetime import timedelta
+
+class TestFunction(unittest.TestCase):
+  @patch('azure.durable_functions.DurableOrchestrationContext')
+  def test_chaining_orchestrator(self, context):
+    # Get the original method definition as seen in the function_app.py file
+    func_call = chaining_orchestrator.build().get_user_function().orchestrator_function
+
+    context.call_activity = Mock(side_effect=mock_activity)
+    context.create_timer = Mock(return_value=MockTask())
+    # Create a generator using the method and mocked context
+    user_orchestrator = func_call(context)
+
+    # Use a method defined above to get the values from the generator. Quick unwrap for easy access
+    values = [val for val in orchestrator_generator_wrapper(user_orchestrator)]
+
+    expected_activity_calls = [call('say_hello', 'Tokyo'),
+                               call('say_hello', 'Seattle'),
+                               call('say_hello', 'London')]
+    
+    self.assertEqual(context.call_activity.call_count, 3)
+    self.assertEqual(context.call_activity.call_args_list, expected_activity_calls)
+    context.create_timer.assert_called_once_with(context.current_utc_datetime + timedelta(seconds=5))
+    self.assertEqual(values[4], ["Hello Tokyo!", "Hello Seattle!", "Hello London!"])
+```
+
+## Testing Durable Entities  
+Durable Entity functions manage stateful objects with operations. To test an entity function:
+
+- Mock the `DurableEntityContext` to simulate the entity's internal state and operation inputs.  
+- Replace `DurableEntityContext` methods like `get_state`, `set_state`, and `operation_name` with mocks that return controlled values.  
+- Invoke the entity function directly with the mocked context.  
+- Use assertions to verify state changes and returned values, along with `unittest.mock` utilities.
+
+**Sample Code:**
+```python
+import unittest
+from unittest.mock import Mock, patch
+
+from function_app import Counter
+
+class TestEntityFunction(unittest.TestCase):
+  @patch('azure.durable_functions.DurableEntityContext')
+  def test_entity_add_operation(self, context_mock):
+    # Get the original method definition as seen in function_app.py
+    func_call = Counter.build().get_user_function().entity_function
+    
+    # Setup mock context behavior
+    state = 0
+    result = None
+
+    def set_state(new_state):
+        nonlocal state
+        state = new_state
+
+    def set_result(new_result):
+        nonlocal result
+        result = new_result
+
+    context_mock.get_state = Mock(return_value=state)
+    context_mock.set_state = Mock(side_effect=set_state)
+
+    context_mock.operation_name = "add"
+    context_mock.get_input = Mock(return_value=5)
+
+    context_mock.set_result = Mock(side_effect=lambda x: set_result)
+
+    # Call the entity function with the mocked context
+    func_call(context_mock)
+
+    # Verify the state was updated correctly
+    context_mock.set_state.assert_called_once_with(5)
+    self.assertEqual(state, 5)
+    self.assertEqual(result, None)
+```
+
+## Testing Activity Functions
+Activity functions require no Durable-specific modifications to be tested. The guidance found in the Azure Functions Python unit testing overview [here](https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-python?tabs=get-started%2Casgi%2Capplication-level&pivots=python-mode-decorators#unit-testing) is sufficient for testing these functions. 
+
+## Summary
+Testing Durable Functions effectively requires simulating their unique runtime behaviors while keeping tests isolated and deterministic. Here are some best practices to keep in mind:
+
+- **Mock the right context objects**: Use `DurableOrchestrationContext`, `DurableOrchestrationClient`, and `DurableEntityContext` mocks to simulate platform behavior.
+- **Replace key methods**: Mock critical methods like `call_activity`, `start_new`, `get_state`, etc., to return controlled values for validation.
+- **Isolate logic**: Keep orchestration, client, and entity logic testable independently to ensure clear separation of concerns.
+- **Validate behavior, not implementation**: Focus on validating the outcome and side effects, rather than internal steps.
+- **Use generator wrappers**: For orchestrators, properly walk through the generator steps to simulate orchestration flow.
+- **Test failure paths**: Include tests for error conditions, timeouts, and unexpected input to ensure robust function behavior.
+
+By applying these practices, you can build a comprehensive test suite for your Durable Functions that ensures reliability and simplifies long-term maintenance.
+
+---
+
+## Related content
+
+For deeper insights into Durable Functions in Python, explore these resources:
+
+- [Durable Functions GitHub Samples](https://github.com/Azure/azure-functions-durable-python)
+- [Azure Functions Python Developer Guide](https://learn.microsoft.com/azure/azure-functions/functions-reference-python)
+- [Azure Durable Functions Documentation](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview)

articles/azure-functions/durable/quickstart-python-vscode.md

@@ -379,6 +379,10 @@ After you verify that the function runs correctly on your local computer, it's t
 
 [!INCLUDE [functions-publish-project-vscode](../../../includes/functions-publish-project-vscode.md)]
 
+## Unit testing
+
+For more information on unit testing functions in Python, see our [Python unit testing guide](durable-functions-unit-testing-python.md)
+
 ## Test your function in Azure
 
 ::: zone pivot="python-mode-configuration"