Filled out usage documentation (#198)

* Filled out usage documentation

* tweak

* format

* simplify!

* killed mutant

assert/assert-junit5/README.md

@@ -22,7 +22,7 @@ It provides the `Flocessor` class, which should be used as a generator for a [dy
 <dependency>
   <!-- system assertion -->
   <groupId>com.mastercard.test.flow</groupId>
-  <artifactId>assert-junit4</artifactId>
+  <artifactId>assert-junit5</artifactId>
   <version>${flow.version}</version>
   <scope>test</scope>
 </dependency>

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

@@ -0,0 +1,110 @@
+package com.mastercard.test.flow.doc;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static java.util.stream.Collectors.joining;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.DynamicTest.dynamicTest;
+
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.TreeSet;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+
+import org.junit.jupiter.api.DynamicNode;
+import org.junit.jupiter.api.TestFactory;
+
+import com.mastercard.test.flow.report.QuietFiles;
+
+/**
+ * Checks that the documented maven dependency declarations are accurate
+ */
+@SuppressWarnings("static-method")
+class DependencyTest {
+
+	private static Pattern DEP = Pattern.compile( "<dependency>(.*)</dependency>", Pattern.DOTALL );
+	private static Pattern GRP = Pattern.compile( "<groupId>(.*)</groupId>" );
+	private static Pattern RTF = Pattern.compile( "<artifactId>(.*)</artifactId>" );
+	private static Pattern VRS = Pattern.compile( "<version>(.*)</version>" );
+
+	/**
+	 * Checks that all of the suggested dependency declarations in the readmes
+	 * accurately target an artifact from this project
+	 *
+	 * @return per-markdown-file tests
+	 */
+	@TestFactory
+	Stream<DynamicNode> markdown() {
+		PomData root = new PomData( null, Paths.get( "../pom.xml" ) );
+		Set<String> allowed = new TreeSet<>();
+		Map<Path, PomData> dirPoms = new TreeMap<>();
+		root.visit( pd -> {
+			allowed.add( pd.groupId() + ":" + pd.artifactId() );
+			dirPoms.put( pd.dirPath(), pd );
+		} );
+		String allowedString = allowed.stream().collect( joining( "\n  " ) );
+
+		Set<String> used = new TreeSet<>();
+
+		return Stream.concat(
+				Util.markdownFiles()
+						.map( path -> dynamicTest( path.toString(), () -> {
+							String content = new String( QuietFiles.readAllBytes( path ), UTF_8 );
+							Matcher depM = DEP.matcher( content );
+							while( depM.find() ) {
+								Matcher grpM = GRP.matcher( depM.group( 1 ) );
+								assertTrue( grpM.find(), "groupId found in " + depM.group( 0 ) );
+
+								Matcher rtfM = RTF.matcher( depM.group( 1 ) );
+								assertTrue( rtfM.find(), "artifactId found in " + depM.group( 0 ) );
+
+								Matcher vrsM = VRS.matcher( depM.group( 1 ) );
+								assertTrue( vrsM.find(), "version found in " + depM.group( 0 ) );
+								assertEquals( "${flow.version}", vrsM.group( 1 ),
+										"Version element in\n" + depM.group( 0 ) );
+
+								String dep = grpM.group( 1 ) + ":" + rtfM.group( 1 );
+								used.add( dep );
+
+								if( "README.md".equals( path.getFileName().toString() ) ) {
+									PomData pom = dirPoms.get( path.getParent() );
+									assertNotNull( pom, "pom associated with readme" );
+									assertEquals(
+											pom.groupId() + ":" + pom.artifactId(),
+											dep,
+											String.format(
+													"Documented dependency%n%s%nmatches associated pom",
+													depM.group() ) );
+								}
+
+								assertTrue( allowed.contains( dep ),
+										String.format(
+												"Dependency '%s' taken from dependency%n%s%nfound in allowed set:%n%s",
+												dep, depM.group(), allowedString ) );
+							}
+						} ) ),
+				Stream.of( dynamicTest( "Documented dependencies", () -> {
+					assertEquals( ""
+							+ "com.mastercard.test.flow:assert-junit4\n"
+							+ "com.mastercard.test.flow:assert-junit5\n"
+							+ "com.mastercard.test.flow:builder\n"
+							+ "com.mastercard.test.flow:message-core\n"
+							+ "com.mastercard.test.flow:message-http\n"
+							+ "com.mastercard.test.flow:message-json\n"
+							+ "com.mastercard.test.flow:message-sql\n"
+							+ "com.mastercard.test.flow:message-text\n"
+							+ "com.mastercard.test.flow:message-web\n"
+							+ "com.mastercard.test.flow:message-xml\n"
+							+ "com.mastercard.test.flow:model\n"
+							+ "com.mastercard.test.flow:validation-junit4\n"
+							+ "com.mastercard.test.flow:validation-junit5",
+							used.stream().collect( joining( "\n" ) ) );
+				} ) ) );
+	}
+}

message/message-core/README.md

@@ -9,4 +9,17 @@ Message implementation utilities
 
  * [../message](..) Implementations of the Message interface
 
-<!-- title end -->
+<!-- title end -->
+
+## Usage
+
+You'll only need to consume this artifact directly if you're implementing your own `Message` type.
+
+```xml
+<dependency>
+  <!-- message implementation utilities -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-core</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```

message/message-http/README.md

@@ -9,4 +9,24 @@ HypterText Transfer Protocol messages
 
  * [../message](..) Implementations of the Message interface
 
-<!-- title end -->
+<!-- title end -->
+
+## Usage
+
+```xml
+<dependency>
+  <!-- http message type -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-http</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
+
+The unit tests [`HttpReqTest`][HttpReqTest] and [`HttpResTest`][HttpResTest] contain usage examples for the message types supplied by this module.
+
+<!-- code_link_start -->
+
+[HttpReqTest]: src/test/java/com/mastercard/test/flow/msg/http/HttpReqTest.java
+[HttpResTest]: src/test/java/com/mastercard/test/flow/msg/http/HttpResTest.java
+
+<!-- code_link_end -->

message/message-json/README.md

@@ -9,4 +9,23 @@ JavaScript Object Notation Messages
 
  * [../message](..) Implementations of the Message interface
 
-<!-- title end -->
+<!-- title end -->
+
+## Usage
+
+```xml
+<dependency>
+  <!-- json message type -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-json</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
+
+The unit test [`JsonTest`][JsonTest] contains usage examples for the message type supplied by this module.
+
+<!-- code_link_start -->
+
+[JsonTest]: src/test/java/com/mastercard/test/flow/msg/json/JsonTest.java
+
+<!-- code_link_end -->

message/message-sql/README.md

@@ -9,4 +9,24 @@ Structured Query Language messages
 
  * [../message](..) Implementations of the Message interface
 
-<!-- title end -->
+<!-- title end -->
+
+## Usage
+
+```xml
+<dependency>
+  <!-- sql message types -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-sql</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
+
+The unit tests [`QueryTest`][sql.QueryTest] and [`ResultTest`][ResultTest] contain usage examples for the message types supplied by this module.
+
+<!-- code_link_start -->
+
+[sql.QueryTest]: src/test/java/com/mastercard/test/flow/msg/sql/QueryTest.java
+[ResultTest]: src/test/java/com/mastercard/test/flow/msg/sql/ResultTest.java
+
+<!-- code_link_end -->

message/message-text/README.md

@@ -9,4 +9,23 @@ Freeform text Message
 
  * [../message](..) Implementations of the Message interface
 
-<!-- title end -->
+<!-- title end -->
+
+## Usage
+
+```xml
+<dependency>
+  <!-- textual message type -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-text</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
+
+The unit test [`TextTest`][TextTest] contains usage examples for the message type supplied by this module.
+
+<!-- code_link_start -->
+
+[TextTest]: src/test/java/com/mastercard/test/flow/msg/txt/TextTest.java
+
+<!-- code_link_end -->

message/message-web/README.md

@@ -11,7 +11,16 @@ Browser interaction messages
 
 <!-- title end -->
 
-## Example usage
+## Usage
+
+```xml
+<dependency>
+  <!-- browser interaction message type -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-web</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
 
 Defining a form submission sequence:
 
@@ -134,4 +143,4 @@ if( assrt.expected().request() instanceof WebSequence
 
 Note how:
  * The actual URL for the page is populated at runtime on a `child()` of the request sequence. This means that the runtime-sourced data will be highlighted in the full diff view of the execution report.
- * We're grabbing the full page source in the extracted results, but we're also masking it as not interesting. This allows users to see the page source in the execution report, but doesn't consign us to slavishly tracking every non-functional change to the HTML in the test suite.
+ * We're grabbing the full page source in the extracted results, but we're also masking it as not interesting. This allows users to see the page source in the execution report, but doesn't condemn us to exhaustively tracking every non-functional change to the HTML in the test suite.

message/message-xml/README.md

@@ -9,4 +9,23 @@ Extensible Markup Language Messages
 
  * [../message](..) Implementations of the Message interface
 
-<!-- title end -->
+<!-- title end -->
+
+## Usage
+
+```xml
+<dependency>
+  <!-- xml message type -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>message-xml</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
+
+The unit test [`XMLTest`][XMLTest] contains usage examples for the message type supplied by this module.
+
+<!-- code_link_start -->
+
+[XMLTest]: src/test/java/com/mastercard/test/flow/msg/xml/XMLTest.java
+
+<!-- code_link_end -->

report/report-core/README.md

@@ -11,6 +11,10 @@ Report input/output
 
 <!-- title end -->
 
+## Usage
+
+It is unlikely that you'll need to depend directly on this module, it will be transitively supplied by [`assert-junit4`](../../assert/assert-junit4) or [`assert-junit5`](../../assert/assert-junit5).
+
 ## Functionality
 
 This module provides an object model for the data in an execution report along with facilities for writing and reading that data to and from storage.

report/report-core/src/main/java/com/mastercard/test/flow/report/QuietFiles.java

@@ -129,4 +129,13 @@ public static Stream<String> lines( Path path ) {
 	public static Stream<Path> list( Path dir ) {
 		return wrap( () -> Files.list( dir ) );
 	}
+
+	/**
+	 * @see Files#readAllBytes(Path)
+	 * @param path The path to read
+	 * @return The bytes of the file at that location
+	 */
+	public static byte[] readAllBytes( Path path ) {
+		return wrap( () -> Files.readAllBytes( path ) );
+	}
 }

report/report-core/src/test/java/com/mastercard/test/flow/report/QuietFilesTest.java

@@ -141,15 +141,18 @@ void deleteDir() throws Exception {
 	}
 
 	/**
-	 * File writing
+	 * File writing and reading
 	 *
 	 * @throws Exception if pre-emptive cleanup fails
 	 */
 	@Test
-	void write() throws Exception {
+	void writeRead() throws Exception {
 		Path f = Paths.get( "target/write" );
 		Files.deleteIfExists( f );
 		Path r = QuietFiles.write( f, "hello!".getBytes( UTF_8 ) );
 		assertEquals( f, r );
+
+		assertEquals( "hello!", new String( QuietFiles.readAllBytes( f ), UTF_8 ) );
 	}
+
 }

validation/validation-junit4/README.md

@@ -10,3 +10,41 @@ Junit4 validation components
  * [../validation](..) Checking model consistency
 
 <!-- title end -->
+
+## Usage
+
+```xml
+
+<dependency>
+  <!-- message implementation utilities -->
+  <groupId>com.mastercard.test.flow</groupId>
+  <artifactId>validation-junit4</artifactId>
+  <version>${flow.version}</version>
+</dependency>
+```
+
+The `Validator` implementation provided by this module can used in a [parameterised test](https://junit.org/junit4/javadoc/4.12/org/junit/runners/Parameterized.html):
+
+```java
+@RunWith(Parameterized.class)
+public class MyTest {
+	@Parameters(name = "{0}")
+	public static Collection<Object[]> flows() {
+		return new Validator()
+				.checking( MY_SYSTEM_MODEL )
+				.with( AbstractValidator.defaultChecks() )
+				.parameters();
+	}
+
+	@Parameter(0)
+	public String name;
+
+	@Parameter(1)
+	public Runnable check;
+
+	@Test
+	public void test() {
+		check.run();
+	}
+}
+```