Add mirror source structure for verified files

docs/mdsource/naming.source.md

@@ -249,6 +249,14 @@ For example to place all `.verified.` files in a `{ProjectDirectory}\Snapshots`
 Verifier.UseProjectRelativeDirectory("Snapshots");
 ```
 
+To nest the `.verified.` files in sub-directories that mirror the directory structure of the test source files (relative to the project directory), enable `mirrorSourceStructure`:
+
+```
+Verifier.UseProjectRelativeDirectory("Snapshots", mirrorSourceStructure: true);
+```
+
+For example a test in `{ProjectDirectory}\Foo\FooTests.cs` would then have its `.verified.` files placed in `{ProjectDirectory}\Snapshots\Foo`. This can make orphaned snapshots easier to identify when test source files are moved, renamed, or removed.
+
 
 ### UseSourceFileRelativeDirectory
 

docs/naming.md

@@ -805,6 +805,14 @@ For example to place all `.verified.` files in a `{ProjectDirectory}\Snapshots`
 Verifier.UseProjectRelativeDirectory("Snapshots");
 ```
 
+To nest the `.verified.` files in sub-directories that mirror the directory structure of the test source files (relative to the project directory), enable `mirrorSourceStructure`:
+
+```
+Verifier.UseProjectRelativeDirectory("Snapshots", mirrorSourceStructure: true);
+```
+
+For example a test in `{ProjectDirectory}\Foo\FooTests.cs` would then have its `.verified.` files placed in `{ProjectDirectory}\Snapshots\Foo`. This can make orphaned snapshots easier to identify when test source files are moved, renamed, or removed.
+
 
 ### UseSourceFileRelativeDirectory
 

src/Directory.Build.props

@@ -2,7 +2,7 @@
 <Project>
   <PropertyGroup>
     <NoWarn>CA1822;CS1591;CS0649;xUnit1026;xUnit1013;CS1573;VerifyTestsProjectDir;VerifySetParameters;PolyFillTargetsForNuget;xUnit1051;NU1608;NU1109</NoWarn>
-    <Version>31.24.3</Version>
+    <Version>31.25.0</Version>
     <ImplicitUsings>enable</ImplicitUsings>
     <LangVersion>preview</LangVersion>
     <AssemblyVersion>1.0.0</AssemblyVersion>

src/Verify.Expecto/DerivePaths/Verifier.cs

@@ -27,12 +27,22 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo)
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
+        UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
         DerivePathInfo(
-            (sourceFile, projectDirectory, typeName, methodName) => new(
-                directory: Path.Combine(projectDirectory, directory),
-                typeName: typeName,
-                methodName: methodName));
+            (sourceFile, projectDirectory, typeName, methodName) =>
+                PathInfo.DeriveProjectRelative(directory, mirrorSourceStructure, sourceFile, projectDirectory, typeName, methodName));
 
     /// <summary>
     /// Use a directory relative to the source file directory for storing for `.verified.` files.

src/Verify.Fixie/DerivePaths/Verifier.cs

@@ -27,12 +27,22 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo)
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
+        UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
         DerivePathInfo(
-            (sourceFile, projectDirectory, type, method) => new(
-                directory: Path.Combine(projectDirectory, directory),
-                typeName: type.NameWithParent(),
-                methodName: method.Name));
+            (sourceFile, projectDirectory, type, method) =>
+                PathInfo.DeriveProjectRelative(directory, mirrorSourceStructure, sourceFile, projectDirectory, type.NameWithParent(), method.Name));
 
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.

src/Verify.MSTest/DerivePaths/Verifier.cs

@@ -27,12 +27,22 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo)
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
+        UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
         DerivePathInfo(
-            (sourceFile, projectDirectory, type, method) => new(
-                directory: Path.Combine(projectDirectory, directory),
-                typeName: type.NameWithParent(),
-                methodName: method.Name));
+            (sourceFile, projectDirectory, type, method) =>
+                PathInfo.DeriveProjectRelative(directory, mirrorSourceStructure, sourceFile, projectDirectory, type.NameWithParent(), method.Name));
 
     /// <summary>
     /// Use a directory relative to the source file directory for storing for `.verified.` files.

