From fa62bc0e24ff0d798ffe928b9abce812a1a3898f Mon Sep 17 00:00:00 2001
From: Kristel <kristel.nieuwenhuijs@kramp.com>
Date: Sat, 28 Dec 2024 12:21:08 +0100
Subject: [PATCH] test, script and documentation improvements

---
 scripts/README.md                             | 33 ++++++++++++++++++
 scripts/mnv-clean-verify.sh                   |  2 ++
 scripts/mvn-clean-verify-site.sh              |  6 +++-
 scripts/mvn-verify-site.sh                    |  6 +++-
 scripts/mvn-verify.sh                         |  2 ++
 scripts/set-secrets.sh.example                |  3 ++
 scripts/test.sh                               |  3 ++
 tado-api-test/README.md                       | 25 ++++++++++++++
 .../tadoclient/apis/HomeControlApi_IT.kt      | 31 -----------------
 .../tadoclient/apis/ZoneControlApi_IT.kt      | 34 +++++++++++++++++++
 10 files changed, 112 insertions(+), 33 deletions(-)
 create mode 100644 scripts/set-secrets.sh.example
 create mode 100644 scripts/test.sh

diff --git a/scripts/README.md b/scripts/README.md
index e69de29..9e165ca 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -0,0 +1,33 @@
+# How to use the `mvn-*.sh` scripts
+
+## Execute from parent directory
+
+The scripts are set-up in a way that they are expected to be executed from their parent directory.
+
+Example: 
+
+`> ./scripts/mvn-clean-verify-site.sh`
+
+## Tado secrets required for integration tests
+
+The mvn scripts which include the `verify` goal execute the integration tests.
+These tests expect environment variables to be present which contain your tado username and password.
+
+1. Lookup your tado username and password
+2. In the `scripts` directory, create a file named `set-secrets.sh` which looks like this:
+   (see `set-secrets.sh.example` for an example)
+
+```
+#!/bin/bash
+export TADO_USERNAME='<fill in your tado username here>'
+export TADO_PASSWORD='<fill in your tado password here'
+```
+
+## Tado home, zone, etc. identifiers required for integration tests
+
+The mvn scripts which include the `verify` goal execute the integration tests.
+
+The tests use tado home, zone, etc. identifiers as specified in
+`tado-api-test/src/test/resources/application.yaml`
+
+You need to update those identifiers to execute the tests on your own home.
\ No newline at end of file
diff --git a/scripts/mnv-clean-verify.sh b/scripts/mnv-clean-verify.sh
index 764167a..b85e09a 100644
--- a/scripts/mnv-clean-verify.sh
+++ b/scripts/mnv-clean-verify.sh
@@ -1 +1,3 @@
+source ./scripts/set-secrets.sh
+
 mvn clean verify -P local-api-spec --file pom.xml
\ No newline at end of file
diff --git a/scripts/mvn-clean-verify-site.sh b/scripts/mvn-clean-verify-site.sh
index 380d2da..7cc6ef4 100644
--- a/scripts/mvn-clean-verify-site.sh
+++ b/scripts/mvn-clean-verify-site.sh
@@ -1 +1,5 @@
-mvn clean verify site -P local-api-spec --file pom.xml
\ No newline at end of file
+source ./scripts/set-secrets.sh
+
+mvn clean verify site -P local-api-spec --file pom.xml
+
+mvn site --file pom.xml
\ No newline at end of file
diff --git a/scripts/mvn-verify-site.sh b/scripts/mvn-verify-site.sh
index 3603dd6..2dd8168 100644
--- a/scripts/mvn-verify-site.sh
+++ b/scripts/mvn-verify-site.sh
@@ -1 +1,5 @@
-mvn verify site site:stage -P local-api-spec --file pom.xml
\ No newline at end of file
+source ./scripts/set-secrets.sh
+
+mvn verify -P local-api-spec --file pom.xml
+
+mvn site --file pom.xml
\ No newline at end of file
diff --git a/scripts/mvn-verify.sh b/scripts/mvn-verify.sh
index e8a1af1..5137b02 100644
--- a/scripts/mvn-verify.sh
+++ b/scripts/mvn-verify.sh
@@ -1 +1,3 @@
+source ./scripts/set-secrets.sh
+
 mvn verify -P local-api-spec --file pom.xml
\ No newline at end of file
diff --git a/scripts/set-secrets.sh.example b/scripts/set-secrets.sh.example
new file mode 100644
index 0000000..a3c0e5f
--- /dev/null
+++ b/scripts/set-secrets.sh.example
@@ -0,0 +1,3 @@
+#!/bin/bash
+export TADO_USERNAME='<fill in>'
+export TADO_PASSWORD='<fill in>'
\ No newline at end of file
diff --git a/scripts/test.sh b/scripts/test.sh
new file mode 100644
index 0000000..0b7ccad
--- /dev/null
+++ b/scripts/test.sh
@@ -0,0 +1,3 @@
+source ./scripts/set-secrets.sh
+
+echo $TADO_USERNAME
\ No newline at end of file
diff --git a/tado-api-test/README.md b/tado-api-test/README.md
index 2ecf86d..e86cbe2 100644
--- a/tado-api-test/README.md
+++ b/tado-api-test/README.md
@@ -4,3 +4,28 @@ This module is the test harness for the tado API spec.
 The goal is to verify whether the API spec is a correct description 
 of the actual tado API by executing API calls using an API client which is
 generated from the tado API spec.
