Duct (#595)

Added duct module - a utility for serving execution reports on your local system

Author: therealryan

README.md

@@ -65,6 +65,7 @@ graph TB
     message-core --> message-web
     message-core --> message-xml
     report-core --> assert-filter
+    report-core --> duct
     report-ng --> report-core
     validation-core --> validation-junit4
     validation-core --> validation-junit5

aggregator/pom.xml

@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.mastercard.test.flow</groupId>
 		<artifactId>parent</artifactId>
-		<version>1.0.1-SNAPSHOT</version>
+		<version>1.1.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>aggregator</artifactId>
 	<packaging>jar</packaging>
@@ -125,6 +125,12 @@
 			<version>${project.version}</version>
 		</dependency>
 
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>duct</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+
 		<dependency>
 			<!-- testing -->
 			<groupId>org.junit.jupiter</groupId>

aggregator/src/test/java/com/mastercard/test/flow/aggregator/SharedConstantTest.java

@@ -1,12 +1,17 @@
 package com.mastercard.test.flow.aggregator;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
+import com.mastercard.test.flow.assrt.AssertionOptions;
 import com.mastercard.test.flow.assrt.Order;
 import com.mastercard.test.flow.builder.Chain;
 import com.mastercard.test.flow.model.LazyModel;
 import com.mastercard.test.flow.report.Writer;
+import com.mastercard.test.flow.report.duct.Duct;
+import com.mastercard.test.flow.util.Option;
 import com.mastercard.test.flow.validation.check.ChainOverlapCheck;
 import com.mastercard.test.flow.validation.check.ReflectiveModelTaggingCheck;
 import com.mastercard.test.flow.validation.check.ResultTagCheck;
@@ -54,4 +59,20 @@ void lazyModelStrings() {
 		Assertions.assertEquals( LazyModel.MODEL_TAGS_FIELD_NAME,
 				ReflectiveModelTaggingCheck.MODEL_TAGS_FIELD_NAME );
 	}
+
+	/**
+	 * The <code>duct</code> module offers {@link Duct#GUI_SUPPRESS}, and we've got
+	 * an alias for that in {@link AssertionOptions#DUCT_GUI_SUPPRESS} so that it
+	 * gets picked up by the documentation automation. However, <code>duct</code> is
+	 * an <i>optional</i> dependency of <code>assert-core</code>, so we can depend
+	 * on it being available when {@link AssertionOptions} is initialised. Hence we
+	 * have to maintain a static copy of the {@link Option} values.
+	 */
+	@Test
+	void ductSuppressionOption() {
+		assertEquals( Duct.GUI_SUPPRESS.property(), AssertionOptions.DUCT_GUI_SUPPRESS.property(),
+				"property name" );
+		assertEquals( Duct.GUI_SUPPRESS.description(), AssertionOptions.DUCT_GUI_SUPPRESS.description(),
+				"property description" );
+	}
 }

api/pom.xml

@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.mastercard.test.flow</groupId>
 		<artifactId>parent</artifactId>
-		<version>1.0.1-SNAPSHOT</version>
+		<version>1.1.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>api</artifactId>
 	<packaging>jar</packaging>

api/src/main/java/com/mastercard/test/flow/util/Option.java

@@ -128,6 +128,19 @@ default Stream<String> asList() {
 		return asList( "," );
 	}
 
+	/**
+	 * Builds the commandline argument that would set this {@link Option}'s current
+	 * value in a new JVM
+	 *
+	 * @return The commandline argument, or <code>null</code> if this {@link Option}
+	 *         has no value
+	 */
+	default String commandLineArgument() {
+		return Optional.ofNullable( value() )
+				.map( v -> String.format( "-D%s=%s", property(), v ) )
+				.orElse( null );
+	}
+
 	/**
 	 * Use in try-with-resources blocks where you want an {@link Option} to have a
 	 * specific value and then revert to the previous value when the block ends

api/src/test/java/com/mastercard/test/flow/util/OptionTest.java

@@ -196,4 +196,19 @@ void builder() {
 		Assertions.assertEquals( "property", b.property() );
 		Assertions.assertEquals( "default", b.defaultValue() );
 	}
+
+	/**
+	 * Exercises {@link Option#commandLineArgument()}
+	 */
+	@Test
+	void commandLineArgument() {
+		try( Temporary t = TSTOPT.temporarily( "abc" ) ) {
+			assertEquals( "-Dtstopt=abc", TSTOPT.commandLineArgument() );
+		}
+
+		try( Temporary t = TSTOPT.temporarily( null ) ) {
+			assertEquals( null, TSTOPT.commandLineArgument() );
+		}
+	}
+
 }

assert/assert-core/README.md

@@ -37,6 +37,7 @@ Some aspects of assertion behaviour can be controlled by system properties:
 
 | property | description |
 | -------- | ----------- |
+| `mctf.browse.xdg_open` | Supply true to try and fall back to `xdg-open` when java's desktop integration fails |
 | `mctf.dir` | The path to the dir where assertion artifacts are saved |
 | `mctf.filter.cli.min_width` | The minimum width of the command-line interface |
 | `mctf.filter.exclude` | A comma-separated list of tags values that flows must not have |
