Release 0.5.7

- Move CompositeGraphResponse adapter
- Minor corrections to Request and Response Info
- Add MilestoneBillingE2ETest
- Minor doc edits

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.6
+:revoman-version: 0.5.7
 
 '''
 
@@ -209,7 +209,7 @@ StepReport(
 	envSnapshot: PostmanEnvironment<Any?> // <2>
 )
 ----
-<1> https://docs.vavr.io/#_either[`Either` type from the VAVR] library represents either of the two states, error or success
+<1> https://docs.vavr.io/#_either[`Either` type from the VAVR] library represents either of the two states, used here to represent error or success
 <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]
@@ -399,8 +399,8 @@ where you can filter out these legacy types from Marshalling/Unmarshalling
 * You may use the bundled static factory methods named `RequestConfig.unmarshallResponse()` for expressiveness.
 * You can pass a `PreTxnStepPick` which is a `Predicate` used
 to qualify a step whose Request JSON payload needs to be unmarshalled/deserialized.
-* If you have set up `requestConfig()` once, wherever you wish to access the request in your <<#_pre_step_and_post_step_hooks,Pre-Step Hooks>>, you can call `stepReport.responseInfo.get().<TypeT>getTypedTxnObj()` which returns a Strong type to conveniently assert.
-* If you don't pass anything in this config, Moshi unmarshalls into default data structures like `LinkedHashMap`
+* If you have set up `requestConfig()` once, wherever you wish to read the request in your <<#_pre_step_and_post_step_hooks,Pre-Step Hooks>>, you can call `stepReport.requestInfo.get().<TypeT>getTypedTxnObj()` which returns your request JSON as a Strong type.
+* If you don't configure it for a step, Moshi unmarshalls the step request JSON into default data structures like `LinkedHashMap`
 
 ==== `responseConfig()`
 
@@ -409,8 +409,8 @@ to qualify a step whose Request JSON payload needs to be unmarshalled/deserializ
 * Use bundled static factory methods like `ResponseConfig.unmarshallSuccessResponse()` and `ResponseConfig.unmarshallErrorResponse()` for expressiveness.
 * You can pass a `PostTxnStepPick` which is a `Predicate` used
 to qualify a step whose Response JSON payload needs to be unmarshalled/deserialized.
-* If you have set up `responseConfig()` once, wherever you wish to access or assert the response in your <<#_pre_step_and_post_step_hooks,Post-Step Hooks>>, you can call `stepReport.responseInfo.get().<TypeT>getTypedTxnObj()` which returns a Strong type to conveniently assert.
-* If you don't pass anything in this config, Moshi unmarshalls into default data structures like `LinkedHashMap`
+* If you have set up `responseConfig()` once, wherever you wish to read or assert the response in your <<#_pre_step_and_post_step_hooks,Post-Step Hooks>>, you can call `stepReport.responseInfo.get().<TypeT>getTypedTxnObj()` which returns your response JSON as a Strong type to conveniently assert.
+* If you don't configure it for a step, Moshi unmarshalls the Step response JSON into default data structures like `LinkedHashMap`
 
 [TIP]
 ====
@@ -425,16 +425,16 @@ See `DiMorphicAdapter` in action from the test `compositeGraphResponseDiMorphicM
 
 ==== `globalCustomTypeAdapters()`
 
-These adapters are used for marshalling/unmarshalling request/response payload for any step. 
-These compliment the custom adapters setup in `requestConfig()` or `responseConfig()` 
+* These come handy when the same POJO/Data structure (e.g `ID`) is present across multiple Request or Response POJOs. These adapters compliment the custom adapters setup in `requestConfig()` or `responseConfig()` wherever these types are present.
+* But these adapters won't be used to marshall/unmarshall before or after each step execution. Which means you won't be able to Strong types in the debug view. Although, you can get them on-demand using the respective `getTypedObj()` method.
 
 ==== JSON Reader/Writer Utils to build Moshi adapters
 
 ReṼoman also comes
 bundled with link:{sourcedir}/com/salesforce/revoman/input/json/JsonReaderUtils.kt[JSON Reader utils] and link:{sourcedir}/com/salesforce/revoman/input/json/JsonWriterUtils.kt[JSON Writer utils]
 to help build Moshi adapters.
 
-TIP: Refer link:{integrationtestdir}/com/salesforce/revoman/integration/core/pq/adapters/ConnectInputRepWithGraphAdapter.java[ConnectInputRepWithGraphAdapter] on how these utils come in handy in building an advanced Moshi adapter
+TIP: Refer link:{integrationtestdir}/com/salesforce/revoman/integration/core/adapters/ConnectInputRepWithGraphAdapter.java[ConnectInputRepWithGraphAdapter] on how these utils come in handy in building an advanced Moshi adapter
 
 ==== JSON POJO Utils
 
@@ -448,12 +448,6 @@ See in Action:
 * link:{integrationtestdir}/com/salesforce/revoman/input/json/JsonPojoUtils2Test.java[JsonPojoUtils2Test]
 ====
 
-==== `rundown.mutableEnv.getTypedObj()`
-
-You can read an environment variable value as a Strong type.
-See it in action: `getTypedObj()`
-test from link:{testdir}/com/salesforce/revoman/output/postman/PostmanEnvironmentTest.java[PostmanEnvironmentTest]
-
 === Execution Control
 
 The configuration offers methods through which the execution strategy can be controlled without making any changes to the template:
@@ -577,6 +571,12 @@ so you can copy and import that environment conveniently into Postman.
 TIP: You do NOT need to save the copied Postman environment JSON from the debugger into file.
 You can paste (kbd:[Ctrl+v]) directly in the Postman environment window
 
+==== Read Environment value into Strong type
+
+You can read any value from mutableEnv as a Strong type using `rundown.mutableEnv.<TypeT>getTypedObj()`
+See it in action: `getTypedObj()`
+test from link:{testdir}/com/salesforce/revoman/output/postman/PostmanEnvironmentTest.java[PostmanEnvironmentTest]
+
 ==== `pmEnvSnapshot` in each StepReport
 
 Each StepReport also has a `pmEnvSnapshot` to assert if a step has executed as expected and compare snapshots from different steps to examine the execution progress.
@@ -585,7 +585,7 @@ 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 in a specific order, you can use the `revUp` overload which accepts a vararg `Kick` configs.
+* 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
@@ -603,6 +603,12 @@ TIP: Here is an example of a low-code link:{integrationtestdir}/com/salesforce/r
 Compared to a traditional Integration/Functional or E2E test, approximately, the amount of code needed is *89%* less using ReṼoman.
 The above test doesn't just have low code, but also low in Cognitive Complexity and Transparent in what it does.
 
+=== Low Learning Curve
+
+Familiarity with Postman gets you a long way in understanding this tool.
+Playing with the existing link:{integrationtestdir}[Integration Tests]
+and writing a couple of hands-on tests should get you started.
+
 === CI/CD integrability
 
 * ReṼoman is like any JVM library that you can plug into any JVM program/test (e.g., JUnit tests or Integration tests).
@@ -658,7 +664,7 @@ The future looks bright with multiple impactful features in the pipeline:
 
 You don't have to.
 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>>
+and you can interlace your TestUtils through <<#_plug_in_your_java_code_in_between_postman_execution,Pre-Step/Post-Step 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]?
 

buildSrc/src/main/kotlin/Config.kt

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

src/integrationTest/java/com/salesforce/revoman/input/json/JsonPojoUtils2Test.java

@@ -9,11 +9,11 @@
 
 import static com.google.common.truth.Truth.assertThat;
 import static com.salesforce.revoman.input.FileUtils.readFileInResourcesToString;
-import static com.salesforce.revoman.integration.core.pq.adapters.ConnectInputRepWithGraphAdapter.adapter;
+import static com.salesforce.revoman.integration.core.adapters.ConnectInputRepWithGraphAdapter.adapter;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
-import com.salesforce.revoman.integration.core.pq.adapters.IDAdapter;
+import com.salesforce.revoman.integration.core.adapters.IDAdapter;
 import com.salesforce.revoman.integration.core.pq.connect.request.PlaceQuoteInputRepresentation;
 import com.salesforce.revoman.integration.core.pq.connect.request.PricingPreferenceEnum;
 import com.salesforce.revoman.integration.core.pq.connect.response.PlaceQuoteOutputRepresentation;

src/integrationTest/java/com/salesforce/revoman/integration/core/CoreUtils.java

@@ -0,0 +1,57 @@
+/***************************************************************************************************
+ *  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.integration.core;
+
+import static com.salesforce.revoman.input.config.HookConfig.post;
+import static com.salesforce.revoman.input.config.ResponseConfig.unmarshallResponse;
+import static com.salesforce.revoman.input.config.StepPick.PostTxnStepPick.afterStepContainingURIPathOfAny;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.salesforce.revoman.input.config.HookConfig;
+import com.salesforce.revoman.input.config.ResponseConfig;
+import com.salesforce.revoman.input.json.adapters.salesforce.CompositeGraphResponse;
+import com.salesforce.revoman.input.json.adapters.salesforce.CompositeGraphResponse.Graph.ErrorGraph;
+import com.salesforce.revoman.output.report.StepReport;
+import kotlin.collections.CollectionsKt;
+
+public class CoreUtils {
+	private CoreUtils() {}
+
+	public static final String COMPOSITE_GRAPH_URI_PATH = "composite/graph";
+
+	public static final HookConfig ASSERT_COMPOSITE_GRAPH_RESPONSE_SUCCESS =
+			post(
+					afterStepContainingURIPathOfAny(COMPOSITE_GRAPH_URI_PATH),
+					(stepReport, ignore) -> assertCompositeGraphResponseSuccess(stepReport));
+
+	public static ResponseConfig unmarshallCompositeGraphResponse() {
+		return unmarshallResponse(
+				afterStepContainingURIPathOfAny(COMPOSITE_GRAPH_URI_PATH),
+				CompositeGraphResponse.class,
+				CompositeGraphResponse.ADAPTER);
+	}
+
+	public static void assertCompositeGraphResponseSuccess(StepReport stepReport) {
+		final var responseTxnInfo = stepReport.responseInfo.get();
+		final var graphResp =
+				responseTxnInfo.<CompositeGraphResponse>getTypedTxnObj().getGraphs().get(0);
+		assertTrue(
+				graphResp.isSuccessful(),
+				() -> {
+					final var firstErrorResponse =
+							CollectionsKt.first(((ErrorGraph) graphResp).errorResponses);
+					final var firstErrorResponseBody = ((ErrorGraph) graphResp).firstErrorResponseBody;
+					return String.format(
+							"Unsuccessful Composite Graph response%n{%n  first error ReferenceId: %s%n  first errorCode: %s%n  first errorMessage: %s%n}%n%s",
+							firstErrorResponse.getReferenceId(),
+							firstErrorResponseBody.getErrorCode(),
+							firstErrorResponseBody.getMessage(),
+							stepReport);
+				});
+	}
+}

src/integrationTest/java/com/salesforce/revoman/integration/core/pq/adapters/ConnectInputRepWithGraphAdapter.java renamed to src/integrationTest/java/com/salesforce/revoman/integration/core/adapters/ConnectInputRepWithGraphAdapter.java

@@ -5,7 +5,7 @@
  *  http://www.apache.org/licenses/LICENSE-2.0
  **************************************************************************************************/
 
-package com.salesforce.revoman.integration.core.pq.adapters;
+package com.salesforce.revoman.integration.core.adapters;
 
 import static com.salesforce.revoman.input.json.JsonReaderUtils.anyMapR;
 import static com.salesforce.revoman.input.json.JsonReaderUtils.listR;

src/integrationTest/java/com/salesforce/revoman/integration/core/pq/adapters/IDAdapter.java renamed to src/integrationTest/java/com/salesforce/revoman/integration/core/adapters/IDAdapter.java

@@ -5,14 +5,16 @@
  *  http://www.apache.org/licenses/LICENSE-2.0
  **************************************************************************************************/
 
-package com.salesforce.revoman.integration.core.pq.adapters;
+package com.salesforce.revoman.integration.core.adapters;
 
 import com.salesforce.revoman.integration.core.pq.connect.response.ID;
 import com.squareup.moshi.FromJson;
 import com.squareup.moshi.ToJson;
 
 // * NOTE 10 Mar 2024 gopala.akshintala: Custom Type Adapter
 public class IDAdapter {
+	public static final IDAdapter INSTANCE = new IDAdapter();
+
 	@FromJson
 	ID fromJson(String id) {
 		return new ID(id);

src/integrationTest/java/com/salesforce/revoman/integration/core/bt2bs/MilestoneBillingE2ETest.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 salesforce.com, inc.
+ * All Rights Reserved
+ * Company Confidential
+ */
+
+package com.salesforce.revoman.integration.core.bt2bs;
+
+import static com.google.common.truth.Truth.assertThat;
+import static com.salesforce.revoman.integration.core.bt2bs.ReVomanConfigForBT2BS.MILESTONE_CONFIG;
+import static com.salesforce.revoman.integration.core.bt2bs.ReVomanConfigForBT2BS.MILESTONE_SETUP_CONFIG;
+import static com.salesforce.revoman.integration.core.bt2bs.ReVomanConfigForBT2BS.USER_CREATION_AND_SETUP_CONFIG;
+
+import com.salesforce.revoman.ReVoman;
+import java.util.Map;
+import kotlin.collections.CollectionsKt;
+import org.junit.jupiter.api.Test;
+
+class MilestoneBillingE2ETest {
+
+	@Test
+	void testMilestoneBillingE2E() {
+		final var mbRundown =
+				ReVoman.revUp(
+						(rundown, ignore) ->
+								assertThat(rundown.firstUnIgnoredUnsuccessfulStepReport()).isNull(),
+						USER_CREATION_AND_SETUP_CONFIG,
+						MILESTONE_SETUP_CONFIG,
+						MILESTONE_CONFIG);
+		assertThat(CollectionsKt.last(mbRundown).mutableEnv)
+				.containsAtLeastEntriesIn(
+						Map.of(
+								"billingMilestonePlan1Status", "Completely Billed",
+								"billingMilestonePlanItem1Status", "Invoiced",
+								"billingSchedule1Status", "CompletelyBilled",
+								"invoice1Status", "Posted",
+								"invoice2Status", "Posted"));
+	}
+}

src/integrationTest/java/com/salesforce/revoman/integration/core/bt2bs/ReVomanConfigForBT2BS.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 salesforce.com, inc.
+ * All Rights Reserved
+ * Company Confidential
+ */
+
+package com.salesforce.revoman.integration.core.bt2bs;
+
+import static com.salesforce.revoman.input.config.HookConfig.post;
+import static com.salesforce.revoman.input.config.StepPick.PostTxnStepPick.afterStepContainingHeader;
+import static com.salesforce.revoman.input.config.StepPick.PostTxnStepPick.afterStepContainingURIPathOfAny;
+import static com.salesforce.revoman.integration.core.CoreUtils.ASSERT_COMPOSITE_GRAPH_RESPONSE_SUCCESS;
+import static com.salesforce.revoman.integration.core.CoreUtils.unmarshallCompositeGraphResponse;
+import static com.salesforce.revoman.output.ExeType.HTTP_STATUS;
+
+import com.salesforce.revoman.input.config.HookConfig;
+import com.salesforce.revoman.input.config.Kick;
+import com.salesforce.revoman.integration.core.adapters.IDAdapter;
+
+public final class ReVomanConfigForBT2BS {
+
+	private ReVomanConfigForBT2BS() {}
+
+	static final String ENV_PATH = "pm-templates/core/milestone/env.postman_environment.json";
+	static final String IGNORE_HTTP_STATUS_UNSUCCESSFUL = "ignoreHTTPStatusUnsuccessful";
+	static final String NODE_MODULE_RELATIVE_PATH = "js";
+
+	// ## User creation and Setup
+	static final String COLLECTION_PATH = "pm-templates/core/milestone/";
+	private static final String USER_CREATION_AND_SETUP_COLLECTION_PATH =
+			COLLECTION_PATH + "user-creation-and-setup.postman_collection.json";
+	static final Kick USER_CREATION_AND_SETUP_CONFIG =
+			Kick.configure()
+					.templatePath(USER_CREATION_AND_SETUP_COLLECTION_PATH)
+					.environmentPath(ENV_PATH)
+					.responseConfig(unmarshallCompositeGraphResponse())
+					.hook(ASSERT_COMPOSITE_GRAPH_RESPONSE_SUCCESS)
+					.nodeModulesRelativePath(NODE_MODULE_RELATIVE_PATH)
+					.haltOnFailureOfTypeExcept(
+							HTTP_STATUS, afterStepContainingHeader(IGNORE_HTTP_STATUS_UNSUCCESSFUL))
+					.insecureHttp(true)
+					.off();
+
+	// ## Hooks
+	static final String PST = "connect/rev/sales-transaction/actions/place";
+	static final String STANDALONE_INVOICE_IA =
+			"commerce/invoicing/invoices/collection/actions/generate";
+	static final String ASSETIZE_IA = "actions/standard/createOrUpdateAssetFromOrder";
+	static final String AMEND_API = "connect/revenue-management/assets/actions/amend";
+	static final String CANCEL_API = "connect/revenue-management/assets/actions/cancel";
+	public static final HookConfig MEMQ_AWAIT =
+			post(
+					afterStepContainingURIPathOfAny(
+							PST, STANDALONE_INVOICE_IA, ASSETIZE_IA, AMEND_API, CANCEL_API),
+					(ignore1, ignore2) -> Thread.sleep(5000));
+
+	// ## Milestone Setup Config
+	private static final String MB_SETUP_POSTMAN_COLLECTION_PATH =
+			COLLECTION_PATH + "milestone-setup.postman_collection.json";
+	static final Kick MILESTONE_SETUP_CONFIG =
+			Kick.configure()
+					.templatePath(MB_SETUP_POSTMAN_COLLECTION_PATH)
+					.haltOnFailureOfTypeExcept(
+							HTTP_STATUS, afterStepContainingHeader(IGNORE_HTTP_STATUS_UNSUCCESSFUL))
+					.responseConfig(unmarshallCompositeGraphResponse())
+					.hook(ASSERT_COMPOSITE_GRAPH_RESPONSE_SUCCESS)
+					.nodeModulesRelativePath(NODE_MODULE_RELATIVE_PATH)
+					.insecureHttp(true)
+					.off();
+
+	// ## Milestone Config
+	private static final String MB_POSTMAN_COLLECTION_PATH =
+			COLLECTION_PATH + "bmp-create-runtime.postman_collection.json";
+	static final Kick MILESTONE_CONFIG =
+			Kick.configure()
+					.templatePath(MB_POSTMAN_COLLECTION_PATH)
+					.responseConfig(unmarshallCompositeGraphResponse())
+					.hooks(MEMQ_AWAIT, ASSERT_COMPOSITE_GRAPH_RESPONSE_SUCCESS)
+					.globalCustomTypeAdapter(IDAdapter.INSTANCE)
+					.nodeModulesRelativePath(NODE_MODULE_RELATIVE_PATH)
+					.insecureHttp(true)
+					.off();
+}