Add samples for fileAssertions (#944) (#1017)

apis/fluent-en_GB/atrium-api-fluent-en_GB-jvm/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/fileAssertions.kt

@@ -20,6 +20,8 @@ import java.nio.file.Path
  *
  * @return The newly created [Expect] for the transformed subject.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.FileExpectationSamples.asPathFeature
+ *
  * @since 0.9.0
  */
 fun <T : File> Expect<T>.asPath(): Expect<Path> =
@@ -34,6 +36,8 @@ fun <T : File> Expect<T>.asPath(): Expect<Path> =
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.FileExpectationSamples.asPath
+ *
  * @since 0.9.0
  */
 fun <T : File> Expect<T>.asPath(assertionCreator: Expect<Path>.() -> Unit): Expect<T> =

apis/fluent-en_GB/atrium-api-fluent-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/FileExpectationSamples.kt

@@ -0,0 +1,47 @@
+package ch.tutteli.atrium.api.fluent.en_GB.samples
+
+import ch.tutteli.atrium.api.fluent.en_GB.*
+import ch.tutteli.atrium.api.verbs.internal.expect
+import ch.tutteli.niok.newFile
+import java.nio.file.Files
+import kotlin.test.Test
+
+class FileExpectationSamples {
+
+    private val tempDir = Files.createTempDirectory("FileAssertionSamples")
+
+    @Test
+    fun asPathFeature() {
+        val file = tempDir.newFile("target").toFile()
+
+        expect(file)
+          .asPath() // subject is now of type Path
+          .toBeARegularFile()
+
+        fails {
+            expect(file)
+              .asPath()
+              .toBeADirectory()  //fails
+        }
+    }
+
+    @Test
+    fun asPath() {
+        val file = tempDir.newFile("target").toFile()
+
+        expect(file).asPath { // subject within this block is of type Path
+            toBeARegularFile()
+            toStartWith(tempDir)
+        } // subject here is back to type File
+
+        fails {
+            // all assertions are evaluated inside an assertion group block; for more details:
+            // https://github.com/robstoll/atrium#define-single-assertions-or-assertion-groups
+
+            expect(file).asPath {
+                toBeADirectory()        // fails
+                notToStartWith(tempDir) // still evaluated, use `.asPath().` if you want a fail fast behaviour
+            }
+        }
+    }
+}