Document the execution order (#2873)

docs/testingplatform/Index.md

@@ -24,6 +24,7 @@
 1. Extensions miscellaneous
     1. [IAsyncInitializableExtension & IAsyncCleanableExtension](asyncinitcleanup.md)
     1. [CompositeExtensionFactory\<T\>](compositeextensionfactory.md)
+1. [Testing framework & extensions execution order](executionorder.md)
 1. Services
     1. [IServiceProvider](iserviceprovider.md)
     1. [IConfiguration](configuration.md)

docs/testingplatform/executionorder.md

@@ -0,0 +1,21 @@
+# Testing framework & extensions execution order
+
+The testing platform consists of a [testing framework](itestframework.md) and any number of extensions that can operate [*in-process*](extensionintro.md) or [*out-of-process*](extensionintro.md). This document outlines the **sequence of calls** to all potential extensibility points to provide clarity on when a feature is anticipated to be invoked.
+
+While a *sequence* could be used to depict this, we opt for a straightforward order of invocation calls, which allows for a more comprehensive commentary on the workflow.
+
+1. [ITestHostEnvironmentVariableProvider.UpdateAsync](itesthostenvironmentvariableprovider.md) : Out-of-process
+1. [ITestHostEnvironmentVariableProvider.ValidateTestHostEnvironmentVariablesAsync](itesthostenvironmentvariableprovider.md) : Out-of-process
+1. [ITestHostProcessLifetimeHandler.BeforeTestHostProcessStartAsync](itesthostprocesslifetimehandler.md) : Out-of-process
+1. Test host process start
+1. [ITestHostProcessLifetimeHandler.OnTestHostProcessStartedAsync](itesthostprocesslifetimehandler.md) : Out-of-process, this event can intertwine the actions of *in-process* extensions, depending on race conditions.
+1. [ITestApplicationLifecycleCallbacks.BeforeRunAsync](itestsessionlifetimehandler.md): In-process
+1. [ITestSessionLifetimeHandler.OnTestSessionStartingAsync](itestsessionlifetimehandler.md): In-process
+1. [ITestFramework.CreateTestSessionAsync](itestframework.md): In-process
+1. [ITestFramework.ExecuteRequestAsync](itestframework.md): In-process, this method can be called one or more times. At this point, the testing framework will transmit information to the [IMessageBus](imessagebus.md) that can be utilized by the [IDataConsumer](idataconsumer.md).
+1. [ITestFramework.CloseTestSessionAsync](itestframework.md): In-process
+1. [ITestSessionLifetimeHandler.OnTestSessionFinishingAsync](itestsessionlifetimehandler.md): In-process
+1. [ITestApplicationLifecycleCallbacks.AfterRunAsync](itestsessionlifetimehandler.md): In-process
+1. In-process cleanup, involves calling dispose and [IAsyncCleanableExtension](asyncinitcleanup.md) on all extension points.
+1. [ITestHostProcessLifetimeHandler.OnTestHostProcessExitedAsync](itesthostprocesslifetimehandler.md) : Out-of-process
+1. Out-of-process cleanup, involves calling dispose and [IAsyncCleanableExtension](asyncinitcleanup.md) on all extension points.

docs/testingplatform/idataconsumer.md

@@ -89,5 +89,7 @@ Finally, the api takes a `CancellationToken` which the extension is expected to
 
 > [!IMPORTANT]
 > It's crucial to process the payload directly within the `ConsumeAsync` method. The [IMessageBus](imessagebus.md) can manage both synchronous and asynchronous processing, coordinating the execution with the [testing framework](itestframework.md). Although the consumption process is entirely asynchronous and doesn't block the [IMessageBus.Push](imessagebus.md) at the time of writing, this is an implementation detail that may change in the future due to feature requirements. However, we aim to maintain this interface's simplicity and ensure that this method is always called once, eliminating the need for complex synchronization. Additionally, we automatically manage the scalability of the consumers.
+> [!WARNING]
+> When using `IDataConsumer` in conjunction with [ITestHostProcessLifetimeHandler](itestsessionlifetimehandler.md) within a [composite extension point](compositeextensionfactory.md), **it's crucial to disregard any data received post the execution of [ITestSessionLifetimeHandler.OnTestSessionFinishingAsync](itestsessionlifetimehandler.md)**. The `OnTestSessionFinishingAsync` is the final opportunity to process accumulated data and transmit new information to the [IMessageBus](imessagebus.md), hence, any data consumed beyond this point will not be *utilizable* by the extension.
 
 If your extension requires intensive initialization and you need to use the async/await pattern, you can refer to the [`Async extension initialization and cleanup`](asyncinitcleanup.md). If you need to *share state* between extension points, you can refer to the [`CompositeExtensionFactory<T>`](compositeextensionfactory.md) section.