Extract reusable MSAL test infrastructure into Microsoft.Identity.Lab.API

PerformanceTests.sln

@@ -5,9 +5,9 @@ VisualStudioVersion = 17.0.31808.319
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Identity.Test.Performance", "tests\Microsoft.Identity.Test.Performance\Microsoft.Identity.Test.Performance.csproj", "{E22D6CD2-E738-4748-900D-BB7C49AF1A67}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Identity.Client", "src\client\Microsoft.Identity.Client\Microsoft.Identity.Client.csproj", "{E94D56E5-AAF5-4BF1-B956-BB600F6E1C0C}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Identity.Client.TestOnly", "src\client\Microsoft.Identity.Client.TestOnly\Microsoft.Identity.Client.TestOnly.csproj", "{B2A3C9E1-5D6F-4832-A7E0-F8B1C3D4E5F6}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Identity.Test.Common", "tests\Microsoft.Identity.Test.Common\Microsoft.Identity.Test.Common.csproj", "{89EB6A48-9E4B-4DD9-AE02-6D782A33C4A0}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Identity.Client", "src\client\Microsoft.Identity.Client\Microsoft.Identity.Client.csproj", "{E94D56E5-AAF5-4BF1-B956-BB600F6E1C0C}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -23,15 +23,15 @@ Global
 		{E94D56E5-AAF5-4BF1-B956-BB600F6E1C0C}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E94D56E5-AAF5-4BF1-B956-BB600F6E1C0C}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{E94D56E5-AAF5-4BF1-B956-BB600F6E1C0C}.Release|Any CPU.Build.0 = Release|Any CPU
-		{89EB6A48-9E4B-4DD9-AE02-6D782A33C4A0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{89EB6A48-9E4B-4DD9-AE02-6D782A33C4A0}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{89EB6A48-9E4B-4DD9-AE02-6D782A33C4A0}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{89EB6A48-9E4B-4DD9-AE02-6D782A33C4A0}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {7BA85844-C0D1-42F5-9DBC-4335CB26C703}
+		{B2A3C9E1-5D6F-4832-A7E0-F8B1C3D4E5F6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B2A3C9E1-5D6F-4832-A7E0-F8B1C3D4E5F6}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B2A3C9E1-5D6F-4832-A7E0-F8B1C3D4E5F6}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B2A3C9E1-5D6F-4832-A7E0-F8B1C3D4E5F6}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 EndGlobal

build/template-pack-and-sign-all-nugets.yaml

@@ -51,6 +51,13 @@ steps:
     ProjectRootPath: '$(Build.SourcesDirectory)\$(MsalSourceDir)src\client'
     AssemblyName: 'Microsoft.Identity.Client.KeyAttestation'
 
+# Sign binary and pack Microsoft.Identity.Lab.Api
+- template: template-pack-and-sign-nuget.yaml
+  parameters:
+    BuildConfiguration: ${{ parameters.BuildConfiguration }}
+    ProjectRootPath: '$(Build.SourcesDirectory)\$(MsalSourceDir)src\client'
+    AssemblyName: 'Microsoft.Identity.Lab.Api'
+
 # Copy all packages out to staging
 - task: CopyFiles@2
   displayName: 'Copy Files to: $(Build.ArtifactStagingDirectory)\packages'

docs/cache_extensibility.md

@@ -117,7 +117,7 @@ In user flows, only the access tokens will be cached by the new schema. Refresh
 - Call `AcquireTokenForClient` with no extensibility. Assert cache miss.
 - Call `AcquireTokenForClient` with the same "key1"="val1". Assert cache miss.
 - Call `AcquireTokenForClient` with the same "key1"="val1", "key2"="foo". Assert cache miss.
-- Call `AcquireTokenForClient` with the same "Key1"="val1", "key2"="val2". Assert cache miss (capital "K" used in "key1")
+- Call `AcquireTokenForClient` with the same "Key1"="val1", "key2"="val2". Assert cache miss (uppercase "K" used in "key1")
 
 2. Forwards compatibility test: old MSAL must function side by side with new MSAL, i.e. old MSAL must ignore the new access token cache entries. 
 

src/client/Microsoft.Identity.Client/Properties/InternalsVisibleTo.cs

@@ -10,7 +10,7 @@
 [assembly: InternalsVisibleTo("Microsoft.Identity.Client.KeyAttestation" + KeyTokens.MSAL)]
 
 [assembly: InternalsVisibleTo("Microsoft.Identity.Test.Unit" + KeyTokens.MSAL)]
