Add --coverlet-file-prefix option for unique report files

Introduce --coverlet-file-prefix to allow custom prefixes for coverage report filenames, preventing overwrites in multi-project test runs. Updated documentation, command-line parsing, configuration, and report generation logic to support the new option. Added comprehensive unit tests for filename generation and option handling. Improves usability in CI and multi-project scenarios.

Author: Bertk

Documentation/Coverlet.MTP.Integration.md

@@ -78,6 +78,7 @@ dotnet exec <test-assembly.dll> --help
 | :------- | :------------ |
 | `--coverlet` | Enable code coverage data collection. |
 | `--coverlet-output-format <format>` | Output format(s) for coverage report. Supported formats: `json`, `lcov`, `opencover`, `cobertura`, `teamcity`. Can be specified multiple times. (default: `json`, `cobertura`) |
+| `--coverlet-file-prefix <prefix>` | Prefix for coverage report filenames to prevent overwrites when multiple test projects write to the same directory. When specified, files are named `<prefix>.coverage.<extension>` instead of `coverage.<extension>`. (default: `none`) |
 | `--coverlet-include <filter>` | Include assemblies matching filters (e.g., `[Assembly]Type`). Can be specified multiple times. (default: `none`) |
 | `--coverlet-include-directory <path>` | Include additional directories for sources. Can be specified multiple times. (default: `none`) |
 | `--coverlet-exclude <filter>` | Exclude assemblies matching filters (e.g., `[Assembly]Type`). Can be specified multiple times. User-specified filters are merged with defaults. (default: `[coverlet.*]*`, `[xunit.*]*`, `[NUnit3.*]*`, `[nunit.*]*`, `[Microsoft.Testing.*]*`, `[Microsoft.Testplatform.*]*`, `[Microsoft.VisualStudio.TestPlatform.*]*`) |