src/Verify.MSTest/DerivePaths/VerifyBase.cs

@@ -19,8 +19,20 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo) =>
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
-        Verifier.UseProjectRelativeDirectory(directory);
+        Verifier.UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
+        Verifier.UseProjectRelativeDirectory(directory, mirrorSourceStructure);
 
     /// <summary>
     /// Use a directory relative to the source file directory for storing for `.verified.` files.

src/Verify.NUnit/DerivePaths/Verifier.cs

@@ -27,12 +27,22 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo)
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
+        UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
         DerivePathInfo(
-            (sourceFile, projectDirectory, type, method) => new(
-                directory: Path.Combine(projectDirectory, directory),
-                typeName: type.NameWithParent(),
-                methodName: method.Name));
+            (sourceFile, projectDirectory, type, method) =>
+                PathInfo.DeriveProjectRelative(directory, mirrorSourceStructure, sourceFile, projectDirectory, type.NameWithParent(), method.Name));
 
     /// <summary>
     /// Use a directory relative to the source file directory for storing for `.verified.` files.

src/Verify.TUnit/DerivePaths/Verifier.cs

@@ -27,12 +27,22 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo)
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
+        UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
         DerivePathInfo(
-            (sourceFile, projectDirectory, type, method) => new(
-                directory: Path.Combine(projectDirectory, directory),
-                typeName: type.NameWithParent(),
-                methodName: method.Name));
+            (sourceFile, projectDirectory, type, method) =>
+                PathInfo.DeriveProjectRelative(directory, mirrorSourceStructure, sourceFile, projectDirectory, type.NameWithParent(), method.Name));
 
     /// <summary>
     /// Use a directory relative to the source file directory for storing for `.verified.` files.

src/Verify.Tests/DeriveProjectRelativeDirectoryTests.cs

@@ -0,0 +1,42 @@
+public class DeriveProjectRelativeDirectoryTests
+{
+    static readonly string projectDirectory = Path.Combine(Path.GetTempPath(), "project");
+
+    static string? Derive(string sourceFile, bool mirrorSourceStructure) =>
+        PathInfo.DeriveProjectRelative(
+                "Snapshots",
+                mirrorSourceStructure,
+                sourceFile,
+                projectDirectory,
+                "TheType",
+                "TheMethod")
+            .Directory;
+
+    [Fact]
+    public void NotMirroredUsesRoot()
+    {
+        var source = Path.Combine(projectDirectory, "Foo", "MyTests.cs");
+        Assert.Equal(Path.Combine(projectDirectory, "Snapshots"), Derive(source, false));
+    }
+
+    [Fact]
+    public void MirrorsNestedSourceStructure()
+    {
+        var source = Path.Combine(projectDirectory, "Foo", "Bar", "MyTests.cs");
+        Assert.Equal(Path.Combine(projectDirectory, "Snapshots", "Foo", "Bar"), Derive(source, true));
+    }
+
+    [Fact]
+    public void MirrorAtProjectRootUsesRoot()
+    {
+        var source = Path.Combine(projectDirectory, "MyTests.cs");
+        Assert.Equal(Path.Combine(projectDirectory, "Snapshots"), Derive(source, true));
+    }
+
+    [Fact]
+    public void MirrorSourceOutsideProjectUsesRoot()
+    {
+        var source = Path.Combine(Path.GetTempPath(), "other", "MyTests.cs");
+        Assert.Equal(Path.Combine(projectDirectory, "Snapshots"), Derive(source, true));
+    }
+}

src/Verify.XunitV3.DerivePaths.Tests/Relative/SubDir/Tests.ProjectRelativeDirectoryMirrored.verified.txt

@@ -0,0 +1 @@
+Value

