Reorganize Petstore and doc review

st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/BaseAll.java

@@ -32,29 +32,29 @@
 import in2test.application.qagrow.QAGrowApiProcess;
 
 /**
- * This is a base class for all system and integration tests that
- * defines basic configurations to manage the different items involved in the tests:
+ * This is the base class for all system and integration tests to
+ * define basic configurations to manage the different items involved in the tests:
  * 
  * - Abstract methods to configure main test parameters
  * - Methods to configure the main test objects (can be overriden for fine tuning)
  * - Test utilities (making assertions, serialization, etc.)
  *
- * The two main configuration methods are getSubjectName (to identify the SUT) and
- * isLiveBackend to indicate whether the test generates and sends data to a live backend
- * or everything is performed in local (no SUT needed).
+ * The two main configurations for every test are getSubjectName() (to identify the SUT) and
+ * isLiveBackend() to indicate whether the test generates and sends data to a live backend
+ * or everything is performed in local (no running SUT needed).
  * These values in combination with the test inheritance, allow creating four
  * different flavours of the tests:
  * 
- * - datagen-local: a simulation of the data generation that manually specifies
+ * - datagen-local: the test simulates the data generation by specifying
  *   the commands sent to the Data Loader and gets the data that would be loaded.
  * - datagen-live: manually specifies the commands sent to the Data Loader,
- *   but loads the data in a live SUT backend
+ *   but loads the data in a running (live) SUT backend.
  * - qagrow-local: Automatically generates the test data, but working in local
- * - qagrow-live: Automatically generates the test data and loads the data
+ * - qagrow-live: Automatically generates and loads the test data
  *   in a live SUT backend.
  *   
  * The last is the true system test that integrates all main components:
- * data loader, qagrow generator, fpc rule generator and the SUT backend
+ * data loader, qagrow data generator, fpc rule generator and the SUT backend.
  */
 public abstract class BaseAll {
 	protected Logger log = LoggerFactory.getLogger(this.getClass());
@@ -75,8 +75,10 @@ public void setUp() {
 	}
 
 	/**
-	 * Returns a string to identify the test subject (e.g. petstore, market)
+	 * Returns a string to identify the SUT (e.g. petstore, market)
 	 * to allow identify separate the expected and actual outputs
+	 * (must be overriden by all test methods, usually in a base 
+	 * class for this SUT)
 	 */
 	protected abstract String getSutName();
 
@@ -89,23 +91,23 @@ protected boolean isLiveBackend() {
 	}
 
 	/**
-	 * Returns the url of the backend
+	 * Returns the url of the SUT backend
 	 */
 	protected abstract String getServerUrl();
 
 	/**
-	 * Returns the endpoint to get all data from the backend 
+	 * Returns the endpoint to get all data from the SUT backend 
 	 */
 	protected abstract String getAllDataLiveEndpoint();
 
 	/**
-	 * Returns the endpoint to reset all data in the backend 
+	 * Returns the endpoint to reset all data in the SUT backend 
 	 */
 	protected abstract String getDeleteAllDataLiveEndpoint();
 
 	/**
 	 * Returns the data schema for each test.
-	 * Each base test should configure the appropriate IdResolver and location of the OpenApi specification
+	 * Each SUT base test should configure the appropriate IdResolver and location of the OpenApi specification
 	 */
 	protected abstract TdSchema getSchema();
 
@@ -117,23 +119,23 @@ protected TdRulesApi getRulesApi() {
 	}
 
 	/**
-	 * Gets the TdRules model for a given query, and reprocess the version numbers
+	 * Gets the TdRules model for a given query and reprocess the version numbers
 	 * to allow comparison of expected test results
 	 */
 	protected TdRules getRules(String query) {
 		TdRules rules = getRulesApi()
 				.getRules(getSchema(), query, "noboundaries gettransformedquery formatquery clientname=" + getSutName());
-		// remove version to allow result comparison
-		return filterRulesVersion(rules);
+		return filterRulesVersion(rules); // remove version to allow result comparison
 	}
 
 	/**
 	 * Gets a data loader for the current configuration:
 	 * - In local tests uses the default OaLocalAdapter.
 	 * - In live tests uses the default OaLiveAdapter and the default OaPathResolver
 	 *   configured to resolve paths from the schema model.
-	 * If a custom path resolver is needed the test must override the getLiveDataLoader()
-	 * method with the appropriate configuration. Calling getDataLoader() will invoke
+	 *   
+	 * If a custom path resolver is needed, the test must override the getLiveDataLoader()
+	 * method with the appropriate configuration so that calling getDataLoader() will invoke
 	 * the overriden method.
 	 */
 	protected DataLoader getDataLoader() {
@@ -173,22 +175,22 @@ protected void generateAndLoad(DataLoader loader, String[] queries, IAttrGen dic
 
 
 	/**
-	 * Gets all data from the backend 
+	 * Gets all data stored in the SUT backend 
 	 */
 	protected String getAllLiveData() {
 		ApiWriter api=new ApiWriter();
 		return api.get(getAllDataLiveEndpoint()).getBody();
 	}
 	/**
-	 * Resets all data in the backend 
+	 * Resets all data stored in the SUT backend 
 	 */
 	protected String deleteAllLiveData() {
 		ApiWriter api=new ApiWriter();
 		return api.delete(getDeleteAllDataLiveEndpoint()).getBody();
 	}
 
 	/**
-	 * General assert on the content of a model (as string) against the expected.
+	 * General assert on a model (as string) against the expected.
 	 * Actual outputs are saved and then comparison is made between the content of
 	 * the expected and actual files.
 	 */
@@ -210,12 +212,6 @@ protected void assertModel(String fileName, String actualModel) {
 	 * or if it has been loaded to a live backend (in this case
 	 * a call to get the data content is made before comparison)
 	 */
-	/**
-	 * Gets a data loader according to the current configuration.
-	 * The actual output data is obtanied as indicated:
-	 * - In local uses the output produced by the data adapter.
-	 * - In live tests queries the backend to get all stored data.
-	 */
 	protected void assertData(String fileName, DataLoader dg) {
 		if (isLiveBackend())
 			assertLiveData(fileName, dg);
@@ -226,8 +222,8 @@ protected void assertLocalData(String fileName, DataLoader dg) {
 		assertModel(fileName, dg.getDataAdapter().getAllAsString());
 	}
 	protected void assertLiveData(String fileName, DataLoader dg) {
-		// Gets the data from the backend and
-		// uses a more compact presentation for easier comparison (an object per line)
+		// Gets the data from the backend and transforms into
+		// a more compact presentation for easier comparison (an object per line)
 		String payload=getAllLiveData();
 		payload=reserializeStoredData(payload);
 		log.info("Actual data stored in the backend\n{}", reserializeStoredData(payload));
@@ -237,7 +233,7 @@ protected void assertLiveData(String fileName, DataLoader dg) {
 
 	/**
 	 * Removes the version number of the FPC rules to allow repeatable comparisons
-	 * (saves the version in target to use during debugging)
+	 * (saves the renamed version in target to use during debugging)
 	 */
 	protected TdRules filterRulesVersion(TdRules rules) {
 		String version=rules.getVersion();
@@ -248,19 +244,16 @@ protected TdRules filterRulesVersion(TdRules rules) {
 	}
 
 	/**
-	 * Serializa un objeto cualquiera a json mostrando los atributos vacios o nulos
+	 * General purpose serialization of an object to use in test comparison
 	 */
 	protected String serialize(TdSchema model) {
 		return new ModelJsonSerializer().serialize(model, true);
 	}
 
 	/**
-	 * Serializa el contenido de toda la base de datos como:
-	 * - un objeto cuyos items son el contenido de cada una de las tablas
-	 * - cada item es un objeto de clave nombre de tabla y valor un array 
-	 *   con el contenido de cada fila de la tabla
-	 * Devuelve un string donde cada linea es un objeto de clave
-	 * nombre de tabla y valor el objeto con los valores de la fila
+	 * Given a serialized json string that represents the data stored in a SUT,
+	 * transforms the json to get a compact representation of the data
+	 * (a line for each object) suitable for display and test comparison
 	 */
 	protected String reserializeStoredData(String payload) {
 		return new Reserializer().reserializeData(payload);

st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/petstore/BasePetstore.java

@@ -7,8 +7,24 @@
 import giis.tdrules.store.loader.gen.DictionaryAttrGen;
 import test4giis.tdrules.tdg.st.test.BaseAll;
 
+/**
+ * Common configuration and customization for all Swagger Petstore tests.
+ * 
+ * There are two different set of test clases:
+ * 
+ * - Classes containing Petstore0 in the name: It is an initial 
+ *   proof of concept of of TDG using simplified entities (Pet0, Pet1...)
+ *   from the Swagger Petstore.
+ * - Classes containing Petstore in the name: They use the real
+ *   entities in the petstore OpenApi model.
+ *   
+ * The former tests (Petstore0) also serve to illustrate using examples the main 
+ * transformations performed on the model and the coverage rules.
+ * 
+ * Documentation is more exhaustive in TestPetstore0DatagenLocal and TestPetstore0DatagenLocal
+ * The others are the different flavour variants to include data generation and a live SUT
+ */
 public class BasePetstore  extends BaseAll{
-	//Para la generacion "live" arrancar antes el container de petstore con docker-run (asegurar tener el puerto 8081 libre)
 	protected static final String PETSTORE_SCHEMA_LOCAL = "../sut-petstore/src/main/resources/openapi.yaml";
 	protected static final String PETSTORE_SCHEMA_LIVE = "http://localhost:8081/api/v3/openapi.json";
 	private static final String PETSTORE_URL_LIVE = "http://localhost:8081/api/v3";
@@ -35,10 +51,10 @@ protected String getDeleteAllDataLiveEndpoint() {
 
 	@Override
 	protected TdSchema getSchema() {
-		// Configure the schema id resolver to use id attribute as uid, but there are exceptions:
+		// Configures the schema id resolver to use id attribute as uid, but there are exceptions:
 		// - Tag has an id, but looking at the source code, a post inserts unconditionally,
 		//   allowing repeated id values. Considers this id as no uid
-		// - Order0 has been artificially created for some tests, it does not follow strictely
+		// - Order0 has been created for some tests, it does not follow strictely
 		//   the conventions (attribute petId references Pet0.id)
 		OaSchemaApi api = new OaSchemaApi(PETSTORE_SCHEMA_LOCAL)
 				.setIdResolver(new OaSchemaIdResolver().setIdName("id")
@@ -47,8 +63,7 @@ protected TdSchema getSchema() {
 	}
 
 	/**
-	 * Instancia un generador de datos configurado con un diccionario para que los datos
-	 * generados no sean solo numeros, sino valores procedentes de un diccionario o mascaras
+	 * Dictionary to load more user friendly petstore data, includes values enumertions for strings and masks
 	 */
 	protected IAttrGen getDictionaryAttrGen() {
 		return new DictionaryAttrGen()

st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/petstore/TestPetstore0DatagenLive.java

@@ -0,0 +1,20 @@
+package test4giis.tdrules.tdg.st.test.petstore;
+
+/**
+ * Proof of concept of Test Data generation for APIs (TDG)
+ * using simplified entities from the Swagger Petstore.
+ * 
+ * Tests in this class simulate the data generation by specifying
+ * the commands sent to the Data Loader and load the data 
+ * in a running (live) SUT backend.
+ */
+public class TestPetstore0DatagenLive extends TestPetstore0DatagenLocal {
+
+	@Override
+	protected boolean isLiveBackend() {
+		return true;
+	}
+
+	// all test methods are inherited
+
+}