Doc edits

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

Author: overfullstack

README.adoc

@@ -97,8 +97,8 @@ Leveraging it can mitigate writing a lot of code as we translate those manual st
 
 ____
 
-* How _productive_ would it be, if you can plug your exported Postman collection template,
-that you anyway would have created for your manual testing, and execute them through your JVM tests?
+* How _productive_ would it be, if you could plug your exported Postman collection template,
+that you anyway would have created for your manual testing and executed through your JVM tests?
 
 * How about a Universal API automation tool that promotes low code and low-cognitive-complexity and strikes a balance between flexibility and ease of use?
 
@@ -185,8 +185,8 @@ such that you can seamlessly run more assertions on top of the run.
 [source,kotlin,indent=0,options="nowrap"]
 ----
 Rundown(
-  stepNameToReport: List<StepReport>,
-  environment: PostmanEnvironment)
+  val stepReports: List<StepReport>,
+  val mutableEnv: PostmanEnvironment<Any?>)
 
 StepReport(
   step: Step,
@@ -201,7 +201,7 @@ StepReport(
 <2> Snapshot of Environment at the end of each step execution. It can be compared with previous or next step environment snapshots to see what changed in this step
 
 [.lead]
-`Rundown` has many convenience methods to ease applying further assertions on top of it.
+`Rundown` has many convenient methods to ease applying further assertions on top of it.
 
 TIP: Other simple examples to see in Action: link:{integrationtestdir}/com/salesforce/revoman/integration/pokemon/PokemonTest.java[PokemonTest.java]
 
@@ -287,11 +287,11 @@ assertThat(pqRundown.mutableEnv)
           "quoteCalculationStatusAfterAllUpdates", PricingPref.System.completeStatus));
 ----
 <1> `revUp()` is the method to call passing a configuration, built as below
-<2> Supply the path (relative to resources) to the Template Collection JSON file
-<3> Supply the path (relative to resources) to the Environment JSON file
+<2> Supply the path (relative to resources) to the Template Collection JSON file/files
+<3> Supply the path (relative to resources) to the Environment JSON file/files
 <4> Supply any dynamic environment that is runtime-specific
 <5> <<Custom Dynamic variables>>
-<6> <<Pre-req and Post-res scripts>>
+<6> Node modules path (relative to resources) to be used inside <<Pre-req and Post-res scripts>>
 <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>>
@@ -310,11 +310,11 @@ ifndef::env-github[]
 include::{integrationtestdir}/com/salesforce/revoman/integration/core/pq/PQE2EWithSMTest.java[tag=pq-e2e-with-revoman-config-demo]
 ----
 <1> `revUp()` is the method to call passing a configuration, built as below
-<2> Supply the path (relative to resources) to the Template Collection JSON file
-<3> Supply the path (relative to resources) to the Environment JSON file
+<2> Supply the path (relative to resources) to the Template Collection JSON file/files
+<3> Supply the path (relative to resources) to the Environment JSON file/files
 <4> Supply any dynamic environment that is runtime-specific
 <5> <<Custom Dynamic variables>>
-<6> <<Pre-req and Post-res scripts>>
+<6> Node modules path (relative to resources) to be used inside <<Pre-req and Post-res scripts>>
 <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>>
@@ -328,7 +328,7 @@ endif::[]
 == Debugging UX
 
 [.lead]
-This tool has particular emphasis on Debugging experience. Here is what a debugger view of a <<Rundown>> looks like:
+This tool has a particular emphasis on the Debugging experience. Here is what a debugger view of a <<Rundown>> looks like:
 
 image:rundown.png[Rundown of all steps]
 
@@ -338,7 +338,7 @@ image:rundown.png[Rundown of all steps]
 image:step-report.png[Step Report]
 
 [.lead]
-Here are the environment *key-value* pairs accumulated along the entire execution and appended to the environment from file and dynamicEnvironment supplied:
+Here are the environment *key-value* pairs accumulated along the entire execution and appended to the environment from the file and `dynamicEnvironment` supplied:
 
 image:mutable-env.png[Mutable environment after the execution completion]
 
@@ -366,7 +366,7 @@ image:pq-exe-logging.gif[Monitor Execution]
 === Type Safety with flexible JSON <- -> POJO marshalling/serialization and unmarshalling/deserialization
 
 * ReṼoman internally uses a modern JSON library called https://github.com/square/moshi[**Moshi**]
-* There may be a POJO that inherits or contains legacy types which are hard or impossible to serialize. ReṼoman lets you serialize such types through `globalSkipTypes`, where you can filter-out these legacy types from Marshalling/Unmarshalling, only focussing on fields that matter.
+* There may be a POJO that inherits or contains legacy types that are hard or impossible to serialize. ReṼoman lets you serialize such types through `globalSkipTypes`, where you can filter out these legacy types from Marshalling/Unmarshalling, only focussing on fields that matter.
 * The payload may not map to POJO, and you may need a custom types adapter for Marshalling/Unmarshalling. Moshi has it covered for you with its advanced adapter mechanism and ReṼoman accepts Moshi adapters via
 ** `requestConfig` — For types present as part of request payload for qualified Steps
 ** `responseConfig` — For types present as part of response payload for qualified Steps