@@ -192,6 +193,14 @@ dotnet exec TestProject.dll --coverlet --coverlet-exclude "[.Tests]" --coverlet-
 dotnet exec TestProject.dll --coverlet --coverlet-exclude-by-attribute "Obsolete" --coverlet-exclude-by-attribute "GeneratedCode"
 ```
 
+**Use file prefix to prevent overwrites in multi-project solutions:**
+
+```bash
+dotnet exec TestProject.dll --coverlet --coverlet-file-prefix "MyProject.UnitTests"
+```
+
+This generates files named `MyProject.UnitTests.coverage.json` and `MyProject.UnitTests.coverage.cobertura.xml` instead of overwriting the default `coverage.json` and `coverage.cobertura.xml`.
+
 ## Coverage Output
 
 Coverlet can generate coverage results in multiple formats:

src/coverlet.MTP/Collector/CollectorExtension.cs

@@ -125,6 +125,7 @@ Task ITestHostProcessLifetimeHandler.BeforeTestHostProcessStartAsync(Cancellatio
       _configuration.SingleHit = config.UseSingleHit;
       _configuration.SkipAutoProps = config.SkipAutoProps;
       _configuration.formats = config.GetOutputFormats();
+      _configuration.FilePrefix = config.GetFilePrefix();
       _configuration.UseSourceLink = false;
 
       _logger.LogVerbose($"Test module path: {_testModulePath}");
@@ -403,7 +404,8 @@ internal List<string> GenerateCoverageReportFiles(
     ISourceRootTranslator sourceRootTranslator,
     IFileSystem fileSystem,
     string outputDirectory,
-    string[] formats)
+    string[] formats,
+    string? filePrefix = null)
   {
     var generatedReports = new List<string>();
 
@@ -420,7 +422,9 @@ internal List<string> GenerateCoverageReportFiles(
       }
       else
       {
-        string filename = $"coverage.{reporter.Extension}";
+        string filename = string.IsNullOrEmpty(filePrefix)
+          ? $"coverage.{reporter.Extension}"
+          : $"{filePrefix}.coverage.{reporter.Extension}";
         string reportPath = Path.Combine(outputDirectory, filename);
         fileSystem.WriteAllText(reportPath, reporter.Report(result, sourceRootTranslator));
         generatedReports.Add(reportPath);
@@ -483,7 +487,8 @@ private async Task GenerateReportsAsync(CoverageResult result, CancellationToken
       sourceRootTranslator,
       fileSystem,
       outputDirectory,
-      _configuration.formats);
+      _configuration.formats,
+      _configuration.FilePrefix);
 
     // Display results
     await DisplayGeneratedReportsAsync(generatedReports, cancellation);

src/coverlet.MTP/CommandLine/CoverletCommandLineOptionDefinitions.cs

@@ -19,6 +19,7 @@ public static IReadOnlyCollection<CommandLineOption> GetAllOptions()
     [
       new CommandLineOption(CoverletOptionNames.Coverage, "Enable code coverage data collection.", ArgumentArity.Zero, isHidden: false),
       new CommandLineOption(CoverletOptionNames.Formats, "Output format(s) for coverage report (json, lcov, opencover, cobertura).", ArgumentArity.OneOrMore, isHidden: false),
+      new CommandLineOption(CoverletOptionNames.FilePrefix, "Prefix for coverage report filenames to prevent overwrites when multiple test projects write to the same directory.", ArgumentArity.ExactlyOne, isHidden: false),
       new CommandLineOption(CoverletOptionNames.Include, "Include assemblies matching filters (e.g., [Assembly]Type).", ArgumentArity.OneOrMore, isHidden: false),
       new CommandLineOption(CoverletOptionNames.IncludeDirectory, "Include additional directories for instrumentation.", ArgumentArity.OneOrMore, isHidden: false),
       new CommandLineOption(CoverletOptionNames.Exclude, "Exclude assemblies matching filters (e.g., [Assembly]Type).", ArgumentArity.OneOrMore, isHidden: false),

src/coverlet.MTP/CommandLine/CoverletOptionNames.cs

@@ -7,6 +7,7 @@ internal static class CoverletOptionNames
 {
   public const string Coverage = "coverlet";
   public const string Formats = "coverlet-output-format";
+  public const string FilePrefix = "coverlet-file-prefix";
   public const string Include = "coverlet-include";
   public const string Exclude = "coverlet-exclude";
   public const string ExcludeByFile = "coverlet-exclude-by-file";

src/coverlet.MTP/Configuration/CoverageConfiguration.cs

@@ -161,6 +161,22 @@ public string[] GetDoesNotReturnAttributes()
     return [];
   }
 
+  /// <summary>
+  /// Gets the file prefix for coverage report filenames.
+  /// </summary>
+  public string? GetFilePrefix()
+  {
+    if (_commandLineOptions.TryGetOptionArgumentList(
+      CoverletOptionNames.FilePrefix,
+      out string[]? prefix) && prefix.Length > 0)
+    {
+      LogOptionValue(CoverletOptionNames.FilePrefix, prefix, isExplicit: true);
+      return prefix[0];
+    }
+
+    return null;
+  }
+
   /// <summary>
   /// Gets the test assembly path.
   /// </summary>

src/coverlet.MTP/Configuration/CoverletExtensionConfiguration.cs

@@ -10,6 +10,10 @@ internal class CoverletExtensionConfiguration
 {
   public string[] formats { get; set; } = ["json"];
   /// <summary>
+  /// Optional prefix for coverage report filenames to prevent overwrites.
+  /// </summary>
+  public string? FilePrefix { get; set; }
+  /// <summary>
   /// Test module
   /// </summary>
   public string? TestModule { get; set; }

test/coverlet.MTP.tests/Collector/CollectorExtensionTests.GenerateReports.cs

@@ -297,6 +297,197 @@ public void GenerateCoverageReportFilesWithJsonFormatCreatesJsonReport()
       Times.Once);
   }
 
+  [Fact]
+  public void GenerateCoverageReportFilesWithFilePrefixCreatesReportWithPrefix()
+  {
+    // Arrange
+    var mockFileSystem = new Mock<IFileSystem>();
+    var mockSourceRootTranslator = new Mock<ISourceRootTranslator>();
+    var mockReporterFactory = new Mock<IReporterFactory>();
+    var mockReporter = new Mock<IReporter>();
+
+    // Setup mocks
+    mockReporter.Setup(x => x.OutputType).Returns(ReporterOutputType.File);
+    mockReporter.Setup(x => x.Extension).Returns("json");
+    mockReporter.Setup(x => x.Report(It.IsAny<CoverageResult>(), It.IsAny<ISourceRootTranslator>()))
+      .Returns("{\"coverage\":\"data\"}");
+
+    mockReporterFactory.Setup(x => x.CreateReporter("json")).Returns(mockReporter.Object);
+
+    var collector = CreateCollectorForTesting(fileSystem: mockFileSystem.Object);
+    collector.ReporterFactoryOverride = mockReporterFactory.Object;
+
+    var coverageResult = CreateTestCoverageResult();
+    string outputDirectory = "/fake/reports";
+    string[] formats = ["json"];
+    string filePrefix = "MyProject";
+
+    // Act
+    List<string> generatedReports = collector.GenerateCoverageReportFiles(
+      coverageResult,
+      mockSourceRootTranslator.Object,
+      mockFileSystem.Object,
+      outputDirectory,
+      formats,
+      filePrefix);
+
+    // Assert
+    Assert.Single(generatedReports);
+    Assert.EndsWith("MyProject.coverage.json", generatedReports[0]);
+
+    mockFileSystem.Verify(
+      x => x.WriteAllText(
+        It.Is<string>(path => path.EndsWith("MyProject.coverage.json")),
+        It.Is<string>(content => content.Contains("coverage"))),
+      Times.Once);
+  }
+
+  [Fact]
+  public void GenerateCoverageReportFilesWithNullFilePrefixCreatesReportWithoutPrefix()
+  {
+    // Arrange
+    var mockFileSystem = new Mock<IFileSystem>();
+    var mockSourceRootTranslator = new Mock<ISourceRootTranslator>();
+    var mockReporterFactory = new Mock<IReporterFactory>();
+    var mockReporter = new Mock<IReporter>();
+
+    // Setup mocks
+    mockReporter.Setup(x => x.OutputType).Returns(ReporterOutputType.File);
+    mockReporter.Setup(x => x.Extension).Returns("cobertura.xml");
+    mockReporter.Setup(x => x.Report(It.IsAny<CoverageResult>(), It.IsAny<ISourceRootTranslator>()))
+      .Returns("<coverage />");
+
+    mockReporterFactory.Setup(x => x.CreateReporter("cobertura")).Returns(mockReporter.Object);
+
+    var collector = CreateCollectorForTesting(fileSystem: mockFileSystem.Object);
+    collector.ReporterFactoryOverride = mockReporterFactory.Object;
+
+    var coverageResult = CreateTestCoverageResult();
+    string outputDirectory = "/fake/reports";
+    string[] formats = ["cobertura"];
+
+    // Act
+    List<string> generatedReports = collector.GenerateCoverageReportFiles(
+      coverageResult,
+      mockSourceRootTranslator.Object,
+      mockFileSystem.Object,
+      outputDirectory,
+      formats,
+      filePrefix: null);
+
+    // Assert
+    Assert.Single(generatedReports);
+    Assert.EndsWith("coverage.cobertura.xml", generatedReports[0]);
+
+    mockFileSystem.Verify(
+      x => x.WriteAllText(
+        It.Is<string>(path => path.EndsWith("coverage.cobertura.xml")),
+        It.IsAny<string>()),
+      Times.Once);
+  }
+
+  [Fact]
+  public void GenerateCoverageReportFilesWithEmptyFilePrefixCreatesReportWithoutPrefix()
+  {
+    // Arrange
+    var mockFileSystem = new Mock<IFileSystem>();
+    var mockSourceRootTranslator = new Mock<ISourceRootTranslator>();
+    var mockReporterFactory = new Mock<IReporterFactory>();
+    var mockReporter = new Mock<IReporter>();
+
+    // Setup mocks
+    mockReporter.Setup(x => x.OutputType).Returns(ReporterOutputType.File);
+    mockReporter.Setup(x => x.Extension).Returns("lcov.info");
+    mockReporter.Setup(x => x.Report(It.IsAny<CoverageResult>(), It.IsAny<ISourceRootTranslator>()))
+      .Returns("TN:coverage");
+
+    mockReporterFactory.Setup(x => x.CreateReporter("lcov")).Returns(mockReporter.Object);
+
+    var collector = CreateCollectorForTesting(fileSystem: mockFileSystem.Object);
+    collector.ReporterFactoryOverride = mockReporterFactory.Object;
+
+    var coverageResult = CreateTestCoverageResult();
+    string outputDirectory = "/fake/reports";
+    string[] formats = ["lcov"];
+
+    // Act
+    List<string> generatedReports = collector.GenerateCoverageReportFiles(
+      coverageResult,
+      mockSourceRootTranslator.Object,
+      mockFileSystem.Object,
+      outputDirectory,
+      formats,
+      filePrefix: "");
+
+    // Assert
+    Assert.Single(generatedReports);
+    Assert.EndsWith("coverage.lcov.info", generatedReports[0]);
+
+    mockFileSystem.Verify(
+      x => x.WriteAllText(
+        It.Is<string>(path => path.EndsWith("coverage.lcov.info")),
+        It.IsAny<string>()),
+      Times.Once);
+  }
+
+  [Fact]
+  public void GenerateCoverageReportFilesWithFilePrefixAndMultipleFormatsCreatesAllReportsWithPrefix()
+  {
+    // Arrange
+    var mockFileSystem = new Mock<IFileSystem>();
+    var mockSourceRootTranslator = new Mock<ISourceRootTranslator>();
+    var mockReporterFactory = new Mock<IReporterFactory>();
+
+    var mockJsonReporter = new Mock<IReporter>();
+    mockJsonReporter.Setup(x => x.OutputType).Returns(ReporterOutputType.File);
+    mockJsonReporter.Setup(x => x.Extension).Returns("json");
+    mockJsonReporter.Setup(x => x.Report(It.IsAny<CoverageResult>(), It.IsAny<ISourceRootTranslator>()))
+      .Returns("{\"coverage\":\"data\"}");
+
+    var mockCoberturaReporter = new Mock<IReporter>();
+    mockCoberturaReporter.Setup(x => x.OutputType).Returns(ReporterOutputType.File);
+    mockCoberturaReporter.Setup(x => x.Extension).Returns("cobertura.xml");
+    mockCoberturaReporter.Setup(x => x.Report(It.IsAny<CoverageResult>(), It.IsAny<ISourceRootTranslator>()))
+      .Returns("<coverage />");
+
+    mockReporterFactory.Setup(x => x.CreateReporter("json")).Returns(mockJsonReporter.Object);
+    mockReporterFactory.Setup(x => x.CreateReporter("cobertura")).Returns(mockCoberturaReporter.Object);
+
+    var collector = CreateCollectorForTesting(fileSystem: mockFileSystem.Object);
+    collector.ReporterFactoryOverride = mockReporterFactory.Object;
+
+    var coverageResult = CreateTestCoverageResult();
+    string outputDirectory = "/fake/reports";
+    string[] formats = ["json", "cobertura"];
+    string filePrefix = "UnitTests";
+
+    // Act
+    List<string> generatedReports = collector.GenerateCoverageReportFiles(
+      coverageResult,
+      mockSourceRootTranslator.Object,
+      mockFileSystem.Object,
+      outputDirectory,
+      formats,
+      filePrefix);
+
+    // Assert
+    Assert.Equal(2, generatedReports.Count);
+    Assert.Contains(generatedReports, r => r.EndsWith("UnitTests.coverage.json"));
+    Assert.Contains(generatedReports, r => r.EndsWith("UnitTests.coverage.cobertura.xml"));
+
+    mockFileSystem.Verify(
+      x => x.WriteAllText(
+        It.Is<string>(path => path.EndsWith("UnitTests.coverage.json")),
+        It.IsAny<string>()),
+      Times.Once);
+
+    mockFileSystem.Verify(
+      x => x.WriteAllText(
+        It.Is<string>(path => path.EndsWith("UnitTests.coverage.cobertura.xml")),
+        It.IsAny<string>()),
+      Times.Once);
+  }
+
   /// <summary>
   /// Creates a CollectorExtension instance for testing with minimal setup.
   /// </summary>

test/coverlet.MTP.tests/CommandLine/CoverletMTPCommandLineTests.cs

@@ -82,6 +82,17 @@ public async Task IsValidForFlagOptions(string optionName)
     Assert.True(string.IsNullOrEmpty(result.ErrorMessage));
   }
 
+  [Fact]
+  public async Task IsValidForFilePrefixWithValue()
+  {
+    CommandLineOption option = _provider.GetCommandLineOptions().First(x => x.Name == CoverletOptionNames.FilePrefix);
+
+    var result = await _provider.ValidateOptionArgumentsAsync(option, ["MyProject"]);
+
+    Assert.True(result.IsValid);
+    Assert.True(string.IsNullOrEmpty(result.ErrorMessage));
+  }
+
   [Fact]
   public void GetCommandLineOptionsReturnsAllExpectedOptions()
   {
@@ -91,6 +102,7 @@ public void GetCommandLineOptionsReturnsAllExpectedOptions()
     {
         CoverletOptionNames.Coverage,
         CoverletOptionNames.Formats,
+        CoverletOptionNames.FilePrefix,
         CoverletOptionNames.Include,
         CoverletOptionNames.IncludeDirectory,
         CoverletOptionNames.Exclude,