From 2f44242659e7a9557af87a220416e8447372cccf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mar=C3=ADa=20Jos=C3=A9?= <cabal@uniovi.es>
Date: Tue, 3 Sep 2024 11:50:20 +0200
Subject: [PATCH] Review market tests documentation

---
 .../tdg/st/test/market/BaseMarket.java        | 52 ++++++++++--------
 .../st/test/market/TestMarketFuncCarts.java   | 33 +++++-------
 .../test/market/TestMarketFuncProducts.java   | 45 ++++++++--------
 .../market/TestMarketQagrowLiveBackId.java    | 54 -------------------
 .../st/test/market/TestMarketQagrowLocal.java |  5 +-
 .../st/test/market/TestMarketSchemaLocal.java |  3 +-
 ...RegionByName.txt => func-RegionByName.txt} |  0
 .../qagrow-livebackid-DistilleryByRegion.txt  |  4 --
 .../qagrow-livebackid-DistilleryByTitle.txt   |  3 --
 9 files changed, 69 insertions(+), 130 deletions(-)
 delete mode 100644 st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLiveBackId.java
 rename st-tdg-test/src/test/resources/market/{qagrow-livebackid-RegionByName.txt => func-RegionByName.txt} (100%)
 delete mode 100644 st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByRegion.txt
 delete mode 100644 st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByTitle.txt

diff --git a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/BaseMarket.java b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/BaseMarket.java
index 63f72d9..263d053 100644
--- a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/BaseMarket.java
+++ b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/BaseMarket.java
@@ -20,17 +20,23 @@
 import giis.tdrules.store.loader.oa.OaPathResolver;
 import test4giis.tdrules.tdg.st.test.BaseAll;
 
