Add client-declared IsStateful capability to MTP

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person

docs/mstest-runner-protocol/001-protocol-intro.md

@@ -225,6 +225,13 @@ interface InitializeParams {
  // If true, the client supports the testing/testUpdates/attachments request.
  attachmentsSupport: true,
 
+ // If true, the client is stateful: it persists an addressable set of test nodes for the
+ // whole session and keeps each node in its last-known state until it is explicitly updated
+ // (for example, an IDE test explorer). If false or missing, the client is stateless: it
+ // consumes test updates as a stream and does not retain node state after the run
+ // (for example, `dotnet test`). Defaults to false.
+ isStateful: true,
+
  // If true, the client support a port to which child processes
  // can connect to.
  // Note: The test runner is expected to ensure the synchronization of messages

src/Platform/Microsoft.Testing.Platform/Hosts/ConsoleTestHost.cs

@@ -24,7 +24,7 @@ internal sealed class ConsoleTestHost(
  : CommonHost(serviceProvider)
 {
  private static readonly ClientInfo ClientInfoHost = new("testingplatform-console", PlatformVersion.Version);
- private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version);
+ private static readonly IClientInfo ClientInfoService = new ClientInfoService("testingplatform-console", PlatformVersion.Version, new ClientCapabilitiesService(IsStateful: false));
 
  private readonly ILogger<ConsoleTestHost> _logger = serviceProvider.GetLoggerFactory().CreateLogger<ConsoleTestHost>();
  private readonly IClock _clock = serviceProvider.GetClock();

src/Platform/Microsoft.Testing.Platform/Hosts/ServerTestHost.RequestExecution.cs

@@ -38,7 +38,7 @@ private async Task<object> HandleRequestCoreAsync(RequestMessage message, RpcInv
 
  case (JsonRpcMethods.Initialize, InitializeRequestArgs args):
  _client = new(args.ClientInfo.Name, args.ClientInfo.Version);
- _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version);
+ _clientInfoService = new ClientInfoService(args.ClientInfo.Name, args.ClientInfo.Version, new ClientCapabilitiesService(args.Capabilities.IsStateful));
  await _logger.LogDebugAsync($"Connection established with '{_client.Id}', protocol version {_client.Version}").ConfigureAwait(false);
 
  INamedFeatureCapability? namedFeatureCapability = ServiceProvider.GetTestFrameworkCapabilities().GetCapability<INamedFeatureCapability>();

src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt

@@ -1,3 +1,28 @@
 #nullable enable
+const Microsoft.Testing.Platform.ServerMode.JsonRpcStrings.IsStateful = "isStateful" -> string!
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider, bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider, out bool IsStateful) -> void
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.get -> bool
+Microsoft.Testing.Platform.ServerMode.ClientCapabilities.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.<Clone>$() -> Microsoft.Testing.Platform.Services.ClientCapabilitiesService!
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ClientCapabilitiesService(bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Deconstruct(out bool IsStateful) -> void
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? other) -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.get -> bool
+Microsoft.Testing.Platform.Services.ClientCapabilitiesService.IsStateful.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!
+Microsoft.Testing.Platform.Services.ClientInfoService.Capabilities.init -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version, Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version, out Microsoft.Testing.Platform.Services.IClientCapabilities! Capabilities) -> void
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.Equals(object? obj) -> bool
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.GetHashCode() -> int
+override Microsoft.Testing.Platform.Services.ClientCapabilitiesService.ToString() -> string!
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator !=(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+static Microsoft.Testing.Platform.Services.ClientCapabilitiesService.operator ==(Microsoft.Testing.Platform.Services.ClientCapabilitiesService? left, Microsoft.Testing.Platform.Services.ClientCapabilitiesService? right) -> bool
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.ClientCapabilities(bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.ServerMode.ClientCapabilities.Deconstruct(out bool DebuggerProvider) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.ClientInfoService(string! Id, string! Version) -> void
+*REMOVED*Microsoft.Testing.Platform.Services.ClientInfoService.Deconstruct(out string! Id, out string! Version) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.ReadFields(System.IO.Stream! stream, System.Func<ushort, int, bool>! tryReadField) -> void
 static Microsoft.Testing.Platform.IPC.Serializers.BaseSerializer.WriteListPayload<T>(System.IO.Stream! stream, ushort fieldId, T[]? list, System.Action<System.IO.Stream!, T>! writeItem) -> void

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,4 @@
 #nullable enable
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities
+[TPEXP]Microsoft.Testing.Platform.Services.IClientCapabilities.IsStateful.get -> bool
+[TPEXP]Microsoft.Testing.Platform.Services.IClientInfo.Capabilities.get -> Microsoft.Testing.Platform.Services.IClientCapabilities!

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/Json/Json.Deserializers.cs

@@ -128,8 +128,13 @@ private static void RegisterDefaultDeserializers(Dictionary<Type, JsonDeserializ
  {
  jsonElement.TryGetProperty(JsonRpcStrings.Testing, out JsonElement testing);
 
+ bool isStateful = testing.ValueKind == JsonValueKind.Object
+ && testing.TryGetProperty(JsonRpcStrings.IsStateful, out JsonElement statefulElement)
+ && statefulElement.ValueKind == JsonValueKind.True;
+
  return new ClientCapabilities(
- DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider));
+ DebuggerProvider: json.Bind<bool>(testing, JsonRpcStrings.DebuggerProvider),
+ IsStateful: isStateful);
  });
 
  deserializers[typeof(InitializeResponseArgs)] = new JsonElementDeserializer<InitializeResponseArgs>(

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/JsonRpcMethods.cs

@@ -40,6 +40,7 @@ internal static class JsonRpcStrings
  public const string Capabilities = "capabilities";
  public const string Testing = "testing";
  public const string DebuggerProvider = "debuggerProvider";
+ public const string IsStateful = "isStateful";
  public const string SupportsDiscovery = "supportsDiscovery";
  public const string MultiRequestSupport = "experimental_multiRequestSupport";
  public const string VSTestProviderSupport = "vstestProvider";

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/RpcMessages.cs

@@ -90,7 +90,7 @@ internal sealed record InvalidRequestParamsArgs(int ErrorCode, string ErrorMessa
 
 internal sealed record ClientInfo(string Name, string Version);
 
-internal sealed record ClientCapabilities(bool DebuggerProvider);
+internal sealed record ClientCapabilities(bool DebuggerProvider, bool IsStateful);
 
 internal sealed record ServerInfo(string Name, string Version);
 

src/Platform/Microsoft.Testing.Platform/ServerMode/JsonRpc/SerializerUtilities.Deserializers.cs

@@ -110,8 +110,9 @@ private static void RegisterDeserializers()
  IDictionary<string, object?> capabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(properties, JsonRpcStrings.Capabilities);
  IDictionary<string, object?> testingCapabilities = GetRequiredPropertyFromJson<IDictionary<string, object?>>(capabilities, JsonRpcStrings.Testing);
  bool debuggerProvider = GetRequiredPropertyFromJson<bool>(testingCapabilities, JsonRpcStrings.DebuggerProvider);
+ bool isStateful = GetOptionalPropertyFromJson(testingCapabilities, JsonRpcStrings.IsStateful) as bool? ?? false;
 
- return new ClientCapabilities(debuggerProvider);
+ return new ClientCapabilities(debuggerProvider, isStateful);
  });
 
  Deserializers[typeof(InitializeResponseArgs)] = new ObjectDeserializer<InitializeResponseArgs>(properties =>

src/Platform/Microsoft.Testing.Platform/Services/ClientCapabilitiesService.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+internal sealed record ClientCapabilitiesService(bool IsStateful) : IClientCapabilities;

src/Platform/Microsoft.Testing.Platform/Services/ClientInfoService.cs

@@ -3,4 +3,4 @@
 
 namespace Microsoft.Testing.Platform.Services;
 
-internal sealed record ClientInfoService(string Id, string Version) : IClientInfo;
+internal sealed record ClientInfoService(string Id, string Version, IClientCapabilities Capabilities) : IClientInfo;

src/Platform/Microsoft.Testing.Platform/Services/IClientCapabilities.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.Testing.Platform.Services;
+
+/// <summary>
+/// Represents the capabilities declared by the client that is driving the test host.
+/// </summary>
+/// <remarks>
+/// Capabilities are opt-in: unless a client explicitly declares a capability, the platform assumes the
+/// most conservative (default) behavior. This lets a test framework tailor its behavior to how the client
+/// intends to consume the results without having to guess based on the environment or transport.
+/// </remarks>
+[Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
+public interface IClientCapabilities
+{
+ /// <summary>
+ /// Gets a value indicating whether the client is stateful.
+ /// </summary>
+ /// <remarks>
+ /// A stateful client persists an addressable set of test nodes for the whole session and keeps each node in
+ /// its last-known state until it is explicitly updated (for example, an IDE test explorer). A stateless client
+ /// consumes updates as a stream and does not retain node state after the run (for example, <c>dotnet test</c>).
+ /// The default is <see langword="false"/> (stateless); a client opts into stateful behavior.
+ /// </remarks>
+ bool IsStateful { get; }
+}

src/Platform/Microsoft.Testing.Platform/Services/IClientInfo.cs

@@ -18,4 +18,9 @@ public interface IClientInfo
  /// Gets the client version.
  /// </summary>
  string Version { get; }
+
+ /// <summary>
+ /// Gets the capabilities declared by the client.
+ /// </summary>
+ IClientCapabilities Capabilities { get; }
 }

test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/ServerMode/v1.0.0/ClientCapabilities.cs

@@ -11,4 +11,7 @@ public sealed record ClientCapabilities(
 
 public sealed record ClientTestingCapabilities(
  [property: JsonProperty("debuggerProvider")]
- bool DebuggerProvider);
+ bool DebuggerProvider,
+
+ [property: JsonProperty("isStateful")]
+ bool IsStateful = false);

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/ObjectModelConvertersTests.cs

@@ -18,7 +18,7 @@ namespace Microsoft.Testing.Extensions.VSTestBridge.UnitTests.ObjectModel;
 [TestClass]
 public sealed class ObjectModelConvertersTests
 {
- private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0");
+ private static readonly IClientInfo ClientInfo = new ClientInfoService(WellKnownClients.VisualStudio, "1.0.0", new ClientCapabilitiesService(IsStateful: false));
 
  [TestMethod]
  [DataRow(true)]

test/UnitTests/Microsoft.Testing.Extensions.VSTestBridge.UnitTests/ObjectModel/RunSettingsPatcherTests.cs

@@ -22,7 +22,7 @@ public void Patch_WhenNoRunSettingsProvided_CreateRunSettingsWithResultsDirector
  {
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
  XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object,
- new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -41,7 +41,7 @@ public void Patch_WithRunSettingsProvidedButMissingResultsDirectory_AddsElement(
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
 
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectory",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -62,7 +62,7 @@ public void Patch_WithRunSettingsContainingResultsDirectory_EntryIsNotOverridden
 """;
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty), _commandLineOptions.Object);
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)), _commandLineOptions.Object);
  Assert.AreEqual(
  "/PlatformResultDirectoryFromFile",
  runSettingsDocument.XPathSelectElement("RunSettings/RunConfiguration/ResultsDirectory")!.Value);
@@ -91,7 +91,7 @@ public void Patch_WhenRunSettingsExists_MergesParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(runSettings, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];
@@ -115,7 +115,7 @@ public void Patch_WhenRunSettingsDoesNotExist_AddParameters()
  });
 
  _configuration.Setup(x => x[PlatformConfigurationConstants.PlatformResultDirectory]).Returns("/PlatformResultDirectory");
- XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty),
+ XDocument runSettingsDocument = RunSettingsPatcher.Patch(null, _configuration.Object, new ClientInfoService(string.Empty, string.Empty, new ClientCapabilitiesService(IsStateful: false)),
  _commandLineOptions.Object);
 
  XElement[] testRunParameters = [.. runSettingsDocument.XPathSelectElements("RunSettings/TestRunParameters/Parameter")];

test/UnitTests/Microsoft.Testing.Platform.UnitTests/ServerMode/JsonTests.cs

@@ -202,6 +202,91 @@ public void GetProperties_WhenPropertiesDelegateIsNotSet_ThrowsInvalidOperationE
  Assert.Contains(nameof(TestJsonObjectSerializer), exception.Message);
  }
 
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithIsStatefulTrue_StjPath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true, "isStateful": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsTrue(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_InitializeRequest_WithoutIsStateful_StjPath_DefaultsToStateless()
+ {
+ // Arrange
+ Json json = new();
+ const string initializeParams = """
+ {
+ "processId": 1,
+ "clientInfo": { "name": "client", "version": "1.0.0" },
+ "capabilities": { "testing": { "debuggerProvider": true } }
+ }
+ """;
+
+ // Act
+ InitializeRequestArgs args = json.Deserialize<InitializeRequestArgs>(initializeParams.AsMemory());
+
+ // Assert
+ Assert.IsFalse(args.Capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithIsStatefulTrue_JsonitePath_SurfacesStatefulClient()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ ["isStateful"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsTrue(capabilities.IsStateful);
+ }
+
+ [TestMethod]
+ public void Deserialize_ClientCapabilities_WithoutIsStateful_JsonitePath_DefaultsToStateless()
+ {
+ // Arrange
+ Dictionary<string, object?> properties = new()
+ {
+ ["capabilities"] = new Dictionary<string, object?>
+ {
+ ["testing"] = new Dictionary<string, object?>
+ {
+ ["debuggerProvider"] = true,
+ },
+ },
+ };
+
+ // Act
+ ClientCapabilities capabilities = SerializerUtilities.Deserialize<ClientCapabilities>(properties);
+
+ // Assert
+ Assert.IsFalse(capabilities.IsStateful);
+ }
+
  private sealed class TestJsonObjectSerializer : JsonObjectSerializer;
 
  private sealed class Person