Implements SkipTestException

Fixes #522

kotlintest-core/src/main/kotlin/io/kotlintest/TestCase.kt

@@ -91,4 +91,20 @@ fun sourceRef(): SourceRef {
   return stack.dropWhile {
     it.className.startsWith("io.kotlintest")
   }[0].run { SourceRef(lineNumber, fileName) }
-}
+}
+
+/**
+ * Exception to mark a test as ignored while it is already running
+ *
+ * The SkipTestException may be thrown inside a test case to skip it (mark it as ignored). Any subclass of this class
+ * may be used, in case you want to use your specific exception.
+ *
+ * ```
+ * class FooTest : StringSpec({
+ *    "Ignore this test!" {
+ *        throw SkipTestException("I want to ignore this test!")
+ *    }
+ * })
+ * ```
+ */
+open class SkipTestException(val reason: String? = null): RuntimeException(reason)

kotlintest-runner/kotlintest-runner-jvm/src/main/kotlin/io/kotlintest/runner/jvm/TestCaseExecutor.kt

@@ -191,6 +191,7 @@ class TestCaseExecutor(private val listener: TestEngineListener,
   private fun buildTestResult(error: Throwable?, metadata: Map<String, Any?>): TestResult = when (error) {
     null -> TestResult(TestStatus.Success, null, null, metadata)
     is AssertionError -> TestResult(TestStatus.Failure, error, null, metadata)
+    is SkipTestException -> TestResult(TestStatus.Ignored, null, error.reason, metadata)
     else -> TestResult(TestStatus.Error, error, null, metadata)
   }
 

kotlintest-tests/kotlintest-tests-core/src/test/kotlin/com/sksamuel/kotlintest/SkipTestExceptionTest.kt

@@ -0,0 +1,39 @@
+package com.sksamuel.kotlintest
+
+import com.nhaarman.mockito_kotlin.argThat
+import com.nhaarman.mockito_kotlin.mock
+import com.nhaarman.mockito_kotlin.then
+import io.kotlintest.*
+import io.kotlintest.runner.jvm.TestCaseExecutor
+import io.kotlintest.runner.jvm.TestEngineListener
+import io.kotlintest.specs.FreeSpec
+import io.kotlintest.specs.FunSpec
+import kotlinx.coroutines.GlobalScope
+import java.util.concurrent.Executors
+
+class SkipTestExceptionTest : FunSpec() {
+
+  private val scheduler = Executors.newScheduledThreadPool(1)
+
+  init {
+    test("A test that throws SkipTestException should have Ignored as a result") {
+
+      val listenerExecutor = Executors.newSingleThreadExecutor()
+      val listener = mock<TestEngineListener> {}
+      val executor = TestCaseExecutor(listener, listenerExecutor, scheduler)
+
+      val testCase = TestCase.test(Description.spec("wibble"), object : FreeSpec() {}) {
+        throw SkipTestException("Foo")
+      }
+
+      val context = object : TestContext(GlobalScope.coroutineContext) {
+        override suspend fun registerTestCase(testCase: TestCase) {}
+        override fun description(): Description = Description.spec("wibble")
+      }
+      executor.execute(testCase, context)
+
+      then(listener).should().exitTestCase(argThat { description == Description.spec("wibble") }, argThat { status == TestStatus.Ignored && reason == "Foo" })
+
+    }
+  }
+}