Jennyf/test md file (#567)

* add testing .md file

* fix

* change md file

* small text changes

* small fixes

* more fixes

* formatting editing

Co-authored-by: Jean-Marc Prieur <jmprieur@microsoft.com>

TESTING.md

@@ -0,0 +1,112 @@
+# How to test the Microsoft.identity.Web project templates (locally or from a NuGet package)
+
+## Introduction
+### When to use this article?
+- Before we release Microsoft.Identity.Web project templates (usually for each release of Microsoft.Identity.Web), we want to make sure that we test them from the release build. 
+- Before we commit changes in the project templates (under ProjectTemplates\templates) in the Microsoft.Identity.Web repo, we want to make sure that we test them in depth from the repo. Changes can be changes of Major versions of package reference of Microsoft.Identity.Web, sync from ASP.NET Core templates. This can also help detecting product bugs so we can do the same before releases of Microsoft.Identity.Web.
+
+### When not to use this article?
+There is another article, explaining how to test templates from a NuGet package generated by ASP.NET Core team: How to test the ASP.NET core templates before they release. 
+
+## Principle:
+In this article you will:
+- Configure the version of the templates to test by setting the ClientSemVer environment variable.
+- Run a script that will:
+  - Generate C# projects corresponding to all the templates in various configurations (no auth, single-org, single-org calling graph, single-org calling web API, Individual B2C, Individual B2C calling Web API (for the Web API and the Blazorwasm hosted templates as B2C does not support OBO)).
+  - Configure the projects with existing Azure AD and B2C apps and client secrets. This is done by a configuration file named `configuration.json`. You will need to add the client secrets (see below).
+  - Build the generated projects (which are grouped in a solution named `test.sln`).
+- Manually test (for now) the generated projects.
+
+## How to generate the test projects?
+In a Developer Command Prompt:
+
+1. cd to the root of the repo (for instance `cd C:\gh\microsoft-identity-web`)
+
+2. Set the version of the templates to test.
+
+   `Set ClientSemVer=0.4.0-preview`
+
+3. Change the directory to ProjectTemplates
+
+   `cd ProjectTemplates`
+
+4. Add client secrets to the Configuration.json file
+   `"B2C_Client_ClientSecret": "sercret_goes_here",`
+   `"AAD_Client_ClientSecret": "sercret_goes_here",`
+   `"AAD_WebApi_ClientSecret": "sercret_goes_here"`
+
+5. Go back to the root of the repo
+
+   `cd ..\..`
+
+   Then perform the following steps. They are different depending on whether you test the templates from the repo, or from a NuGet package that you downloaded (release build)
+   <table border = "2">
+    <tr>
+        <th>If you are testing the templates from the local repo</th>
+        <th>If you are testing the templates from a NuGet package</th>
+    </tr>
+    <tr>
+        <td>6. Delete the NuGet packages from ProjectTemplates\bin\Debug (to be sure to test the right one)</td>
+        <td>6. clean the repo to be sure to start clean. Ignore the ChromeDriver.exe if it cannot be removed.</td>
+    </tr>
+    <tr>
+        <td><code>del ProjectTemplates\bin\Debug\*.nupkg</code></td>
+        <td><code>git clean -xdf</code></td>
+    </tr>
+    <tr>
+        <td>7. Build the repo. This builds everything and generates the NuGet packages</td>
+        <td>7. Copy the NuGet package containing the templates (Microsoft.Identity.Web.ProjectTemplates.version.nupkg) downloaded from the release build and paste it under the <code>ProjectTemplates\bin\Debug</code> folder of the repo. 
+        
+    The version should be the same as the value of <code>ClientSemVer</code> you set in step For instance if you downloaded the <code>Packages.zip</code> file from the  AzureDevOps build and saved it in your Downloads folder before unzipping it, you could run the following command: </td>
+    </tr>
+    <tr>
+        <td><code>dotnet pack Microsoft.Identity.Web.sln</code></td>
+        <td><code>mkdir ProjectTemplates\bin\Debug 
+        
+    copy %UserProfile%\Downloads\Packages\Packages\Microsoft.Identity.Web.ProjectTemplates.%ClientSemVer%.nupkg" ProjectTemplates\bin\Debug</code></td>
+    </tr>
+    <tr>
+        <td>8. Go to the ProjetTemplates folder</td>
+        <td>8. Go to the ProjetTemplates folder</td>
+    </tr>
+    <tr>
+        <td><code>cd ProjectTemplates</code></td>
+        <td><code>cd ProjectTemplates</code></td>
+    </tr>
+    <tr>
+        <td>9. Ensure that the NuGet packages that will be picked-up are the ones generated from the <b>build for the repo</b>. For this you can select the corresponding folders in the Visual Studio NuGet package options UI, or just uncomment the following 3 lines from the NuGet.Config file:</td>
+        <td>9. Ensure that the NuGet packages that will be restored in the test projects are the ones <b>generated from the release build</b>. For this you can select the corresponding folder in the Visual Studio NuGet package options UI, or just add a line corresponding to the folder where your NuGet packages are, in the NuGet.Config file (change:</td>
+    </tr>
+    <tr>
+        <td><p><a href="https://github.com/AzureAD/microsoft-identity-web/blob/f211a9ea80a34402b290b15f933d53b9b54c62e7/ProjectTemplates/nuget.config#L22-L24">Nuget.config Lines 22-24</a></td>
+        <td><p><a href="https://github.com/AzureAD/microsoft-identity-web/blob/f211a9ea80a34402b290b15f933d53b9b54c62e7/ProjectTemplates/nuget.config#L28">Nuget.config Line 28</a></td>
+    </tr>
+    <tr>
+        <td>10. From ProjectTemplates folder, run the <code>Test-templates.bat</code> script:</td>
+        <td>10. From ProjectTemplates folder, run the <code>Test-templates.bat</code> script with an argument to tell the script to pick-up the existing <code>Microsoft.Identity.Web.ProjectTemplates.%ClientSemVer%.nupkg</code> file instead of regenerating it. </td>
+    </tr>
+    <tr>
+        <td><code>Test-templates.bat</code></td>
+        <td><code>Test-templates.bat DontGenerate</code></td>
+    </tr>
+   </table>
+
+
+11. Don't commit the changes to the `configuration.json` (secrets) and the `NuGet.Config` (folder to pick-up NuGet packages from, as they depend on your local disk layout).
+
+## How to test the configured projects manually?
+
+Once the projects are generated from the templates, test them manually.
+
+`cd bin\debug\tests`
+
+`Tests.sln`
+
+Test each project in the solution:
+
+- Starting by the no-auth (we don't want to break this scenario)
+- Then the AAD simple, AAD with Graph, and AAD with Web api (the API is really graph so no need to start a web api)
+- Then the B2C simple templates
+- To test the B2C-calls-web-api templates, you'll need to run the TodoListService of the B2CWebAppCallsWebApi test app in the Microsoft.Identity.Web solution
+  - Note that we could do with testing the B2C-calls-web-api against the Web api deployed in Azure, but testing it against our test project has the interest of enabling debugging
+- To test the web apis templates … TBD …

tools/ConfigureGeneratedApplications/Program.cs

@@ -44,11 +44,8 @@ private static void GenerateIssueMdText(Configuration configuration, string fold
         {
             StringBuilder builder = new StringBuilder();
             builder.AppendLine("## Test the generated templates");
-            builder.AppendLine("1. Build the Microsoft.Identity.Web.sln solution");
-            builder.AppendLine(@"2. Add secrets to the `ProjectTemplates\configuration.json` file");
-            builder.AppendLine(@"3. Run the ProjectTemplates\test-templates.bat file");
-            builder.AppendLine(@"4. Open the `ProjectTemplates\bin\Debug\tests\tests.sln` solution");
-            builder.AppendLine("5. Test the following projects");
+            builder.AppendLine(@"1. Use `TESTING.md` file for steps for testing locally and for testing a release.");
+            builder.AppendLine("2. Test the following projects: ");
             foreach (Project p in configuration.Projects)
             {
                 builder.AppendLine($"   - [ ] {p.ProjectRelativeFolder}");