Duct (#595)

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

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
 	 */

assert/assert-filter/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-filter</artifactId>
 	<packaging>jar</packaging>

assert/assert-junit4/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-junit4</artifactId>
 	<packaging>jar</packaging>

assert/assert-junit5/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-junit5</artifactId>
 	<packaging>jar</packaging>

assert/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>assert</artifactId>
 	<packaging>pom</packaging>

bom/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>bom</artifactId>
 	<packaging>pom</packaging>

builder/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>builder</artifactId>
 	<packaging>jar</packaging>

doc/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>doc</artifactId>
 	<packaging>jar</packaging>

doc/src/main/markdown/further.md

@@ -15,7 +15,7 @@ The execution report includes tooling to aid in change review. If the reports ge
 
 <!-- code_link_start -->
 
-[AbstractFlocessor.reporting(Reporting,String...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L194-L203,194-203
+[AbstractFlocessor.reporting(Reporting,String...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L195-L204,195-204
 [Reporting]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/Reporting.java
 
 <!-- code_link_end -->
@@ -80,8 +80,8 @@ Note that only the tag/index-based filtering can be used to avoid flow construct
 
 <!-- code_link_start -->
 
-[AbstractFlocessor.filtering(Consumer)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L315-L323,315-323
-[AbstractFlocessor.exercising(Predicate,Consumer)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L328-L353,328-353
+[AbstractFlocessor.filtering(Consumer)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L316-L324,316-324
+[AbstractFlocessor.exercising(Predicate,Consumer)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L329-L354,329-354
 
 <!-- code_link_end -->
 
@@ -125,7 +125,7 @@ Note that the assertion components will not make any assumptions about the forma
 [LogCapture]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/LogCapture.java
 [Tail]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/log/Tail.java
 [Merge]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/log/Merge.java
-[AbstractFlocessor.logs(LogCapture)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L283-L290,283-290
+[AbstractFlocessor.logs(LogCapture)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L284-L291,284-291
 
 <!-- code_link_end -->
 
@@ -248,7 +248,7 @@ Consider the following worked example:
 
 [flow.Unpredictable]: ../../../../api/src/main/java/com/mastercard/test/flow/Unpredictable.java
 [AbstractMessage.masking(Unpredictable,UnaryOperator)]: ../../../../message/message-core/src/main/java/com/mastercard/test/flow/msg/AbstractMessage.java#L50-L57,50-57
-[AbstractFlocessor.masking(Unpredictable...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L211-L218,211-218
+[AbstractFlocessor.masking(Unpredictable...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L212-L219,212-219
 [mask.BenSys]: ../../test/java/com/mastercard/test/flow/doc/mask/BenSys.java
 [mask.DieSys]: ../../test/java/com/mastercard/test/flow/doc/mask/DieSys.java
 [mask.Unpredictables]: ../../test/java/com/mastercard/test/flow/doc/mask/Unpredictables.java
@@ -258,7 +258,7 @@ Consider the following worked example:
 [msg.Mask.andThen(Consumer)]: ../../../../message/message-core/src/main/java/com/mastercard/test/flow/msg/Mask.java#L290-L292,290-292
 [BenDiceTest?masking]: ../../test/java/com/mastercard/test/flow/doc/mask/BenDiceTest.java#L31,31
 [BenTest]: ../../test/java/com/mastercard/test/flow/doc/mask/BenTest.java
-[AbstractFlocessor.masking(Unpredictable...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L211-L218,211-218
+[AbstractFlocessor.masking(Unpredictable...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L212-L219,212-219
 
 <!-- code_link_end -->
 
@@ -278,7 +278,7 @@ You can see usage of these types in the example system:
 [flow.Context]: ../../../../api/src/main/java/com/mastercard/test/flow/Context.java
 [Builder.context(Context)]: ../../../../builder/src/main/java/com/mastercard/test/flow/builder/Builder.java#L225-L232,225-232
 [assrt.Applicator]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/Applicator.java
-[AbstractFlocessor.applicators(Applicator...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L257-L263,257-263
+[AbstractFlocessor.applicators(Applicator...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L258-L264,258-264
 [model.ctx.QueueProcessing]: ../../../../example/app-model/src/main/java/com/mastercard/test/flow/example/app/model/ctx/QueueProcessing.java
 [QueueProcessingApplicator]: ../../../../example/app-assert/src/main/java/com/mastercard/test/flow/example/app/assrt/ctx/QueueProcessingApplicator.java
 
@@ -301,7 +301,7 @@ You can see usage of these types in the example system:
 
 [flow.Residue]: ../../../../api/src/main/java/com/mastercard/test/flow/Residue.java
 [assrt.Checker]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/Checker.java
-[AbstractFlocessor.checkers(Checker...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L270-L276,270-276
+[AbstractFlocessor.checkers(Checker...)]: ../../../../assert/assert-core/src/main/java/com/mastercard/test/flow/assrt/AbstractFlocessor.java#L271-L277,271-277
 [model.rsd.DBItems]: ../../../../example/app-model/src/main/java/com/mastercard/test/flow/example/app/model/rsd/DBItems.java
 [DBItemsChecker]: ../../../../example/app-assert/src/main/java/com/mastercard/test/flow/example/app/assrt/rsd/DBItemsChecker.java
 

doc/src/test/java/com/mastercard/test/flow/doc/DependencyTest.java

@@ -106,6 +106,7 @@ Stream<DynamicNode> markdown() {
 							+ "com.mastercard.test.flow:assert-junit4\n"
 							+ "com.mastercard.test.flow:assert-junit5\n"
 							+ "com.mastercard.test.flow:builder\n"
+							+ "com.mastercard.test.flow:duct\n"
 							+ "com.mastercard.test.flow:message-core\n"
 							+ "com.mastercard.test.flow:message-http\n"
 							+ "com.mastercard.test.flow:message-json\n"