Add Blazor SWA Baseline Mismatched Assets Logging

documentation/project-docs/blazor-swa-baseline-generation.md

@@ -0,0 +1,19 @@
+# Blazor WebAssembly Static Web Asset (SWA) Baseline Generation
+
+The Blazor WASM SWA baselines are used to determine if the expected assets in the manifest are present, and if new assets have been added. Occasionally, it's required to update the SWA baselines to account for expected changes in the packaged files.
+
+**Please note:** These steps must be performed in a Windows development environment otherwise the line-ending and ordering result in very large diff-counts.
+
+## Updating Baselines
+
+1. Clone SDK repo: `git clone [email protected]:dotnet/sdk.git`
+    - Switch branches as appropriate
+2. Restore repo: `.\restore.cmd`
+3. Build dotnet: `.\build.cmd`
+4. Activate local dotnet environment: `.\eng\dogfood.cmd`
+5. Enter the following into the CLI from the activated dogfood environment to open VS: `.\src\BlazorWasmSdk\BlazorWasmSdk.slnf`
+6. Open `src\Tests\Microsoft.NET.Sdk.Razor.Tests\AspNetSdkBaselineTest.cs`
+7. Add `#define GENERATE_SWA_BASELINES` on the first line (above the license comment)
+8. Run all tests from `Microsoft.NET.Sdk.BlazorWebAssembly.Tests.csproj`
+9. Delete `#define GENERATE_SWA_BASELINES` from step 7.
+10. Commit the changes to the project baselines.

src/Tests/Microsoft.NET.Sdk.Razor.Tests/AspNetSdkBaselineTest.cs

@@ -356,8 +356,36 @@ internal void AssertManifest(
                     .Should()
                     .BeEquivalentTo(expected.ReferencedProjectsConfiguration.OrderBy(cm => cm.Identity));
                 manifest.DiscoveryPatterns.OrderBy(dp => dp.Name).ShouldBeEquivalentTo(expected.DiscoveryPatterns.OrderBy(dp => dp.Name));
-                manifest.Assets.OrderBy(a => a.BasePath).ThenBy(a => a.RelativePath).ThenBy(a => a.AssetKind)
-                    .ShouldBeEquivalentTo(expected.Assets.OrderBy(a => a.BasePath).ThenBy(a => a.RelativePath).ThenBy(a => a.AssetKind));
+
+                var manifestAssets = manifest.Assets.OrderBy(a => a.BasePath).ThenBy(a => a.RelativePath).ThenBy(a => a.AssetKind);
+                var expectedAssets = expected.Assets.OrderBy(a => a.BasePath).ThenBy(a => a.RelativePath).ThenBy(a => a.AssetKind);
+
+                manifestAssets.ShouldBeEquivalentTo(expectedAssets, AssetDifferencesDetails(manifestAssets, expectedAssets));
+
+                static string AssetDifferencesDetails(IEnumerable<StaticWebAsset> manifestAssets, IEnumerable<StaticWebAsset> expectedAssets)
+                {
+                    var missingAssets = expectedAssets.Except(manifestAssets);
+                    var unexpectedAssets = manifestAssets.Except(expectedAssets);
+
+                    var differences = new List<string>();
+
+                    if (missingAssets.Any())
+                    {
+                        differences.Add($"The following expected assets weren't found in the manifest {string.Join(", ", missingAssets.Select(a => a.Identity))}.");
+                    }
+
+                    if (unexpectedAssets.Any())
+                    {
+                        differences.Add($"The following additional unexpected assets were found in the manifest {string.Join(", ", unexpectedAssets.Select(a => a.Identity))}.");
+                    }
+
+                    if (differences.Any())
+                    {
+                        differences.Add("If the difference in baselines is expected, please re-generate the baselines. Instructions are available at https://aka.ms/aspnet/blazor/blazor-wasm-sdk-baselines");
+                    }
+
+                    return string.Join(Environment.NewLine, differences);
+                }
             }
             else
             {