Acrolynx improvements and PR suggestions

Author: andystaples

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

@@ -9,7 +9,7 @@ ms.author: azfuncdf
 
 # Unit Testing Durable Functions in Python
 
-Unit testing is an important part of modern software development practices. Unit tests verify business logic behavior and protect from introducing unnoticed breaking changes in the future. Durable Functions can easily grow in complexity so introducing unit tests will help to avoid breaking changes. The following sections explain how to unit test the three function types - Orchestration client, orchestrator, and entity functions.
+Unit testing is an important part of modern software development practices. Unit tests verify business logic behavior and protect from introducing unnoticed breaking changes in the future. Durable Functions can easily grow in complexity so introducing unit tests helps avoid breaking changes. The following sections explain how to unit test the three function types - Orchestration client, orchestrator, and entity functions.
 
 > [!NOTE]
 > This guide applies only to Durable Functions apps written in the [Python v2 programming model](../functions-reference-python.md). 
@@ -25,15 +25,15 @@ The examples in this article require knowledge of the following concepts and fra
 
 ## 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](../functions-reference-python.md#unit-testing).
+To test Durable Functions, it's crucial to set up a proper test environment. This includes creating a test directory and installing Python's `unittest` module into your Python environment. For more info, see the [Azure Functions Python unit testing overview](../functions-reference-python.md#unit-testing).
 
 ## Unit testing trigger functions
 
 Trigger functions, often referred to as _client_ functions, initiate orchestrations and external events. To test these functions:
 
 - Mock the `DurableOrchestrationClient` to simulate orchestration execution and status management.  
 - Assign `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.  
+- Invoke the client function directly with a mocked client and 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.
 
 ```python
@@ -71,9 +71,9 @@ class TestFunction(unittest.TestCase):
 Orchestrator functions 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. 
+- Replace `DurableOrchestrationContext` methods needed for orchestrator execution like `call_activity` or `create_timer` with mock functions. These functions will typically return objects of type TaskBase with a `result` property.
+- Call the orchestrator recursively, passing the result of the Task generated by the previous yield statement to the next.
+- Verify the orchestrator result using the results returned from the orchestrator and `unittest.mock`.
 
 ```python
 import unittest
@@ -90,6 +90,8 @@ class TestFunction(unittest.TestCase):
     # Get the original method definition as seen in the function_app.py file
     func_call = my_orchestrator.build().get_user_function().orchestrator_function
 
+    # The mock_activity method is defined above with behavior specific to your app.
+    # It returns a TaskBase object with the result expected from the activity call.
     context.call_activity = Mock(side_effect=mock_activity)
 
     # Create a generator using the method and mocked context

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

@@ -7,7 +7,7 @@ ms.date: 11/03/2019
 
 # Durable Functions unit testing (C#)
 
-Unit testing is an important part of modern software development practices. Unit tests verify business logic behavior and protect from introducing unnoticed breaking changes in the future. Durable Functions can easily grow in complexity so introducing unit tests will help to avoid breaking changes. The following sections explain how to unit test the three function types - Orchestration client, orchestrator, and activity functions.
+Unit testing is an important part of modern software development practices. Unit tests verify business logic behavior and protect from introducing unnoticed breaking changes in the future. Durable Functions can easily grow in complexity so introducing unit tests helps avoid breaking changes. The following sections explain how to unit test the three function types - Orchestration client, orchestrator, and activity functions.
 
 > [!NOTE]
 > This article provides guidance for unit testing for Durable Functions apps written in C# for the .NET in-process worker and targeting Durable Functions 2.x. For more information about the differences between versions, see the [Durable Functions versions](durable-functions-versions.md) article.

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

@@ -379,10 +379,6 @@ 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"
@@ -412,3 +408,4 @@ If you no longer need the resources that you created to complete the quickstart,
 ## Related content
 
 * Learn about [common Durable Functions app patterns](durable-functions-overview.md#application-patterns).
+* Learn about [Unit Testing Durable Functions in Python](durable-functions-unit-testing-python.md)

articles/azure-functions/functions-reference-python.md

@@ -1427,6 +1427,9 @@ class TestFunction(unittest.TestCase):
 
 Inside your *.venv* Python virtual environment folder, install your favorite Python test framework, such as `pip install pytest`. Then run `pytest tests` to check the test result.
 
+> [!NOTE]
+> Durable Functions require special syntax for unit testing. For more information, refer to [Unit Testing Durable Functions in Python](durable-functions-unit-testing-python.md)
+
 ::: zone-end
 
 ## Temporary files