@@ -47,9 +48,12 @@ Some aspects of assertion behaviour can be controlled by system properties:
 | `mctf.filter.update` | Supply `true` to update filter values at runtime in the most appropriate interface.Supply `cli` to force use of the command-line interface or `gui` to force use of the graphical interface |
 | `mctf.replay` | The location of a report to replay, or `latest` to replay the most recent local report |
 | `mctf.report.dir` | The path from the artifact directory to the report destination |
+| `mctf.report.serve` | Set to `true` to browse reports on a local web server rather than the filesystem. You must have the optional `duct` module on your classpath. |
 | `mctf.suppress.assertion` | Set to `true` to continue processing a flow in the face of assertion failure |
 | `mctf.suppress.basis` | Set to `true` to process flows whose basis flows have suffered assertion failure |
+| `mctf.suppress.browse` | Supply 'true' to suppress attempts to open browsers |
 | `mctf.suppress.dependency` | Set to `true` to process flows whose dependency flows have suffered errors |
+| `mctf.suppress.duct.gui` | Supply 'true' to suppress the duct gui |
 | `mctf.suppress.filter` | Set to `true` to process all flows regardless of filter configuration |
 | `mctf.suppress.system` | Set to `true` to process when the system under test lacks declared dependencies |
 

assert/assert-core/pom.xml

@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.mastercard.test.flow</groupId>
 		<artifactId>assert</artifactId>
-		<version>1.0.1-SNAPSHOT</version>
+		<version>1.1.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>assert-core</artifactId>
 	<packaging>jar</packaging>
@@ -18,6 +18,16 @@
 			<version>${project.version}</version>
 		</dependency>
 
+		<dependency>
+			<!-- report serving -->
+			<groupId>${project.groupId}</groupId>
+			<artifactId>duct</artifactId>
+			<version>${project.version}</version>
+			<!-- duct is a convenience feature that brings in a load of dependencies, so
+			     we're leaving it up to client projects if they want it or not -->
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>org.junit.jupiter</groupId>
 			<artifactId>junit-jupiter</artifactId>
@@ -57,4 +67,4 @@
 		</plugins>
 	</build>
 
-</project>
+</project>

assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java

@@ -52,6 +52,7 @@
 import com.mastercard.test.flow.report.data.LogEvent;
 import com.mastercard.test.flow.report.data.ResidueData;
 import com.mastercard.test.flow.report.data.TransmissionData;
+import com.mastercard.test.flow.report.duct.Duct;
 import com.mastercard.test.flow.util.Dependencies;
 import com.mastercard.test.flow.util.Flows;
 
@@ -1013,7 +1014,14 @@ private void report( Consumer<Writer> data, boolean error ) {
 
 				// also, if appropriate, open a browser to it
 				if( reporting.shouldOpen( error ) ) {
-					report.browse();
+					if( AssertionOptions.DUCT.isTrue() ) {
+						// if you've traced a ClassNotFoundException or NoClassDefFoundError to here,
+						// then you've forgotten to add the duct module to your dependencies.
+						Duct.serve( report.path() );
+					}
+					else {
+						report.browse();
+					}
 				}
 			}
 		}

assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AssertionOptions.java

@@ -4,6 +4,8 @@
 
 import com.mastercard.test.flow.Flow;
 import com.mastercard.test.flow.assrt.filter.FilterOptions;
+import com.mastercard.test.flow.report.LocalBrowse;
+import com.mastercard.test.flow.report.duct.Duct;
 import com.mastercard.test.flow.util.Option;
 
 /**
@@ -24,6 +26,34 @@ public enum AssertionOptions implements Option {
 	 */
 	ARTIFACT_DIR(FilterOptions.ARTIFACT_DIR),
 
+	/**
+	 * Allows browser launches to be avoided. An alias for
+	 * {@link LocalBrowse#SUPPRESS}
+	 */
+	BROWSE_SUPPRESS(LocalBrowse.SUPPRESS),
+
+	/**
+	 * Allows the option of a browse-opening fallback. An alias for
+	 * {@link LocalBrowse#XDG_OPEN_FALLBACK}
+	 */
+	BROWSE_XDG_OPEN_FALLBACK(LocalBrowse.XDG_OPEN_FALLBACK),
+
+	/**
+	 * Controls whether we use {@link Duct} or not
+	 */
+	DUCT(b -> b.property( "mctf.report.serve" )
+			.description( "Set to `true` to browse reports on a local web"
+					+ " server rather than the filesystem. You must have the"
+					+ " optional `duct` module on your classpath." )),
+
+	/**
+	 * Allows the {@link Duct} gui to be avoided. An alias for
+	 * {@link Duct#GUI_SUPPRESS}
+	 */
+	DUCT_GUI_SUPPRESS(b -> b
+			.property( "mctf.suppress.duct.gui" )
+			.description( "Supply 'true' to suppress the duct gui" )),
+
 	/**
 	 * Controls {@link Replay} parameters
 	 */