+/**
+ * Common configuration and customization for all Market tests that use entities in its OpenApi model.
+ */
 public class BaseMarket extends BaseAll {
 	protected static final String MARKET_SCHEMA_LOCAL = "../sut-market/src/main/resources/marketWithoutArrays.json";
 	private static final String MARKET_URL_LIVE = "http://localhost:8083";
-	
+
+	// attributes that can be filtered during comparisons of assertions 
 	private static final String[] FILTERED_ATTRS = {"password", "dateCreated","number"};
 
+	public static String queryCartByUser = "tds CartDTO where user='lucia@email.com'";
+	public static String queryCartByUserProductQuantity = "tds CartDTO,CartItemDTORes,ProductDTORes where CartDTO.user='pepe@email.com' and CartItemDTORes.productId=1 and CartItemDTORes.quantity=5 and ProductDTORes.available=1";
+	public static String queryOrderByUser = "tds OrderDTO where userAccount='pepe@email.com' ";
 	public static String queryProductByAge = "tds ProductDTORes where age=10";
 	public static String queryUserByName = "tds UserDTORes where name='Pepe'";
 	public static String queryUserByEmail = "tds UserDTORes where email ='pepe@email.com'";
-	public static String queryCartByUserProductQuantity = "tds CartDTO,CartItemDTORes,ProductDTORes where CartDTO.user='pepe@email.com' and CartItemDTORes.productId=1 and CartItemDTORes.quantity=5 and ProductDTORes.available=1";
-		
+	
 	@Override
 	protected String getSutName() {
 		return "market";
@@ -54,9 +60,9 @@ protected String getDeleteAllDataLiveEndpoint() {
 	@Override
 	protected TdSchema getSchema() {
 		// Configure:
-		// filter entities Link* and attributes _link*, and
-		// the schema id resolver to use id attributes as uid and
-		// not to use productId as product.id in entities CartItem and ProductDTO	
+		// - filter entities Link* and attributes _link*
+		// - the schema id resolver to use id attributes as uid 
+		//   except in entities CartItemDTO (pk are user + productId) and ProductDTO (pk is productId)	
 		OaSchemaApi api = new OaSchemaApi(MARKET_SCHEMA_LOCAL)
 				.setFilter(new OaSchemaFilter()
 						.add("*", "_link*")
@@ -69,15 +75,16 @@ protected TdSchema getSchema() {
 				;
 		return api.getSchema();
 	}
-
-	/**
-	 * Instancia un generador utilizando un Adaptador para Openapi que genera los datos directamente a traves del api
-	 * El path resolver se configura con la url donde extraer los paths de los endpoints de LiveBackId.
-	 * La generación de las claves se realiza en el backend (UidGen), las columnas (AttrGen) se generan de forma determinista.
-	 * Se utliza  diccionario para la generación de columnas (getDictionaryAttrGen)
-	 */	
+	
 	@Override
 	protected DataLoader getLiveDataLoader() {
+		// Generator with a custom path resolver injected:
+		// * Get uids from the backend
+		// * Include an authenticator:
+		//   - The provider is the entity userDTOReq storing credential in email and password attributes
+		//   - Consumers are entities CartItemDTO and ContactsDTO (username is user attribute) and 
+		//     OrderDTO (username is userAccount attribute)
+		// * Use a dictionary
 		TdSchema model = getSchema();
 		IPathResolver pathResolver=new CustomPathResolver().setServerUrl(MARKET_URL_LIVE);
 		OaBasicAuthStore authenticator = new OaBasicAuthStore()
@@ -91,12 +98,12 @@ protected DataLoader getLiveDataLoader() {
 				                            .setAttrGen(getDictionaryAttrGen());
 	}
 	
-	/**
-	 * 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
-	 * Para tarjetas de crédito: https://dev.na.bambora.com/docs/references/payment_APIs/test_cards/
-	 */
 	protected IAttrGen getDictionaryAttrGen() {
+		// Dictionary configured for:
+		// - UserDTO (attributes email, name, password, phone)
+		// - DistilleryDTO (attribute title)
+		// - RegionDTO (attribute name)
+		// - CreditCardDTO (attribute ccNumber, source https://dev.na.bambora.com/docs/references/payment_APIs/test_cards/)
 		return new DictionaryAttrGen()
 				.with("UserDTORes", "email").padLeft('0', 2).mask("us{}@email.com")
 				.with("UserDTOReq", "email").padLeft('0', 2).mask("us{}@email.com")
@@ -119,7 +126,7 @@ protected IAttrGen getDictionaryAttrGen() {
 	protected void assertLiveData(String fileName, DataLoader dg) {
 		String dataLive = getAllLiveData();
 		log.info("Actual data stored in the backend\n{}", reserializeStoredData(dataLive));
-		// antes de comparar, se deben filtrar los atributos que no se quieren comparar
+		// before comparing, filter attributes
 		super.assertModel(fileName, filterAttributes(dataLive,FILTERED_ATTRS));  
 	}
 	
@@ -140,7 +147,7 @@ private String filterAttributes(String strJson, String... ignoreAttributes) {
 		return reserializeStoredData(sb.toString());
     }
 	
-	// actualiza json eliminando attributeName y su valor en todas las apariciones 
+	// update json deleting attributeName and its value  
 	private void removeAttribute(JsonNode node, String attributeName) {
         if (node.isObject()) {
             ObjectNode objectNode = (ObjectNode) node;
@@ -151,11 +158,11 @@ private void removeAttribute(JsonNode node, String attributeName) {
         }
     }
 	
-	//los endpoints estan bajo el path backid
+	// Use the appropiate endpoint depending on the entity
 	public class CustomPathResolver extends OaPathResolver {
 		@Override
 		public String getEndpointPath(String tableName) {
-			//Eliminacion de Req o Res en las llamadas a los endpoints
+			//Removing Req or Res from the endpoints
 			String table = tableName.split("Re(s|q)")[0];
 			if ("CartDTO".equals(table))
 				return null;
@@ -173,6 +180,7 @@ else if ("OrderDTO".equals(table))
 				return super.getEndpointPath(table);
 		}
 		
+		// Endpoint using PUT instead of POST for entity CartItemDTO
 		@Override public boolean usePut(String tableName) {
 			String table = tableName.split("Re(s|q)")[0];
 			return "CartItemDTO".equals(table);
diff --git a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncCarts.java b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncCarts.java
index 0e038d0..e939fc7 100644
--- a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncCarts.java
+++ b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncCarts.java
@@ -6,8 +6,10 @@
 import giis.tdrules.store.loader.IAttrGen;
 
 /**
- * Tests de funcionalidad de Carts
- * Generación: QAGrow y claves se realiza en el backend
+ * Carts Functionality Tests.
+ * - Use the live SUT where the uids of each generated object are generated by the backend.
+ * - Use the dictionary
+ * - Include Users, Carts and Orders
  */
 public class TestMarketFuncCarts extends BaseMarket {
 	
@@ -18,6 +20,7 @@ protected boolean isLiveBackend() {
 	
 	@Test
 	public void testDictUserDTOResByName() {
+		// users
 		String query = queryUserByName;
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -25,29 +28,20 @@ public void testDictUserDTOResByName() {
 		assertData("func-UsersByName.txt", dg);
 	}
 
-	/*
-	 * Inserta carts pero no items ni productos. Para cubrir las reglas de cobertura no son necesarios
-	 * Son carts vacíos. 
-	 */
 	@Test
 	public void testDictCartDTOByUser() {
-		String query = "tds CartDTO where user='lucia@email.com'";
+		// empty carts
+		String query = queryCartByUser;
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
 		generateAndLoad(dg, query, dict);
 		assertData("func-CartsByUser.txt", dg);
 	}
 	
-	/* Inserta carts y sus items.
-	 * Para que se inserte un producto en un carrito, debe estar disponible, necesario incluirlo en la query.
-	 * Si no se indica en la query, se genera por DataGenerator y es no disponible (available = false),
-	 * entonces al intentar añadirlo via api, no se inserta en la tabla (lo que es correcto)
-	 * Hay otra regla de cobertura que no se cubre con una única base de datos:
-	 * - user='lucia...' and productId=1 and quantity != 5
-	 * En este caso, desde QAGrow ya no se generan los datos.
-	 */
 	@Test
 	public void testDictCartDTOByUserProductQuantity() {
+		// carts and items
+		// products must be available
 		String query = queryCartByUserProductQuantity;
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -55,14 +49,13 @@ public void testDictCartDTOByUserProductQuantity() {
 		assertData("func-CartsByUserProductQuantity.txt", dg);
 	}
 	
-	/* Inserta order a un usuario.
-	 * Para que cree una order, el carrito no puede estar vacio.
-	 * Por tanto, habrá una query1 para generar carritos con productos y query2 para generar la orden del carrito
-	 */
 	@Test
 	public void testOrderDTOByUser() {
+		// order (cart must not be empty)
+		// query 1 generates a non-empty cart, 
+		// query 2 generates the order
 		String query1= queryCartByUserProductQuantity;
-		String query2 = "tds OrderDTO where userAccount='pepe@email.com' ";
+		String query2 = queryOrderByUser;
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
 		generateAndLoad(dg, new String[] {query1, query2}, dict);
diff --git a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncProducts.java b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncProducts.java
index fbab485..86f3446 100644
--- a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncProducts.java
+++ b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketFuncProducts.java
@@ -5,8 +5,10 @@
 import giis.tdrules.store.loader.IAttrGen;
 
 /**
- * Tests de funcionalidad de Products
- * Generación: QAGrow y claves se realiza en el backend
+ * Products Functionality Tests
+ * - Use the live SUT where the uids of each generated object are generated by the backend.
+ * - Use the dictionary
+ * - Include Products, Distilleries and Regions
  */
 public class TestMarketFuncProducts extends BaseMarket {
 
@@ -15,11 +17,9 @@ protected boolean isLiveBackend() {
 		return true;
 	}
 	
-	/**
-	 * Todos los productos de una destileria
-	 */
 	@Test
 	public void testProductsByDistillery() {
+		// products of a distillery
 		String query =  "tds ProductDTOReq where distillery ='Ardbeg'";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -27,12 +27,9 @@ public void testProductsByDistillery() {
 		assertData("func-ProductsByDistillery.txt", dg);
 	}
 
-	
-	/**
-	 * Productos de una destileria disponibles
-	 */
 	@Test
 	public void testProductsByDistilleryAvaliable() {
+		// available products of a distillery 
 		String query =  "tds ProductDTOReq where distillery ='Ardbeg' and available = 1";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -40,11 +37,9 @@ public void testProductsByDistilleryAvaliable() {
 		assertData("func-ProductsByDistilleryAvailable.txt", dg);
 	}
 	
-	/**
-	 * Todos los productos de una destileria no disponibles
-	 */
 	@Test
 	public void testProductsByDistilleryNotAvailable() {
+		// non-available products of a distillery
 		String query =  "tds ProductDTOReq where distillery ='Ardbeg' and available = 0";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -52,11 +47,9 @@ public void testProductsByDistilleryNotAvailable() {
 		assertData("func-ProductsByDistilleryNotAvailable.txt", dg);
 	}
 	
-	/**
-	 * Productos de una destileria disponibles entre dos precios
-	 */
 	@Test
 	public void testProductsByDistilleryPrice() {
+		// available products of a distillery, price between two values
 		String query =  "tds ProductDTOReq where distillery ='Ardbeg' and price < 100 and price > 5";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -64,11 +57,9 @@ public void testProductsByDistilleryPrice() {
 		assertData("func-ProductsByDistilleryPrice.txt", dg);
 	}
 	
-	/**
-	 * Productos de una destileria disponibles entre dos precios
-	 */
 	@Test
 	public void testProductsByDistilleryPriceAge() {
+		// available products of a distillery and an age, price between two values
 		String query =  "tds ProductDTOReq where distillery ='Ardbeg' and price < 100 and price > 5 and age = 12";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -77,11 +68,9 @@ public void testProductsByDistilleryPriceAge() {
 	}
 	
 	
-	/**
-	 * Prueba de generacion de distillery y region con claves en el backend, fijando distillery.title
-	 */
 	@Test
 	public void testDistilleryByTitle() {
+		// distillery 
 		String query =  "tds DistilleryDTOReq where title ='Ardbeg'";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
@@ -89,16 +78,24 @@ public void testDistilleryByTitle() {
 		assertData("func-DistilleryByTitle.txt", dg);
 	}
 	
-	/**
-	 * Prueba de generacion de distillery y region con claves en el backend, fijando distillery.region (region es maestro de distillery)
-	 */
 	@Test
 	public void testDistilleryByRegion() {
+		// distillery of a region
 		String query =  "tds DistilleryDTOReq where region ='Islay'";
 		IAttrGen dict=getDictionaryAttrGen();
 		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
 		generateAndLoad(dg, query, dict);
 		assertData("func-DistilleryByRegion.txt", dg);
 	}
+	
+	@Test
+	public void testRegionByName() {
+		// region
+		String query =  "tds RegionDTOReq where name ='Campbeltown'";
+		IAttrGen dict=getDictionaryAttrGen();
+		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
+		generateAndLoad(dg, query, dict);
+		assertData("func-RegionByName.txt", dg);
+	}
 
 }
diff --git a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLiveBackId.java b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLiveBackId.java
deleted file mode 100644
index 37d73d9..0000000
--- a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLiveBackId.java
+++ /dev/null
@@ -1,54 +0,0 @@
-package test4giis.tdrules.tdg.st.test.market;
-
-import org.junit.Test;
-import giis.tdrules.store.loader.DataLoader;
-import giis.tdrules.store.loader.IAttrGen;
-
-/**
- * Tests para generacion de datos con QAGrow
- * Las generacion de claves se realiza en el backend
- */
-public class TestMarketQagrowLiveBackId extends BaseMarket {
-
-	@Override
-	protected boolean isLiveBackend() {
-		return true;
-	}
-	
-	/**
-	 * Prueba de generacion de regiones con claves en el backend
-	 */
-	@Test
-	public void testRegionByName() {
-		String query =  "tds RegionDTOReq where name ='Campbeltown'";
-		IAttrGen dict=getDictionaryAttrGen();
-		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
-		generateAndLoad(dg, query, dict);
-		assertData("qagrow-livebackid-RegionByName.txt", dg);
-	}
-
-	/**
-	 * Prueba de generacion de distillery y region con claves en el backend, fijando distillery.title
-	 */
-	@Test
-	public void testDistilleryByTitle() {
-		String query =  "tds DistilleryDTOReq where title ='Balvenie'";
-		IAttrGen dict=getDictionaryAttrGen();
-		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
-		generateAndLoad(dg, query, dict);
-		assertData("qagrow-livebackid-DistilleryByTitle.txt", dg);
-	}
-	
-	/**
-	 * Prueba de generacion de distillery y region con claves en el backend, fijando distillery.region (region es maestro de distillery)
-	 */
-	@Test
-	public void testDistilleryByRegion() {
-		String query =  "tds DistilleryDTOReq where region ='Highland'";
-		IAttrGen dict=getDictionaryAttrGen();
-		DataLoader dg = getLiveDataLoader().setAttrGen(dict);
-		generateAndLoad(dg, query, dict);
-		assertData("qagrow-livebackid-DistilleryByRegion.txt", dg);
-	}
-
-}
diff --git a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLocal.java b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLocal.java
index 0636325..da364ab 100644
--- a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLocal.java
+++ b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketQagrowLocal.java
@@ -5,9 +5,10 @@
 import giis.tdrules.store.loader.DataLoader;
 
 /**
- * Generacion de datos para Market utilizando QAGrow.
- * Utiliza un un esquema y un DataAdapter local, que no requiere una conexion activa a un servidor.
+ * Generates test data for a given query using QAGrow and loads
+ * the data as indicated by the local specified data loader
  */
+
 public class TestMarketQagrowLocal extends BaseMarket {
 
 	@Test
diff --git a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketSchemaLocal.java b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketSchemaLocal.java
index be854a8..c8ac4b8 100644
--- a/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketSchemaLocal.java
+++ b/st-tdg-test/src/test/java/test4giis/tdrules/tdg/st/test/market/TestMarketSchemaLocal.java
@@ -9,7 +9,8 @@
 import giis.tdrules.openapi.model.TdSchema;
 
 /**
- * Genera el esquema a partir de la especificacion (leida de archivo) y lo comprueba en formato json y xml
+ * Checks the transformation of the OpenApi specification into the TdSchema model
+ * (json, xml and Mermaid graph)
  */
 public class TestMarketSchemaLocal extends BaseMarket {
 
diff --git a/st-tdg-test/src/test/resources/market/qagrow-livebackid-RegionByName.txt b/st-tdg-test/src/test/resources/market/func-RegionByName.txt
similarity index 100%
rename from st-tdg-test/src/test/resources/market/qagrow-livebackid-RegionByName.txt
rename to st-tdg-test/src/test/resources/market/func-RegionByName.txt
diff --git a/st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByRegion.txt b/st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByRegion.txt
deleted file mode 100644
index 90ec85b..0000000
--- a/st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByRegion.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-"distillery":{"id":1,"title":"Ardbeg","region":{"id":1,"name":"Campbeltown","subtitle":"5","description":"3","color":"2"},"description":"203"}
-"distillery":{"id":2,"title":"Balvenie","region":{"id":2,"name":"Highland","subtitle":"105","description":"103","color":"102"},"description":"303"}
-"region":{"id":1,"name":"Campbeltown","subtitle":"5","description":"3","color":"2"}
-"region":{"id":2,"name":"Highland","subtitle":"105","description":"103","color":"102"}
diff --git a/st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByTitle.txt b/st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByTitle.txt
deleted file mode 100644
index 9d632c2..0000000
--- a/st-tdg-test/src/test/resources/market/qagrow-livebackid-DistilleryByTitle.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-"distillery":{"id":1,"title":"Ardbeg","region":{"id":1,"name":"Campbeltown","subtitle":"5","description":"3","color":"2"},"description":"103"}
-"distillery":{"id":2,"title":"Balvenie","region":{"id":1,"name":"Campbeltown","subtitle":"5","description":"3","color":"2"},"description":"203"}
-"region":{"id":1,"name":"Campbeltown","subtitle":"5","description":"3","color":"2"}