Add options to set diff file name qualifiers

README.md

@@ -97,6 +97,21 @@ These methods follow a fluent style, so as, they can be concatenated in a single
 If set to true (soft), some whitespace differences may be hidden from the html output.
 - `setBrightColors(boolean useBrightColors)`: By default differences are highlighted with pale red and green colors,
   if set to true the colors are brighter to easily locate small differences.
+- `setDiffFileQualifier(String value)`: When assertions do not specify a diff file name, adds the indicated string to 
+  the autogenerated diff file name.
+  Use this setting to get unique files when generating consolidated reports
+  from tests that run in different processes 
+  (e.g. when run multiple modules, each in a different GitHub Actions job,
+  set a different qualifier in each module). 
+- `setDiffFileEnvQualifier(String envVariable)`: When assertions do not specify a diff file name, adds the value of the
+  indicated environment variable to the autogenerated diff file name.
+  Use this setting to get unique files when generating consolidated reports
+  from tests that run in different processes and share the same codebase
+  (e.g. when run multiple modules, each in a different GitHub Actions job,
+  set the variable GITHUB_JOB in each module).
+  Note: Jobs that run in a matrix strategy share the same job name.
+  In this case the workflow should define and environment variable 
+  to differentiate each matrix job. 
 - `setUseLocalAbsolutePath(boolean useLocalAbsolutePath)`: If set to true, the link with the differences file will include a file url with the absolute path to the file,
   useful when running tests from a development environment that allows links in the assertion messages (e.g. MS Visual Studio).
 - `setShowExpectedAndActual(boolean showExpectedAndActual)`: If set to true, the assert message will include the whole content of the exepcted and actual strings that are compared.

java/src/main/java/giis/visualassert/AbstractVisualAssert.java

