Release 0.5.2

- Support for InputStream for reading template and environment files
- Renamed Pre- and Post-hooks to PreStepHook and PostStepHook
- revUp with multiple configs

Signed-off-by: Gopal S Akshintala <[email protected]>

Author: overfullstack

README.adoc

@@ -18,7 +18,7 @@ endif::[]
 :pmtemplates: src/integrationTest/resources/pm-templates
 :imagesdir: docs/images
 :prewrap!:
-:revoman-version: 0.5.1
+:revoman-version: 0.5.2
 
 '''
 
@@ -200,9 +200,9 @@ Rundown(
 StepReport(
   step: Step,
   requestInfo: Either<RequestFailure, TxnInfo<Request>>? = null, // <1>
-  preHookFailure: PreHookFailure? = null,
+  preStepHookFailure: PreStepHookFailure? = null,
   responseInfo: Either<ResponseFailure, TxnInfo<Response>>? = null,
-  postHookFailure: PostHookFailure? = null,
+  postStepHookFailure: PostStepHookFailure? = null,
   envSnapshot: PostmanEnvironment<Any?> // <2>
 )
 ----
@@ -304,7 +304,7 @@ assertThat(pqRundown.mutableEnv)
 <7> <<Execution Control>>
 <8> <<#_type_safety_with_flexible_json_pojo_marshallingserialization_and_unmarshallingdeserialization, Request Config>>
 <9> <<#_type_safety_with_flexible_json_pojo_marshallingserialization_and_unmarshallingdeserialization, Response Config>>
-<10> <<#_pre_and_post_hooks>>
+<10> <<#_pre_and_post_step_hooks>>
 <11> <<Response Validations>>
 <12> <<#_type_safety_with_flexible_json_pojo_marshallingserialization_and_unmarshallingdeserialization, Global Custom Type Adapters>>
 <13> Ignore Java cert issues when firing HTTP calls
@@ -327,7 +327,7 @@ include::{integrationtestdir}/com/salesforce/revoman/integration/core/pq/PQE2EWi
 <7> <<Execution Control>>
 <8> <<#_type_safety_with_flexible_json_pojo_marshallingserialization_and_unmarshallingdeserialization, Request Config>>
 <9> <<#_type_safety_with_flexible_json_pojo_marshallingserialization_and_unmarshallingdeserialization, Response Config>>
-<10> <<#_pre_and_post_hooks>>
+<10> <<#_pre_and_post_step_hooks>>
 <11> <<Response Validations>>
 <12> <<#_type_safety_with_flexible_json_pojo_marshallingserialization_and_unmarshallingdeserialization, Global Custom Type Adapters>>
 <13> Ignore Java cert issues when firing HTTP calls
@@ -406,8 +406,8 @@ The configuration offers methods through which the execution strategy can be con
 * `runOnlySteps`, `skipSteps` — All these accept a `predicate` of type `ExeStepPick`, which is invoked passing the current `Step` instance to decide whether to execute or skip a step.
 ** There are some `ExeStepPick` predicates bundled with ReṼoman under `ExeStepPick.PickUtils` e.g `withName`, `inFolder` etc. You can write a custom predicate of your own too.
 
-[#_pre_and_post_hooks]
-=== Pre- and Post-Hooks
+[#_pre_and_post_step_hooks]
+=== Pre- and Post-Step Hooks
 
 A hook lets you fiddle with the execution by plugging in your code before or after a Step execution.
 
@@ -491,7 +491,7 @@ CAUTION: The recommendation is not to add too much code in <<Pre-req and Post-re
 === Mutable Environment
 
 * Environment is the only mutable-shared state across step executions, which can be used for data passing between the consumer and the library.
-* This can be mutated (set key-value pairs) through <<Pre-req and Post-res scripts>> (using `pm.environment.set()`) and <<#_pre_and_post_hooks,Pre-/Post-Hooks>> (using the reference `rundown.mutableEnv`) during execution.
+* This can be mutated (set key-value pairs) through <<Pre-req and Post-res scripts>> (using `pm.environment.set()`) and <<#_pre_and_post_step_hooks,Pre-/Post-Hooks>> (using the reference `rundown.mutableEnv`) during execution.
 
 ==== Read Mutable Environment as Postman Environment JSON format
 
@@ -507,7 +507,8 @@ Each StepReport also has a `pmEnvSnapshot` to assert if a step has executed as e
 
 * You don't have to squash all your steps into one mega collection. Instead, you can break them into easy-to-manage modular collections. `ReVoman.revUp()` accepts a list of collection paths through `templatePaths()`
 * But that doesn't mean you have to execute all these templates in one-go. You can make multiple `ReVoman.revUp()` calls for different collections.
-* If you wish to compose these executions, you can do so by adding the previous execution's `mutableEnv` to the current execution using the `dynamicEnvironment` parameter. This also comes in handy when you wish to execute a common step (e.g. `UserSetup`) inside a Test setup method and use that environment for all the tests.
+* If you wish to compose these executions in a specific order, you can use the `revUp` overload which accepts a vararg `Kick` configs.
+** You can also achieve the same yourself, by adding the previous execution's `mutableEnv` to the current execution using the `dynamicEnvironment` parameter. This also comes in handy when you wish to execute a common step (e.g. `UserSetup`) inside a Test setup method and use that environment for all the tests.
 
 === Custom Dynamic variables
 
@@ -567,13 +568,13 @@ The future looks bright with multiple impactful features in the pipeline:
 
 === How to Debug a step in the middle of an Execution?
 
-* You can add a <<#_pre_and_post_hooks,pre-hook>> to the Step you are interested and add a debug point inside that. This gets hit before ReṼoman fires the request in that Step
+* You can add a <<#_pre_and_post_step_hooks,pre-hook>> to the Step you are interested and add a debug point inside that. This gets hit before ReṼoman fires the request in that Step
 * You can get more adventurous by attaching revoman jar sources and directly adding conditional debug points inside this library source-code. You can search for logs in the source-code that indicate key operations to add conditional debug points with conditions like StepName etc.
 
 === Is there a way to add Metadata to a Postman collection Step?
 
 * You can add key-value pairs to a Step's HTTP Headers section (e.g., `ignoreHTTPStatusUnsuccessful=true`).
-* You can use this information in <<#_step_picks,Step Picks>> or <<#_pre_and_post_hooks>> to identify a particular step to execute any conditional logic
+* You can use this information in <<#_step_picks,Step Picks>> or <<#_pre_and_post_step_hooks>> to identify a particular step to execute any conditional logic
 
 === Do I need to migrate all my existing TestUtils to Postman Collections?
 

buildSrc/src/main/kotlin/Config.kt

@@ -6,6 +6,6 @@
  * ************************************************************************************************
  */
 const val GROUP_ID = "com.salesforce.revoman"
-const val VERSION = "0.5.1"
+const val VERSION = "0.5.2"
 const val ARTIFACT_ID = "revoman"
 const val STAGING_PROFILE_ID = "1ea0a23e61ba7d"

src/integrationTest/java/com/salesforce/revoman/integration/pokemon/PokemonTest.java

@@ -19,8 +19,8 @@
 import static org.mockito.Mockito.times;
 
 import com.salesforce.revoman.ReVoman;
-import com.salesforce.revoman.input.config.HookConfig.Hook.PostHook;
-import com.salesforce.revoman.input.config.HookConfig.Hook.PreHook;
+import com.salesforce.revoman.input.config.HookConfig.StepHook.PostStepHook;
+import com.salesforce.revoman.input.config.HookConfig.StepHook.PreStepHook;
 import com.salesforce.revoman.input.config.Kick;
 import com.salesforce.revoman.output.Rundown;
 import com.salesforce.revoman.output.report.Step;
@@ -54,7 +54,7 @@ void pokemon() {
     //noinspection Convert2Lambda
     final var preLogHook =
         Mockito.spy(
-            new PreHook() {
+            new PreStepHook() {
               @Override
               public void accept(
                   @NotNull Step currentStep,
@@ -66,7 +66,7 @@ public void accept(
     //noinspection Convert2Lambda
     final var postLogHook =
         Mockito.spy(
-            new PostHook() {
+            new PostStepHook() {
               @Override
               public void accept(@NotNull StepReport stepReport, @NotNull Rundown rundown) {
                 LOGGER.info("Picked `postLogHook` after stepName: {}", stepReport.step.displayName);
@@ -75,7 +75,7 @@ public void accept(@NotNull StepReport stepReport, @NotNull Rundown rundown) {
     //noinspection Convert2Lambda
     final var preHook =
         Mockito.spy(
-            new PreHook() {
+            new PreStepHook() {
               @Override
               public void accept(
                   @NotNull Step currentStep,
@@ -87,7 +87,7 @@ public void accept(
     //noinspection Convert2Lambda
     final var postHook =
         Mockito.spy(
-            new PostHook() {
+            new PostStepHook() {
               @Override
               public void accept(@NotNull StepReport ignore2, @NotNull Rundown rundown) {
                 assertThat(rundown.mutableEnv).containsEntry("limit", String.valueOf(newLimit));
@@ -97,7 +97,7 @@ public void accept(@NotNull StepReport ignore2, @NotNull Rundown rundown) {
     //noinspection Convert2Lambda
     final var postHookAfterURIPath =
         Mockito.spy(
-            new PostHook() {
+            new PostStepHook() {
               @Override
               public void accept(@NotNull StepReport stepReport, @NotNull Rundown ignore) {
                 LOGGER.info(

src/main/kotlin/com/salesforce/revoman/ReVoman.kt

@@ -11,7 +11,9 @@ import arrow.core.Either.Left
 import arrow.core.Either.Right
 import arrow.core.flatMap
 import arrow.core.merge
+import com.salesforce.revoman.input.PostExeHook
 import com.salesforce.revoman.input.bufferFileInResources
+import com.salesforce.revoman.input.bufferInputStream
 import com.salesforce.revoman.input.config.Kick
 import com.salesforce.revoman.internal.exe.deepFlattenItems
 import com.salesforce.revoman.internal.exe.executePostResJS
@@ -43,12 +45,20 @@ import org.http4k.core.Request
 import org.http4k.format.ConfigurableMoshi
 
 object ReVoman {
-
   @JvmStatic
   @JvmOverloads
   fun revUp(
-    dynamicEnvironment: Map<String, String> = mapOf<String, String>(),
     vararg kicks: Kick,
+    postExeHook: PostExeHook = PostExeHook { _, _ -> },
+    dynamicEnvironment: Map<String, String> = emptyMap(),
+  ): List<Rundown> = revUp(kicks.toList(), postExeHook, dynamicEnvironment)
+
+  @JvmStatic
+  @JvmOverloads
+  fun revUp(
+    kicks: List<Kick>,
+    postExeHook: PostExeHook = PostExeHook { _, _ -> },
+    dynamicEnvironment: Map<String, String> = emptyMap(),
   ): List<Rundown> =
     kicks
       .fold(dynamicEnvironment to listOf<Rundown>()) { (accumulatedMutableEnv, rundowns), kick ->
@@ -59,19 +69,23 @@ object ReVoman {
               accumulatedMutableEnv,
             )
           )
-        rundown.mutableEnv.mutableEnvCopyWithValuesOfType<String>() to (rundowns + rundown)
+        val accumulatedRundowns = rundowns + rundown
+        postExeHook.accept(rundown, accumulatedRundowns)
+        rundown.mutableEnv.mutableEnvCopyWithValuesOfType<String>() to accumulatedRundowns
       }
       .second
 
   @JvmStatic
   @OptIn(ExperimentalStdlibApi::class)
   fun revUp(kick: Kick): Rundown {
     val pmTemplateAdapter = Moshi.Builder().build().adapter<Template>()
+    val templateBuffers =
+      kick.templatePaths().map { bufferFileInResources(it) } +
+        kick.templateInputStreams().map { bufferInputStream(it) }
     val pmStepsDeepFlattened =
-      kick
-        .templatePaths()
+      templateBuffers
         .asSequence()
-        .mapNotNull { pmTemplateAdapter.fromJson(bufferFileInResources(it)) }
+        .mapNotNull { pmTemplateAdapter.fromJson(it) }
         .flatMap { (pmSteps, authFromRoot) ->
           deepFlattenItems(
             pmSteps.map { item ->
@@ -92,7 +106,12 @@ object ReVoman {
         kick.customTypeAdaptersFromRequestConfig() + kick.customTypeAdaptersFromResponseConfig(),
         kick.globalSkipTypes(),
       )
-    val environment = mergeEnvs(kick.environmentPaths(), kick.dynamicEnvironmentsFlattened())
+    val environment =
+      mergeEnvs(
+        kick.environmentPaths(),
+        kick.environmentInputStreams(),
+        kick.dynamicEnvironmentsFlattened(),
+      )
     val pm =
       PostmanSDK(
         moshiReVoman,
@@ -149,7 +168,10 @@ object ReVoman {
             .flatMap { requestInfo: TxnInfo<Request> -> // --------### PRE-HOOKS ###--------
               preHookExe(step, kick, requestInfo, pm)?.let {
                 Left(
-                  preStepReport.copy(requestInfo = Right(requestInfo).toVavr(), preHookFailure = it)
+                  preStepReport.copy(
+                    requestInfo = Right(requestInfo).toVavr(),
+                    preStepHookFailure = it,
+                  )
                 )
               } ?: Right(preStepReport.copy(requestInfo = Right(requestInfo).toVavr()))
             }
@@ -183,7 +205,7 @@ object ReVoman {
             .map { sr: StepReport -> // --------### POST-HOOKS ###--------
               pm.currentStepReport = sr
               pm.rundown = pm.rundown.copy(stepReports = pm.rundown.stepReports + sr)
-              sr.copy(postHookFailure = postHookExe(kick, pm))
+              sr.copy(postStepHookFailure = postHookExe(kick, pm))
             }
             .merge()
             .copy(

src/main/kotlin/com/salesforce/revoman/input/FileUtils.kt

@@ -10,6 +10,7 @@
 package com.salesforce.revoman.input
 
 import java.io.File
+import java.io.InputStream
 import okio.BufferedSource
 import okio.FileSystem
 import okio.Path.Companion.toPath
@@ -22,6 +23,11 @@ fun bufferFileInResources(fileRelativePath: String): BufferedSource =
 fun readFileInResourcesToString(fileRelativePath: String): String =
   bufferFileInResources(fileRelativePath).readUtf8()
 
+fun bufferInputStream(inputStream: InputStream): BufferedSource = inputStream.source().buffer()
+
+fun readInputStreamToString(inputStream: InputStream): String =
+  bufferInputStream(inputStream).readUtf8()
+
 fun bufferFile(file: File): BufferedSource = file.source().buffer()
 
 fun readFileToString(file: File): String = bufferFile(file).readUtf8()

src/main/kotlin/com/salesforce/revoman/input/PostExeHook.kt

@@ -0,0 +1,14 @@
+/**
+ * ************************************************************************************************
+ * Copyright (c) 2023, Salesforce, Inc. All rights reserved. SPDX-License-Identifier: Apache License
+ * Version 2.0 For full license text, see the LICENSE file in the repo root or
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * ************************************************************************************************
+ */
+package com.salesforce.revoman.input
+
+import com.salesforce.revoman.output.Rundown
+
+fun interface PostExeHook {
+  @Throws(Throwable::class) fun accept(currentRundown: Rundown, rundowns: List<Rundown>)
+}

src/main/kotlin/com/salesforce/revoman/input/config/HookConfig.kt

@@ -7,8 +7,8 @@
  */
 package com.salesforce.revoman.input.config
 
-import com.salesforce.revoman.input.config.HookConfig.Hook.PostHook
-import com.salesforce.revoman.input.config.HookConfig.Hook.PreHook
+import com.salesforce.revoman.input.config.HookConfig.StepHook.PostStepHook
+import com.salesforce.revoman.input.config.HookConfig.StepHook.PreStepHook
 import com.salesforce.revoman.input.config.StepPick.PostTxnStepPick
 import com.salesforce.revoman.input.config.StepPick.PreTxnStepPick
 import com.salesforce.revoman.output.Rundown
@@ -18,21 +18,22 @@ import com.salesforce.revoman.output.report.TxnInfo
 import org.http4k.core.Request
 
 @ExposedCopyVisibility
-data class HookConfig private constructor(val pick: StepPick, val hook: Hook) {
-  sealed interface Hook {
-    fun interface PreHook : Hook {
+data class HookConfig private constructor(val pick: StepPick, val stepHook: StepHook) {
+  sealed interface StepHook {
+    fun interface PreStepHook : StepHook {
       @Throws(Throwable::class)
       fun accept(currentStep: Step, requestInfo: TxnInfo<Request>, rundown: Rundown)
     }
 
-    fun interface PostHook : Hook {
+    fun interface PostStepHook : StepHook {
       @Throws(Throwable::class) fun accept(currentStepReport: StepReport, rundown: Rundown)
     }
   }
 
   companion object {
-    @JvmStatic fun pre(pick: PreTxnStepPick, hook: PreHook): HookConfig = HookConfig(pick, hook)
+    @JvmStatic fun pre(pick: PreTxnStepPick, hook: PreStepHook): HookConfig = HookConfig(pick, hook)
 
-    @JvmStatic fun post(pick: PostTxnStepPick, hook: PostHook): HookConfig = HookConfig(pick, hook)
+    @JvmStatic
+    fun post(pick: PostTxnStepPick, hook: PostStepHook): HookConfig = HookConfig(pick, hook)
   }
 }

src/main/kotlin/com/salesforce/revoman/input/config/KickDef.kt

@@ -16,6 +16,7 @@ import com.salesforce.revoman.output.report.StepReport
 import com.squareup.moshi.JsonAdapter
 import com.squareup.moshi.JsonAdapter.Factory
 import io.vavr.control.Either
+import java.io.InputStream
 import java.lang.reflect.Type
 import java.util.Collections.disjoint
 import org.immutables.value.Value
@@ -24,11 +25,16 @@ import org.immutables.value.Value.Style.ImplementationVisibility.PUBLIC
 @Config
 @Value.Immutable
 internal interface KickDef {
-  // * NOTE 29/10/23 gopala.akshintala: `List` coz it allows adding a template twice
+  // * NOTE 29/10/23 gopala.akshintala: `List` coz it allows adding a template twice,
+  // as there can be use-cases to execute the same template twice
   fun templatePaths(): List<String>
 
+  fun templateInputStreams(): List<InputStream>
+
   fun environmentPaths(): Set<String>
 
+  fun environmentInputStreams(): List<InputStream>
+
   fun dynamicEnvironments(): List<Map<String, String>>
 
   fun nodeModulesRelativePath(): String?

src/main/kotlin/com/salesforce/revoman/internal/exe/PostHook.kt renamed to src/main/kotlin/com/salesforce/revoman/internal/exe/PostStepHook.kt

@@ -8,24 +8,24 @@
 package com.salesforce.revoman.internal.exe
 
 import com.salesforce.revoman.input.config.HookConfig
-import com.salesforce.revoman.input.config.HookConfig.Hook.PostHook
+import com.salesforce.revoman.input.config.HookConfig.StepHook.PostStepHook
 import com.salesforce.revoman.input.config.Kick
 import com.salesforce.revoman.input.config.StepPick.PostTxnStepPick
 import com.salesforce.revoman.internal.postman.PostmanSDK
-import com.salesforce.revoman.output.ExeType.POST_HOOK
+import com.salesforce.revoman.output.ExeType.POST_STEP_HOOK
 import com.salesforce.revoman.output.Rundown
 import com.salesforce.revoman.output.report.StepReport
-import com.salesforce.revoman.output.report.failure.HookFailure.PostHookFailure
+import com.salesforce.revoman.output.report.failure.HookFailure.PostStepHookFailure
 import io.github.oshai.kotlinlogging.KotlinLogging
 
-internal fun postHookExe(kick: Kick, pm: PostmanSDK): PostHookFailure? =
+internal fun postHookExe(kick: Kick, pm: PostmanSDK): PostStepHookFailure? =
   pickPostHooks(kick.postHooks(), pm.currentStepReport, pm.rundown)
     .asSequence()
     .map { postHook ->
-      runChecked(pm.currentStepReport.step, POST_HOOK) {
+      runChecked(pm.currentStepReport.step, POST_STEP_HOOK) {
           postHook.accept(pm.currentStepReport, pm.rundown)
         }
-        .mapLeft { PostHookFailure(it) }
+        .mapLeft { PostStepHookFailure(it) }
     }
     .firstOrNull { it.isLeft() }
     ?.leftOrNull()
@@ -34,11 +34,11 @@ private fun pickPostHooks(
   postHooks: List<HookConfig>,
   currentStepReport: StepReport,
   rundown: Rundown,
-): List<PostHook> =
+): List<PostStepHook> =
   postHooks
     .asSequence()
     .filter { (it.pick as PostTxnStepPick).pick(currentStepReport, rundown) }
-    .map { it.hook as PostHook }
+    .map { it.stepHook as PostStepHook }
     .toList()
     .also {
       if (it.isNotEmpty()) {