-[assembly: InternalsVisibleTo("Microsoft.Identity.Test.Common" + KeyTokens.MSAL)]
+[assembly: InternalsVisibleTo("Microsoft.Identity.Lab.Api" + KeyTokens.MSAL)]
 [assembly: InternalsVisibleTo("Microsoft.Identity.Test.SideBySide" + KeyTokens.MSAL)]
 [assembly: InternalsVisibleTo("Microsoft.Identity.Test.Integration.NetCore" + KeyTokens.MSAL)]
 [assembly: InternalsVisibleTo("Microsoft.Identity.Test.Integration.NetFx" + KeyTokens.MSAL)]

src/client/Microsoft.Identity.Lab.Api/AuthorityWithExpectedTenantId.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+
+namespace Microsoft.Identity.Test.Common
+{
+    /// <summary>
+    /// Represents an authority URI and its expected tenant ID for testing purposes.
+    /// </summary>
+    public class AuthorityWithExpectedTenantId
+    {
+        /// <summary>
+        /// Gets or sets the authority URI.
+        /// </summary>
+        public Uri Authority { get; set; }
+
+        /// <summary>
+        /// Gets or sets the expected tenant ID.
+        /// </summary>
+        public string ExpectedTenantId { get; set; }
+
+        /// <summary>
+        /// Converts the authority and expected tenant ID to an object array.
+        /// </summary>
+        /// <returns>An array containing the authority and expected tenant ID.</returns>
+        public object[] ToObjectArray()
+        {
+            return new object[] { Authority, ExpectedTenantId };
+        }
+    }
+}

tests/Microsoft.Identity.Test.Common/Core/Helpers/AssertException.cs → src/client/Microsoft.Identity.Lab.Api/Helpers/AssertException.cs

@@ -10,8 +10,16 @@
 
 namespace Microsoft.Identity.Test.Common.Core.Helpers
 {
+    /// <summary>
+    /// AssertException provides a set of assertion methods for verifying that specific exceptions are thrown or not thrown by a given piece of code. It includes methods for both synchronous and asynchronous code, allowing developers to easily test exception handling in their unit tests. The class uses a nested Recorder class to execute the test code and capture any exceptions that occur, providing detailed error messages when assertions fail.
+    /// </summary>
     public static class AssertException
     {
+        /// <summary>
+        /// DoesNotThrow verifies that the provided test code does not throw any exceptions. If an exception is thrown, it captures the exception and throws an AssertFailedException with a message indicating that the assertion failed and includes details of the exception that was thrown.
+        /// </summary>
+        /// <param name="testCode">The code to test for exceptions.</param>
+        /// <exception cref="AssertFailedException">Thrown if the test code throws an exception.</exception>
         public static void DoesNotThrow(Action testCode)
         {
             var ex = Recorder.Exception<Exception>(testCode);
@@ -21,6 +29,11 @@ public static void DoesNotThrow(Action testCode)
             }
         }
 
+        /// <summary>
+        /// DoesNotThrow verifies that the provided test code does not throw any exceptions. If an exception is thrown, it captures the exception and throws an AssertFailedException with a message indicating that the assertion failed and includes details of the exception that was thrown.
+        /// </summary>
+        /// <param name="testCode">The code to test for exceptions.</param>
+        /// <exception cref="AssertFailedException">Thrown if the test code throws an exception.</exception>
         public static void DoesNotThrow(Func<object> testCode)
         {
             var ex = Recorder.Exception<Exception>(testCode);
@@ -30,12 +43,27 @@ public static void DoesNotThrow(Func<object> testCode)
             }
         }
 
+        /// <summary>
+        /// Throws verifies that the provided test code throws an exception of type <typeparamref name="TException"/>. If no exception is thrown or a different exception type is thrown, an AssertFailedException is raised.
+        /// </summary>
+        /// <typeparam name="TException">The type of exception expected to be thrown.</typeparam>
+        /// <param name="testCode">The code to test for exceptions.</param>
+        /// <returns>The exception that was thrown by the test code.</returns>
+        /// <exception cref="AssertFailedException">Thrown if the test code does not throw an exception or throws a different exception type.</exception>
         public static TException Throws<TException>(Action testCode)
              where TException : Exception
         {
             return Throws<TException>(testCode, false);
         }
 
+        /// <summary>
+        /// Throws verifies that the provided test code throws an exception of type <typeparamref name="TException"/> or a derived type. If no exception is thrown or an incompatible exception type is thrown, an AssertFailedException is raised.
+        /// </summary>
+        /// <typeparam name="TException">The type of exception expected to be thrown.</typeparam>
+        /// <param name="testCode">The code to test for exceptions.</param>
+        /// <param name="allowDerived">If true, allows exceptions derived from <typeparamref name="TException"/>. If false, requires an exact type match.</param>
+        /// <returns>The exception that was thrown by the test code.</returns>
+        /// <exception cref="AssertFailedException">Thrown if the test code does not throw an exception or throws an incompatible exception type.</exception>
         public static TException Throws<TException>(Action testCode, bool allowDerived)
              where TException : Exception
         {
@@ -51,12 +79,27 @@ public static TException Throws<TException>(Action testCode, bool allowDerived)
             return exception;
         }
 
