test, script and documentation improvements

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.

scripts/mnv-clean-verify.sh

@@ -1 +1,3 @@
+source ./scripts/set-secrets.sh
+
 mvn clean verify -P local-api-spec --file pom.xml

scripts/mvn-clean-verify-site.sh

@@ -1 +1,5 @@
-mvn clean verify site -P local-api-spec --file pom.xml
+source ./scripts/set-secrets.sh
+
+mvn clean verify site -P local-api-spec --file pom.xml
+
+mvn site --file pom.xml

scripts/mvn-verify-site.sh

@@ -1 +1,5 @@
-mvn verify site site:stage -P local-api-spec --file pom.xml
+source ./scripts/set-secrets.sh
+
+mvn verify -P local-api-spec --file pom.xml
+
+mvn site --file pom.xml

scripts/mvn-verify.sh

@@ -1 +1,3 @@
+source ./scripts/set-secrets.sh
+
 mvn verify -P local-api-spec --file pom.xml

scripts/set-secrets.sh.example

@@ -0,0 +1,3 @@
+#!/bin/bash
+export TADO_USERNAME='<fill in>'
+export TADO_PASSWORD='<fill in>'

scripts/test.sh

@@ -0,0 +1,3 @@
+source ./scripts/set-secrets.sh
+
+echo $TADO_USERNAME

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`

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)

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)