src/Verify.XunitV3.DerivePaths.Tests/SubDir/Tests.Mirror.cs

@@ -0,0 +1,13 @@
+// This partial is intentionally located in a sub-directory so that its source file path,
+// relative to the project directory, is "SubDir". That exercises the mirrorSourceStructure
+// option, nesting the derived `.verified.` file under "Relative/SubDir".
+public partial class Tests
+{
+    [Fact]
+    public Task ProjectRelativeDirectoryMirrored()
+    {
+        VerifierSettings.Reset();
+        UseProjectRelativeDirectory("Relative", mirrorSourceStructure: true);
+        return Verify("Value");
+    }
+}

src/Verify.XunitV3.DerivePaths.Tests/Tests.cs

@@ -1,4 +1,4 @@
-public class Tests
+public partial class Tests
 {
     [Fact]
     public Task Test()

src/Verify.XunitV3/DerivePaths/Verifier.cs

@@ -27,12 +27,22 @@ public static void DerivePathInfo(DerivePathInfo derivePathInfo)
     /// <summary>
     /// Use a directory relative to the project directory for storing for `.verified.` files.
     /// </summary>
+    [Obsolete("Use the overload that accepts mirrorSourceStructure.")]
     public static void UseProjectRelativeDirectory(string directory) =>
+        UseProjectRelativeDirectory(directory, false);
+
+    /// <summary>
+    /// Use a directory relative to the project directory for storing for `.verified.` files.
+    /// </summary>
+    /// <param name="directory">The project relative directory to store `.verified.` files in.</param>
+    /// <param name="mirrorSourceStructure">
+    /// If true, nests `.verified.` files in sub-directories that mirror the directory structure of the test source files relative to the project directory.
+    /// </param>
+    [OverloadResolutionPriority(1)]
+    public static void UseProjectRelativeDirectory(string directory, bool mirrorSourceStructure = false) =>
         DerivePathInfo(
-            (sourceFile, projectDirectory, type, method) => new(
-                directory: Path.Combine(projectDirectory, directory),
-                typeName: type.NameWithParent(),
-                methodName: method.Name));
+            (sourceFile, projectDirectory, type, method) =>
+                PathInfo.DeriveProjectRelative(directory, mirrorSourceStructure, sourceFile, projectDirectory, type.NameWithParent(), method.Name));
 
     /// <summary>
     /// Use a directory relative to the source file directory for storing for `.verified.` files.

src/Verify/DerivePaths/PathInfo.cs

@@ -43,6 +43,39 @@ public static PathInfo DeriveDefault(
 
     #endregion
 
+    /// <summary>
+    /// Derives a <see cref="PathInfo" /> that stores `.verified.` files in <paramref name="directory" /> relative to
+    /// <paramref name="projectDirectory" />. When <paramref name="mirrorSourceStructure" /> is true, the files are
+    /// nested in sub-directories that mirror the directory structure of the test source file relative to the project
+    /// directory. Source files at, above, or outside the project directory fall back to <paramref name="directory" />.
+    /// </summary>
+    public static PathInfo DeriveProjectRelative(
+        string directory,
+        bool mirrorSourceStructure,
+        string sourceFile,
+        string projectDirectory,
+        string? typeName,
+        string? methodName)
+    {
+        var resolved = Path.Combine(projectDirectory, directory);
+        if (mirrorSourceStructure)
+        {
+            var sourceDirectory = Path.GetDirectoryName(sourceFile)!;
+            var relative = Path.GetRelativePath(projectDirectory, sourceDirectory);
+            if (relative != "." &&
+                !relative.StartsWith("..", StringComparison.Ordinal) &&
+                !Path.IsPathRooted(relative))
+            {
+                resolved = Path.Combine(resolved, relative);
+            }
+        }
+
+        return new(
+            directory: resolved,
+            typeName: typeName,
+            methodName: methodName);
+    }
+
     internal static PathInfo DeriveDefault(
         string sourceFile,
         string projectDirectory,