Merge pull request #9 from jaa127/master

Better Examples and changes for testing: 0.6.0

.gitignore

@@ -5,3 +5,4 @@
 /.idea/
 *.swp
 *~
+*.sc

CHANGELOG.md

@@ -10,14 +10,6 @@ Latest releases (for scala 2.12) are:
  * utils-fs: 0.8.0
  * utils-testing: 0.5.1
 
-Release artifacts are published on the maven Central Repository.
-
-Library configuration for sbt:
-
-    libraryDependencies += "fi.sn127" %% "utils-fs" % "0.8.0"
-    libraryDependencies += "fi.sn127" %% "utils-testing" % "0.5.1"
-
-
 #### fs:0.8.0, testing:0.5.1
 
  - fs:

README.md

@@ -2,20 +2,41 @@
 [![Build Status](https://travis-ci.org/sn127/utils.svg?branch=master)](https://travis-ci.org/sn127/utils)
 [![Coverage Status](https://coveralls.io/repos/github/sn127/utils/badge.svg?branch=master)](https://coveralls.io/github/sn127/utils?branch=master)
 
-# Utils
+ * utils-fs: [![Maven Central](https://maven-badges.herokuapp.com/maven-central/fi.sn127/utils-fs_2.12/badge.svg?style=plastic)](https://maven-badges.herokuapp.com/maven-central/fi.sn127/utils-fs_2.12)
+ * utils-testing: [![Maven Central](https://maven-badges.herokuapp.com/maven-central/fi.sn127/utils-testing_2.12/badge.svg?style=plastic)](https://maven-badges.herokuapp.com/maven-central/fi.sn127/utils-testing_2.12)
+
+# Utils (DirSuite add-on to ScalaTest)
 
  * utils-fs
    - java.nio.{Files,Paths} path manipulating utilities
-   - Recursive findFiles with glob and regex pattern
+   - Recursive findFiles with glob and regex pattern matching
  * utils-testing
-   - Scalatest-like `DirSuite` to run collection of tests with
-     predefined input and output references on filesystem.
+   - DirSuite add-on to ScalaTest. DirSuite can run (huge) collection of tests
+     which are defined on filesystem. Arguments, inputs and expected reference output
+     files are defined by test directory.
 
 
 ## Documentation
 
  * [docs/dirsuite.md](./docs/dirsuite.md) has some general information about dirsuite
  * [docs/howto.md](./docs/howto.md) has examples against dirsuite's own tests
+ * Example test setup with DirSuite:
+   * [example-tests](./examples/tests/)
+   * [example-DirSuite](./examples/src/test/scala/DirSuiteDemo.scala)
+
+
+## Releases
+
+Release artifacts are published on the maven 
+[Central Repository](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22fi.sn127%22).
+
+Library configuration for sbt:
+
+    libraryDependencies += "fi.sn127" %% "utils-fs" % "0.8.0"
+    libraryDependencies += "fi.sn127" %% "utils-testing" % "0.5.1"
+
+For release information and version history details, see [CHANGELOG](./CHANGELOG.md).
+
 
 ## Contributing to Utils
 
@@ -38,7 +59,7 @@ so they don't have be global settings in your system.
 Please make sure that you sign-off all your PR's commits. 
 
 
-## Thanks
+## Credits
 
 See [THANKS](./THANKS.md) for full list of credits. Most notably 
 this started as a test tool for [Abandon](https://github.com/hrj/abandon) 

build.sbt

@@ -44,8 +44,8 @@ lazy val testing = (project in file("testing")).
   settings(commonSettings: _*).
   settings(
     name := "utils-testing",
-    version := "0.5.1",
-    isSnapshot := false,
+    version := "0.6.0-pre",
+    isSnapshot := true,
     fork in run := true,
     libraryDependencies += scalaArm,
     libraryDependencies += scalatest

docs/dirsuite.md

@@ -1,6 +1,39 @@
 # DirSuite
 
-See: [DirSuiteDemo](../testing/src/test/scala/fi/sn127/utils/testing/DirSuiteDemo.scala)
+DirSuite is an add-on to ScalaTest, and it makes  possible to run and test 
+corpus of tests which are defined in as files on directory tree.
+
+Test interface is simple, your testFunction takes as an input 
+an array of strings.  Return values, exceptions etc. you can define
+normally by using ScalaTest's assertions. 
+
+It is possible to run multiple execution steps per one test case, 
+e.g. for testing git session, one test could be: 
+
+`init`, `add file.txt`, `commit -m "msg"`
+
+if test function is git's main method.
+
+DirSuite also supports automatic validation of potential output.
+Currently supported formats are txt and xml-output.
+
+
+### Examples
+
+Under examples are three demo DirSuites, which demonstrates 
+different aspects of DirSuite:
+
+ * [DemoApp](../examples/src/main/scala/DemoApp.scala) which is used in tests
+
+ * [Test corpus](../examples/tests/) contains test inputs
+
+ * [DirSuiteDemo](../examples/src/test/scala/DirSuiteDemo.scala)
+   Normal usage of DirSuite
+
+ * [MapArgsDemo](../examples/src/test/scala/MapArgsDemo.scala)
+   Howto map and change test's arguments (e.g. to provide conf file)
+
+ * [FailureDemo](../examples/src/test/scala/FailureDemo.scala)
+   Ignored tests which all will fail, and provide example output of failurecases.
 
-TODO 
 

docs/howto.md

@@ -1,3 +1,15 @@
 # How to use DirSuite
 
-See: [DirSuiteDemo](../testing/src/test/scala/fi/sn127/utils/testing/DirSuiteDemo.scala)
+Under examples are three demo DirSuites, which demonstrates 
+different aspects of DirSuite:
+
+ * [DirSuiteDemo](../examples/src/test/scala/DirSuiteDemo.scala)
+   Normal usage of DirSuite
+
+ * [MapArgsDemo](../examples/src/test/scala/MapArgsDemo.scala)
+   Howto map and change test's arguments (e.g. to provide conf file)
+
+ * [FailureDemo](../examples/src/test/scala/FailureDemo.scala)
+   Ignored tests which all will fail, and provide example output of failurecases.
+
+

examples/.gitignore

@@ -0,0 +1,7 @@
+/**/lib_managed/
+/**/src_managed/
+/**/target/
+/tests/**/out.*
+/.idea/
+*.swp
+*~

examples/build.sbt

@@ -0,0 +1,7 @@
+
+name := "DirSuiteExample"
+
+scalaVersion := "2.12.1"
+
+libraryDependencies += "fi.sn127" %% "utils-testing" % "0.6.0-pre" % "test"
+libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.1" % "test"

examples/project/build.properties

@@ -0,0 +1 @@
+sbt.version=0.13.13

examples/src/main/scala/DemoApp.scala

@@ -0,0 +1,62 @@
+import java.nio.charset.StandardCharsets
+import java.nio.file.{Files, Path, Paths}
+
+object DemoApp {
+  //
+  val SUCCESS = 127
+  val FAILURE = 255
+}
+
+class DemoApp(val testdir: Path) {
+
+  def doSuccess(args: Array[String]): Int = {
+    DemoApp.SUCCESS
+  }
+
+  def doFailure(args: Array[String]): Int = {
+    DemoApp.FAILURE
+  }
+
+  def doFlaky(args: Array[String]): Int = {
+    if (args(0) == "bang") {
+      throw new RuntimeException("BANG!")
+    }
+    else if (args(0) == "fail") {
+      DemoApp.FAILURE
+    } else {
+      DemoApp.SUCCESS
+    }
+  }
+
+  def doArgsCount(args: Array[String]): Int = {
+    args.length
+  }
+
+  def doTxt(args: Array[String]): Int = {
+    val output = Paths.get(testdir.toString, args(0))
+    Files.write(output, args
+      .mkString("hello\n", "\n", "\nworld\n")
+      .getBytes(StandardCharsets.UTF_8))
+    DemoApp.SUCCESS
+  }
+
+  def doXml(args: Array[String]): Int = {
+    val output = Paths.get(testdir.toString, args(0))
+    Files.write(output, args
+      .mkString("<hello><arg>", "</arg><arg>", "</arg></hello>\n")
+      .getBytes(StandardCharsets.UTF_8))
+    DemoApp.SUCCESS
+  }
+
+  def doTxtXml(args: Array[String]): Int = {
+    val result =
+      if (args(1) == "txt") {
+        doTxt(args)
+      } else if (args(1) == "xml") {
+        doXml(args)
+      } else {
+        DemoApp.FAILURE
+      }
+    result
+  }
+}

examples/src/test/scala/DirSuiteDemo.scala

@@ -0,0 +1,156 @@
+
+import java.nio.file.Paths
+
+import fi.sn127.utils.fs.{Glob, Regex}
+import fi.sn127.utils.testing.DirSuite
+
+class DirSuiteDemo extends DirSuite {
+
+  val testdir = Paths.get("tests").toAbsolutePath.normalize
+  val app = new DemoApp(testdir)
+
+  /**
+   * Find all noargs-tests and execute them.
+   *
+   * Assert that App (doArgsCount) return correct arg count (0)
+   *
+   * Search method: Glob
+   * https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob
+   */
+  runDirSuite(testdir, Glob("success/noargs[0-9]*.exec")) { args: Array[String] =>
+    assertResult(0) {
+      app.doArgsCount(args)
+    }
+  }
+
+  /**
+   * Find all args3 and execute them.
+   *
+   * Assert that App (doArgsCount) return correct arg count (3)
+   *
+   * Search method: Glob
+   * https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob
+   */
+  runDirSuite(testdir, Glob("success/args3-[0-9]*.exec")) { args: Array[String] =>
+    assertResult(3) {
+      app.doArgsCount(args)
+    }
+  }
+
+  /**
+   * Find all txt-output tests and execute them.
+   *
+   * Assert that doTxt was successful and check
+   * output based on reference vectors.
+   *
+   * Search method: Regex
+   * https://docs.oracle.com/javase/tutorial/essential/regex/index.html
+   */
+  runDirSuite(testdir, Regex("success/txt[0-9]+\\.exec")) { args: Array[String] =>
+    assertResult(DemoApp.SUCCESS) {
+      app.doTxt(args)
+    }
+  }
+
+  /**
+   * Find all xml-output tests and execute them.
+   *
+   * Assert that doXml was successful and check
+   * output based on reference vectors.
+   *
+   * Search method: Regex
+   * https://docs.oracle.com/javase/tutorial/essential/regex/index.html
+   */
+  runDirSuite(testdir, Regex("success/xml[0-9]+\\.exec")) { args: Array[String] =>
+    assertResult(DemoApp.SUCCESS) {
+      app.doXml(args)
+    }
+  }
+
+  /**
+   * Find all mixed output tests and execute them.
+   * Use XML Validator for XML-files, and TXT Validator
+   * for txt-files. This choice is done by
+   * DirSuite::selectValidator, which can be overloaded
+   * test-by-test class basis.
+   *
+   * Assert that doTxtXml was successful and check
+   * output based on reference vectors.
+   *
+   * Search method: Glob
+   * https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob
+   */
+  runDirSuite(testdir, Glob("success/mixed[0-9]*.exec")) { args: Array[String] =>
+    assertResult(DemoApp.SUCCESS) {
+      app.doTxtXml(args)
+    }
+  }
+
+  /**
+   * Test that an exception is thrown.
+   *
+   * This is internal assertThrows/intercept, so every execution step
+   * must throw an exception if multiple steps are run.
+   */
+  runDirSuite(testdir, Glob("success/singleStepEx[0-9]*.exec")) { args: Array[String] =>
+    assertThrows[RuntimeException]{
+      app.doFlaky(args)
+    }
+  }
+
+  /**
+   * First execution steps must succeed, and then
+   * Last execution step  must throw up an exception
+   * when multiple steps are run
+   *
+   * For example:
+   *  exec 0 => assertResult(SUCCESS)
+   *  exec 1 => assertResult(SUCCESS)
+   *  exec 2 => assertThrows[RuntimeException]
+   */
+  runMultiTestDirSuite(testdir, Glob("success/multiStepEx[0-9]*.exec"))(
+    { args: Array[String] =>
+      /*
+       * All steps at the begin must succeed
+       */
+      assertResult(DemoApp.SUCCESS) {
+        app.doFlaky(args)
+      }
+    },
+    { args: Array[String] =>
+      /*
+       * Last step must fail with exception
+       */
+      assertThrows[RuntimeException] {
+        app.doFlaky(args)
+      }
+    }
+  )
+  /**
+   * First execution steps must succeed, and then
+   * Last execution step  must fail
+   *
+   * For example:
+   *  exec 0 => assertResult(SUCCESS)
+   *  exec 1 => assertResult(SUCCESS)
+   *  exec 2 => assertResult(FAILURE)
+   */
+  runMultiTestDirSuite(testdir, Glob("success/multiStepFail[0-9]*.exec"))(
+    { args: Array[String] =>
+      /*
+       * All steps at the begin must succeed
+       */
+      assertResult(DemoApp.SUCCESS) {
+        app.doFlaky(args)
+      }
+    },
+    { args: Array[String] =>
+      /*
+       * Last step must fail
+       */
+      assertResult(DemoApp.FAILURE) {
+        app.doFlaky(args)
+      }
+    }
+  )
+}