@@ -13,6 +13,8 @@
  */
 public abstract class AbstractVisualAssert<T extends AbstractVisualAssert<T>> {
 	private boolean useLocalAbsolutePath = false;
+	private String diffFileQualifier = "";
+	private String diffFileEnvQualifier = "";
 	private boolean showExpectedAndActual = false;
 	private boolean softDifferences = false;
 	protected boolean normalizeEol = false;
@@ -81,6 +83,42 @@ public T setBrightColors(boolean useBrightColors) {
 		return (T) this;
 	}
 
+	/**
+	 * When assertions do not specify a diff file name, adds the indicated string to 
+	 * the autogenerated diff file name.
+	 * Use this setting to get unique files when generating consolidated reports
+	 * from tests that run in different processes 
+	 * (e.g. when run multiple modules, each in a different GitHub Actions job,
+	 * set a different qualifier in each module).
+	 * @param diffFileQualifier the value to add to the diff file name (must contain valid characters)
+	 * @return this object to allow fluent style
+	 */
+	@SuppressWarnings("unchecked")
+	public T setDiffFileQualifier(String diffFileQualifier) {
+		this.diffFileQualifier = diffFileQualifier;
+		return (T) this;
+	}
+
+	/**
+	 * When assertions do not specify a diff file name, adds the value of the
+	 * indicated environment variable to the autogenerated diff file name.
+	 * Use this setting to get unique files when generating consolidated reports
+	 * from tests that run in different processes and share the same codebase
+	 * (e.g. when run multiple modules, each in a different GitHub Actions job,
+	 * set the variable GITHUB_JOB in each module).
+	 * Note: Jobs that run in a matrix strategy share the same job name.
+	 * In this case the workflow should define and environment variable 
+	 * to differentiate each matrix job. 
+	 * @param envVariable the name of the environment variable whose value is added
+	 *   to the diff file name (the value must contain valid characters)
+	 * @return this object to allow fluent style
+	 */
+	@SuppressWarnings("unchecked")
+	public T setDiffFileEnvQualifier(String envVariable) {
+		this.diffFileEnvQualifier = envVariable;
+		return (T) this;
+	}
+
 	/**
 	 * If set to true, the link with the differences file will include a file url
 	 * with the absolute path to the file; 
@@ -198,11 +236,18 @@ protected String writeDiffFile(String htmlDiffs, String fileName) {
 		FileUtil.createDirectory(reportSubdir);
 		String uniqueFileName = fileName;
 		if (JavaCs.isEmpty(fileName))
-			uniqueFileName = "diff-" + JavaCs.getSequenceAndIncrement() + ".html";
+			uniqueFileName = getUniqueFileName();
 		String uniqueFile = FileUtil.getPath(reportSubdir, uniqueFileName);
 		FileUtil.fileWrite(uniqueFile, htmlDiffs);
 		return uniqueFileName;
 	}
+
+	public String getUniqueFileName() {
+		return "diff-" 
+				+ (JavaCs.isEmpty(this.diffFileQualifier) ? "" : this.diffFileQualifier + "-")
+				+ (JavaCs.isEmpty(this.diffFileEnvQualifier) ? "" : JavaCs.getEnvironmentVariable(this.diffFileEnvQualifier) + "-")
+				+ JavaCs.getSequenceAndIncrement() + ".html";
+	}
 
 	public String getHtmlDiffs(String expected, String actual) {
 		DiffMatchPatch dmp = new DiffMatchPatch();

java/src/main/java/giis/visualassert/portable/JavaCs.java

@@ -26,6 +26,9 @@ public static synchronized int getCurrentSequence() {
 	public static synchronized void clearCurrentSequence() {
 		currentSequenceId=0;
 	}
+	public static String getEnvironmentVariable(String name) {
+		return System.getenv(name); // NOSONAR
+	}
 	public static String getUniqueId() {
 		return UUID.randomUUID().toString();
 	}

java/src/test/java/giis/visualassert/TestVisualAssert.java

@@ -150,6 +150,7 @@ public void testNormalizeLineEndings() {
 
 	@Test
 	public void testAutogeneratedFileSequence() {
+		// Check that the diff files have been actually written
 		String tempReportPath=FileUtil.getPath(defaultFolder, "tmp-"+JavaCs.getUniqueId());
 		FileUtil.createDirectory(tempReportPath);
 		VisualAssert va=new VisualAssert().setReportSubdir(tempReportPath);
@@ -172,4 +173,29 @@ private void runFailSilently(VisualAssert va) {
 		}
 	}
 
+	@Test
+	public void testQualifiedFileNames() {
+		VisualAssert va = new VisualAssert();
+		assertEquals("diff-" + JavaCs.getCurrentSequence() + ".html", va.getUniqueFileName());
+		va = new VisualAssert().setDiffFileQualifier("xxx");
+		assertEquals("diff-xxx-" + JavaCs.getCurrentSequence() + ".html", va.getUniqueFileName());
+
+		// With environment variable, gets a valid variable for linux and windows
+		String variable = "";
+		String value = "";
+		if (!JavaCs.isEmpty(JavaCs.getEnvironmentVariable("USER"))) {
+			variable = "USER";
+			value = JavaCs.getEnvironmentVariable("USER");
+		} else if (!JavaCs.isEmpty(JavaCs.getEnvironmentVariable("USERNAME"))) {
+			variable = "USERNAME";
+			value = JavaCs.getEnvironmentVariable("USERNAME");
+		}
+		va = new VisualAssert().setDiffFileEnvQualifier(variable);
+		assertEquals("diff-" + value + "-" + JavaCs.getCurrentSequence() + ".html", va.getUniqueFileName());
+
+		// qualifiers are additive
+		va = new VisualAssert().setDiffFileQualifier("yyy").setDiffFileEnvQualifier(variable);
+		assertEquals("diff-yyy-" + value + "-" + JavaCs.getCurrentSequence() + ".html", va.getUniqueFileName());
+	}
+
 }

net/VisualAssert/Giis.Visualassert.Portable/JavaCs.N.cs

@@ -41,6 +41,10 @@ public static void ClearCurrentSequence()
                 currentSequenceId = 0;
             }
         }
+        public static string GetEnvironmentVariable(string name)
+        {
+            return Environment.GetEnvironmentVariable(name);
+        }
         public static string GetUniqueId()
         {
             return Guid.NewGuid().ToString();

net/VisualAssert/Giis.Visualassert/AbstractVisualAssert.cs

@@ -18,6 +18,10 @@ public abstract class AbstractVisualAssert<T>
 	{
 		private bool useLocalAbsolutePath = false;
 
+		private string diffFileQualifier = string.Empty;
+
+		private string diffFileEnvQualifier = string.Empty;
+
 		private bool showExpectedAndActual = false;
 
 		private bool softDifferences = false;
@@ -92,6 +96,52 @@ public virtual T SetBrightColors(bool useBrightColors)
 			return (T)this;
 		}
 
+		/// <summary>
+		/// When assertions do not specify a diff file name, adds the indicated string to
+		/// the autogenerated diff file name.
+		/// </summary>
+		/// <remarks>
+		/// When assertions do not specify a diff file name, adds the indicated string to
+		/// the autogenerated diff file name.
+		/// Use this setting to get unique files when generating consolidated reports
+		/// from tests that run in different processes
+		/// (e.g. when run multiple modules, each in a different GitHub Actions job,
+		/// set a different qualifier in each module).
+		/// </remarks>
+		/// <param name="diffFileQualifier">the value to add to the diff file name (must contain valid characters)</param>
+		/// <returns>this object to allow fluent style</returns>
+		public virtual T SetDiffFileQualifier(string diffFileQualifier)
+		{
+			this.diffFileQualifier = diffFileQualifier;
+			return (T)this;
+		}
+
+		/// <summary>
+		/// When assertions do not specify a diff file name, adds the value of the
+		/// indicated environment variable to the autogenerated diff file name.
+		/// </summary>
+		/// <remarks>
+		/// When assertions do not specify a diff file name, adds the value of the
+		/// indicated environment variable to the autogenerated diff file name.
+		/// Use this setting to get unique files when generating consolidated reports
+		/// from tests that run in different processes and share the same codebase
+		/// (e.g. when run multiple modules, each in a different GitHub Actions job,
+		/// set the variable GITHUB_JOB in each module).
+		/// Note: Jobs that run in a matrix strategy share the same job name.
+		/// In this case the workflow should define and environment variable
+		/// to differentiate each matrix job.
+		/// </remarks>
+		/// <param name="envVariable">
+		/// the name of the environment variable whose value is added
+		/// to the diff file name (the value must contain valid characters)
+		/// </param>
+		/// <returns>this object to allow fluent style</returns>
+		public virtual T SetDiffFileEnvQualifier(string envVariable)
+		{
+			this.diffFileEnvQualifier = envVariable;
+			return (T)this;
+		}
+
 		/// <summary>
 		/// If set to true, the link with the differences file will include a file url
 		/// with the absolute path to the file;
@@ -226,13 +276,18 @@ protected internal virtual string WriteDiffFile(string htmlDiffs, string fileNam
 			string uniqueFileName = fileName;
 			if (JavaCs.IsEmpty(fileName))
 			{
-				uniqueFileName = "diff-" + JavaCs.GetSequenceAndIncrement() + ".html";
+				uniqueFileName = GetUniqueFileName();
 			}
 			string uniqueFile = FileUtil.GetPath(reportSubdir, uniqueFileName);
 			FileUtil.FileWrite(uniqueFile, htmlDiffs);
 			return uniqueFileName;
 		}
 
+		public virtual string GetUniqueFileName()
+		{
+			return "diff-" + (JavaCs.IsEmpty(this.diffFileQualifier) ? string.Empty : this.diffFileQualifier + "-") + (JavaCs.IsEmpty(this.diffFileEnvQualifier) ? string.Empty : JavaCs.GetEnvironmentVariable(this.diffFileEnvQualifier) + "-") + JavaCs.GetSequenceAndIncrement() + ".html";
+		}
+
 		public virtual string GetHtmlDiffs(string expected, string actual)
 		{
 			DiffMatchPatch.diff_match_patch dmp = new DiffMatchPatch.diff_match_patch();