+        /// <summary>
+        /// Throws verifies that the provided test code throws an exception of type <typeparamref name="TException"/>. If no exception is thrown or a different exception type is thrown, an AssertFailedException is raised.
+        /// </summary>
+        /// <typeparam name="TException">The type of exception expected to be thrown.</typeparam>
+        /// <param name="testCode">The code to test for exceptions.</param>
+        /// <returns>The exception that was thrown by the test code.</returns>
+        /// <exception cref="AssertFailedException">Thrown if the test code does not throw an exception or throws a different exception type.</exception>
         public static TException Throws<TException>(Func<object> testCode)
             where TException : Exception
         {
             return Throws<TException>(testCode, false);
         }
 
+        /// <summary>
+        /// Throws verifies that the provided test code throws an exception of type <typeparamref name="TException"/> or a derived type. If no exception is thrown or an incompatible exception type is thrown, an AssertFailedException is raised.
+        /// </summary>
+        /// <typeparam name="TException">The type of exception expected to be thrown.</typeparam>
+        /// <param name="testCode">The code to test for exceptions.</param>
+        /// <param name="allowDerived">If true, allows exceptions derived from <typeparamref name="TException"/>. If false, requires an exact type match.</param>
+        /// <returns>The exception that was thrown by the test code.</returns>
+        /// <exception cref="AssertFailedException">Thrown if the test code does not throw an exception or throws an incompatible exception type.</exception>
         public static TException Throws<TException>(Func<object> testCode, bool allowDerived)
             where TException : Exception
         {
@@ -72,6 +115,14 @@ public static TException Throws<TException>(Func<object> testCode, bool allowDer
             return exception;
         }
 
+        /// <summary>
+        /// TaskThrowsAsync verifies that the provided asynchronous test code throws an exception of type <typeparamref name="T"/> or a derived type. If no exception is thrown or an incompatible exception type is thrown, an AssertFailedException is raised.
+        /// </summary>
+        /// <typeparam name="T">The type of exception expected to be thrown.</typeparam>
+        /// <param name="testCode">The asynchronous code to test for exceptions.</param>
+        /// <param name="allowDerived">If true, allows exceptions derived from <typeparamref name="T"/>. If false, requires an exact type match.</param>
+        /// <returns>A task that represents the asynchronous operation, containing the exception that was thrown by the test code.</returns>
+        /// <exception cref="AssertFailedException">Thrown if the test code does not throw an exception or throws an incompatible exception type.</exception>
         public static async Task<T> TaskThrowsAsync<T>(Func<Task> testCode, bool allowDerived = false)
             where T : Exception
         {
@@ -112,6 +163,11 @@ public static async Task<T> TaskThrowsAsync<T>(Func<Task> testCode, bool allowDe
             return (exception as T);
         }
 
+        /// <summary>
+        /// TaskDoesNotThrow verifies that the provided asynchronous test code does not throw any exceptions. If an exception is thrown, it captures the exception and throws an AssertFailedException with a message indicating that the assertion failed and includes details of the exception that was thrown.
+        /// </summary>
+        /// <param name="testCode">The asynchronous code to test for exceptions.</param>
+        /// <exception cref="AssertFailedException">Thrown if the test code throws an exception.</exception>
         public static void TaskDoesNotThrow(Func<Task> testCode)
         {
             var exception = Recorder.Exception(() => testCode().Wait());
@@ -130,6 +186,12 @@ public static void TaskDoesNotThrow(Func<Task> testCode)
                 exception);
         }
 
+        /// <summary>
+        /// TaskDoesNotThrow verifies that the provided asynchronous test code does not throw an exception of type <typeparamref name="T"/> or any derived type. If such an exception is thrown, an AssertFailedException is raised.
+        /// </summary>
+        /// <typeparam name="T">The type of exception to verify is not thrown.</typeparam>
+        /// <param name="testCode">The asynchronous code to test for exceptions.</param>
+        /// <exception cref="AssertFailedException">Thrown if the test code throws an exception of type <typeparamref name="T"/> or a derived type.</exception>
         public static void TaskDoesNotThrow<T>(Func<Task> testCode) where T : Exception
         {
             var exception = Recorder.Exception<AggregateException>(() => testCode().Wait());