@@ -432,15 +432,15 @@ You can plug in your java code
 to create/generate values for environment variables
 which can be populated and picked-up by subsequent steps.
 For example, you may want some `xyzId` but you don't have a Postman collection to create it.
-But instead, you have a Java utility to generate/create it.
+Instead, you have a Java utility to generate/create it.
 You can invoke the utility in a pre-hook of a step and set the value in `rundown.mutableEnv`,
 so the later steps can pick up value for `+{{xyzId}}+` variable from the environment.
 
 ==== Response Validations
 
 * Post-Hooks are the best place to validate response right after the step.
 * If you have configured a strong type for your response through `responseConfig`, you can write type-safe validations by extracting your Strong type Object using `stepReport.responseInfo.get().<TypeT>getTypedTxnObj()` (if you have configured `responseConfig()` or `globalCustomTypeAdapters()`) or use `JsonPojoUtils.jsonToPojo(TypeT, stepReport.responseInfo.get().httpMsg.bodyString())` to convert it inline.
-* If your response data structure is non-trivial and have requirements to execute validations with different strategies like `fail-fast` or `error-accumulation`, consider using a library like https://github.com/salesforce-misc/Vador[*Vador*]
+* If your response data structure is non-trivial and has requirements to execute validations with different strategies like `fail-fast` or `error-accumulation`, consider using a library like https://github.com/salesforce-misc/Vador[*Vador*]
 
 === Pre-req and Post-res scripts
 
@@ -469,7 +469,7 @@ pm.environment.set("$quantity", _.random(1, 10)); // lodash doesn't need `requir
 
 [TIP]
 ====
-* `node_modules` adds a lot of files to check in. You may replace them with a single distribution file
+* `node_modules` adds a lot of files to check-in. You may replace them with a single distribution file
 
 image::node_modules.png[]
 
@@ -481,7 +481,7 @@ CAUTION: The recommendation is not to add too much code in <<Pre-req and Post-re
 [#_mutable_environment]
 === Mutable Environment
 
-* Environment is the only mutable-shared state across step executions, which can be used for data-passing between consumer and the library.
+* 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.
 
 ==== Read Mutable Environment as Postman Environment JSON format
@@ -497,12 +497,12 @@ Each StepReport also has a `pmEnvSnapshot` to assert if a step has executed as e
 === Compose Modular Executions
 
 * 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 collection.
-* If you wish to compose these executions, you can do so by adding the previous execution's `mutableEnv` to current execution using `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.
+* 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.
 
 === Custom Dynamic variables
 
-If the in-built dynamic variables don't fit your need, you can plug your own dynamic variable generator
+If the in-built dynamic variables don't fit your needs, you can plug your own dynamic variable generator
 to be invoked to generate a value for your custom variable-key in the template at runtime.
 
 == USP
@@ -535,8 +535,8 @@ The above test doesn't just have low code, but also low in Cognitive Complexity
 
 == Perf
 
-This entire execution of **~75 steps**, which includes **10 async steps**, took a mere *122 sec* on localhost.
-This can be much better on auto-build environments.
+This entire execution of **~75 steps**, including **10 async steps**, took a mere *122 sec* on localhost.
+This can be much better in auto-build environments.
 
 image:pq-revoman-test-time.png[Localhost Test time on FTest console for ~75 steps]
 
@@ -549,7 +549,7 @@ to how your server responds or your network speed.
 The future looks bright with multiple impactful features in the pipeline:
 
 * API metrics and Analytics
-* *It's built with extensibility* in mind. It can easily be extended to support other template formats, e.g., Kaiju templates used for availability testing.
+* *It's built with extensibility* in mind. It can easily be extended to support other template formats, such as Kaiju templates used for availability testing.
 * In-built polling support for Async steps
 * Payload generation
 * Flow control through YAML config
@@ -569,13 +569,13 @@ The future looks bright with multiple impactful features in the pipeline:
 === Do I need to migrate all my existing TestUtils to Postman Collections?
 
 You don't have to.
-This is a JVM first tool,
+This is a JVM-first tool,
 and you can interlace your TestUtils through <<#_plug_in_your_java_code_in_between_postman_execution,Pre-/Post-Hooks>>
 
 === Why not use https://learning.postman.com/docs/collections/using-newman-cli/command-line-integration-with-newman[Newman] or https://learning.postman.com/docs/postman-cli/postman-cli-overview/#comparing-the-postman-cli-and-newman[Postman CLI]?
 
 * ReṼoman may be similar to Newman or Postman CLI when it comes to executing a Postman collection, but the _similarities end there_.
-* Newman or Postman CLI are built for node and cannot be executed within a JVM. Even if you are able to run with some hacky way, there is no easy way to assert results.
+* Newman or Postman CLI are built for node and cannot be executed within a JVM. Even if you are able to run in some hacky way, there is no easy way to assert results.
 * ReṼoman is JVM first that lets you configure a lot more, and gives you back a detailed report to assert in a typesafe way
 
 == 🙌🏼 Consume-Collaborate-Contribute