diff --git a/Directory.Build.props b/Directory.Build.props index 25e725ef65..2bd5603288 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -1,4 +1,9 @@ + + + + true + @@ -18,9 +23,8 @@ not report warnings for missing comments. CS1573: Parameter 'parameter' has no matching param tag in the XML comment for 'parameter' (but other parameters do) - CS1591: Missing XML comment for publicly visible type or member 'Type_or_Member' --> - $(NoWarn),1573,1591 + $(NoWarn),1573 diff --git a/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs b/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs index 7b618018a9..3691d6a931 100644 --- a/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs +++ b/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs @@ -233,6 +233,7 @@ public void Dispose() => (_testHost as IDisposable)?.Dispose(); #if NETCOREAPP + /// public ValueTask DisposeAsync() => _testHost is IAsyncDisposable asyncDisposable ? asyncDisposable.DisposeAsync() diff --git a/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs b/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs index ee8a92dee3..0015c11683 100644 --- a/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs +++ b/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs @@ -15,5 +15,16 @@ namespace Microsoft.Testing.Platform.Capabilities.TestFramework; [Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")] public interface IGracefulStopTestExecutionCapability : ITestFrameworkCapability { + /// + /// This requests the test framework to stop test execution gracefully. + /// + /// + /// If stopping gracefully is taking long, the user may press Ctrl+C to request + /// a hard abort. In that case, test frameworks should respect the cancellation token and finish execution as soon as possible. + /// + /// + /// Stopping gracefully is currently used for the --maximum-failed-tests feature. + /// Test frameworks may decide that a graceful stop should run any remaining class/assembly cleanups, if needed. + /// Task StopTestExecutionAsync(CancellationToken cancellationToken); } diff --git a/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs b/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs index f3500528e9..4a0f96ee0c 100644 --- a/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs +++ b/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs @@ -3,6 +3,9 @@ namespace Microsoft.Testing.Platform.Logging; +/// +/// Specifies a logging level used with APIs. +/// public enum LogLevel { /// diff --git a/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs b/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs index 3a24bf4469..8a0b09687e 100644 --- a/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs +++ b/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs @@ -3,6 +3,9 @@ namespace Microsoft.Testing.Platform.Logging; +/// +/// A set of extension methods for . +/// public static class LoggingExtensions { internal static readonly Func Formatter = @@ -13,51 +16,99 @@ exception is not null #pragma warning restore RS0030 // Do not use banned APIs : state; + /// + /// Asynchronously logs a message with . + /// public static Task LogTraceAsync(this ILogger logger, string message) => logger.LogAsync(LogLevel.Trace, message, null, Formatter); + /// + /// Asynchronously logs a message with . + /// public static Task LogDebugAsync(this ILogger logger, string message) => logger.LogAsync(LogLevel.Debug, message, null, Formatter); + /// + /// Asynchronously logs a message with . + /// public static Task LogInformationAsync(this ILogger logger, string message) => logger.LogAsync(LogLevel.Information, message, null, Formatter); + /// + /// Asynchronously logs a message with . + /// public static Task LogWarningAsync(this ILogger logger, string message) => logger.LogAsync(LogLevel.Warning, message, null, Formatter); + /// + /// Asynchronously logs a message with . + /// public static Task LogErrorAsync(this ILogger logger, string message) => logger.LogAsync(LogLevel.Error, message, null, Formatter); + /// + /// Asynchronously logs a message with which is associated with an exception. + /// public static Task LogErrorAsync(this ILogger logger, string message, Exception ex) => logger.LogAsync(LogLevel.Error, message, ex, Formatter); + /// + /// Asynchronously logs an exception with . + /// public static Task LogErrorAsync(this ILogger logger, Exception ex) => logger.LogAsync(LogLevel.Error, ex.ToString(), null, Formatter); + /// + /// Asynchronously logs a message with . + /// public static Task LogCriticalAsync(this ILogger logger, string message) => logger.LogAsync(LogLevel.Critical, message, null, Formatter); + /// + /// Logs a message with . + /// public static void LogTrace(this ILogger logger, string message) => logger.Log(LogLevel.Trace, message, null, Formatter); + /// + /// Logs a message with . + /// public static void LogDebug(this ILogger logger, string message) => logger.Log(LogLevel.Debug, message, null, Formatter); + /// + /// Logs a message with . + /// public static void LogInformation(this ILogger logger, string message) => logger.Log(LogLevel.Information, message, null, Formatter); + /// + /// Logs a message with . + /// public static void LogWarning(this ILogger logger, string message) => logger.Log(LogLevel.Warning, message, null, Formatter); + /// + /// Logs a message with . + /// public static void LogError(this ILogger logger, string message) => logger.Log(LogLevel.Error, message, null, Formatter); + /// + /// Logs a message with which is associated with an exception. + /// public static void LogError(this ILogger logger, string message, Exception ex) => logger.Log(LogLevel.Error, message, ex, Formatter); + /// + /// Logs an exception with . + /// public static void LogError(this ILogger logger, Exception ex) => logger.Log(LogLevel.Error, ex.ToString(), null, Formatter); + /// + /// Logs a message with . + /// public static void LogCritical(this ILogger logger, string message) => logger.Log(LogLevel.Critical, message, null, Formatter); } diff --git a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs b/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs index e7b5cc0cb3..e36ab97388 100644 --- a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs +++ b/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs @@ -3,7 +3,18 @@ namespace Microsoft.Testing.Platform.OutputDevice; +/// +/// Represents output device data that should be displayed as error. +/// +/// +/// It's up to the output device to decide how to display error messages. +/// The built-in terminal output device will print errors in red foreground. +/// The built-in server mode output device will send the data to Test Explorer with Error severity. +/// public sealed class ErrorMessageOutputDeviceData(string message) : IOutputDeviceData { + /// + /// Gets the message text represented by this instance. + /// public string Message { get; } = message; } diff --git a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs b/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs index e56f33950c..c5a5a499e0 100644 --- a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs +++ b/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs @@ -3,7 +3,18 @@ namespace Microsoft.Testing.Platform.OutputDevice; +/// +/// Represents output device data that is associated with an exception. +/// +/// +/// It's up to the output device to decide how to display exceptions. +/// The built-in terminal output device will print the exception in red foreground. +/// The built-in server mode output device will send the data to Test Explorer with Error severity. +/// public sealed class ExceptionOutputDeviceData(Exception exception) : IOutputDeviceData { + /// + /// Gets the exception associated with this instance. + /// public Exception Exception { get; } = exception; } diff --git a/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs b/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs index f4b9ee22cb..bc5962dfc5 100644 --- a/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs +++ b/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs @@ -3,7 +3,18 @@ namespace Microsoft.Testing.Platform.OutputDevice; +/// +/// Represents output device data that should be displayed as warning. +/// +/// +/// It's up to the output device to decide how to display error messages. +/// The built-in terminal output device will print warnings in yellow foreground. +/// The built-in server mode output device will send the data to Test Explorer with Warning severity. +/// public sealed class WarningMessageOutputDeviceData(string message) : IOutputDeviceData { + /// + /// Gets the message text represented by this instance. + /// public string Message { get; } = message; }