+
+## Tado secrets required for integration tests
+
+The test set-up expects environment variables to be present which contain your tado username and password.
+
+You can do this with a script like this:
+```
+#!/bin/bash
+export TADO_USERNAME='<fill in your tado username here>'
+export TADO_PASSWORD='<fill in your tado password here'
+```
+
+## Tado home, zone, etc. identifiers required for integration tests
+
+The tests use tado home, zone, etc. identifiers as specified in
+`tado-api-test/src/test/resources/application.yaml`
+
+You need to update those identifiers to execute the tests on your own home.
+
+## Run the tests
+
+You can use the following mvn command to run the tests
+(run it from the `tado-openapi-spec-v2` parent directory)
+
+`> mvn clean verify -P local-api-spec`
\ No newline at end of file
diff --git a/tado-api-test/src/test/kotlin/tadoclient/apis/HomeControlApi_IT.kt b/tado-api-test/src/test/kotlin/tadoclient/apis/HomeControlApi_IT.kt
index e258c46..fc566e0 100644
--- a/tado-api-test/src/test/kotlin/tadoclient/apis/HomeControlApi_IT.kt
+++ b/tado-api-test/src/test/kotlin/tadoclient/apis/HomeControlApi_IT.kt
@@ -97,37 +97,6 @@ class HomeControlApi_IT(
 
     }
 
-    @Test
-    @DisplayName("POST /homes/{homeId}/overlay")
-    @Order(10)
-    @EnabledIf(value = "isHomeConfigured", disabledReason = "no home specified in tado set-up")
-    fun setZoneOverlays() {
-        val newZoneOverlay = ZoneOverlay(
-            setting = ZoneSetting(
-                type = ZoneType.HEATING,
-                power = Power.ON,
-                temperature = Temperature(celsius = 16f)
-            ),
-            termination = ZoneOverlayTermination(
-                typeSkillBasedApp = ZoneOverlayTerminationTypeSkillBasedApp.TIMER,
-                durationInSeconds = 120
-            )
-        )
-        val result = assertCorrectResponse {
-            tadoStrictHomeControlAPI.setZoneOverlays(tadoConfig.home!!.id, ZoneOverlays(listOf(ZoneOverlaysOverlaysInner(tadoConfig.zone!!.heating!!.id.toString(), newZoneOverlay))) )
-        }
-        assertEquals(Unit, result)
-    }
-
-    @Test
-    @DisplayName("DELETE /homes/{homeId}/overlay")
-    @Order(20)
-    @EnabledIf(value = "isHomeConfigured", disabledReason = "no home specified in tado set-up")
-    fun deleteZoneOverlays() {
-        val result = assertCorrectResponse { tadoStrictHomeControlAPI.deleteZoneOverlays(tadoConfig.home!!.id, rooms = listOf(tadoConfig.zone!!.heating!!.id) ) }
-        assertEquals(Unit, result)
-    }
-
     @Test
     @DisplayName("PUT /homes/{homeId}/presenceLock")
     @Order(30)
diff --git a/tado-api-test/src/test/kotlin/tadoclient/apis/ZoneControlApi_IT.kt b/tado-api-test/src/test/kotlin/tadoclient/apis/ZoneControlApi_IT.kt
index 395472b..e8e63a3 100644
--- a/tado-api-test/src/test/kotlin/tadoclient/apis/ZoneControlApi_IT.kt
+++ b/tado-api-test/src/test/kotlin/tadoclient/apis/ZoneControlApi_IT.kt
@@ -112,6 +112,40 @@ class ZoneControlApi_IT(
         }
     }
 
+    @Test
+    @DisplayName("POST /homes/{homeId}/overlay")
+    @Order(4)
+//    @EnabledIf(value = "isHomeConfigured", disabledReason = "no home specified in tado set-up")
+    @Disabled("needs additional test set-up to revert back to the pre-test situation")
+    fun setZoneOverlays() {
+        val newZoneOverlay = ZoneOverlay(
+            setting = ZoneSetting(
+                type = ZoneType.HEATING,
+                power = Power.ON,
+                temperature = Temperature(celsius = 16f)
+            ),
+            termination = ZoneOverlayTermination(
+                typeSkillBasedApp = ZoneOverlayTerminationTypeSkillBasedApp.TIMER,
+                durationInSeconds = 120
+            )
+        )
+        val result = assertCorrectResponse {
+            tadoStrictZoneControlAPI.setZoneOverlays(tadoConfig.home!!.id, ZoneOverlays(listOf(ZoneOverlaysOverlaysInner(tadoConfig.zone!!.heating!!.id.toString(), newZoneOverlay))) )
+        }
+        assertEquals(Unit, result)
+    }
+
+    @Test
+    @DisplayName("DELETE /homes/{homeId}/overlay")
+    @Order(7)
+//    @EnabledIf(value = "isHomeConfigured", disabledReason = "no home specified in tado set-up")
+    @Disabled("needs additional test set-up to revert back to the pre-test situation")
+    fun deleteZoneOverlays() {
+        val result = assertCorrectResponse { tadoStrictZoneControlAPI.deleteZoneOverlays(tadoConfig.home!!.id, rooms = listOf(tadoConfig.zone!!.heating!!.id) ) }
+        assertEquals(Unit, result)
+    }
+
+
     @Test
     @DisplayName("GET /homes/{homeId}/zones/{zoneId}/earlyStart")
     @Order(10)