From 042189b73ddf2bf71f9ddc2ed7c18ae52994856d Mon Sep 17 00:00:00 2001
From: Filippo Ledda <filippo@metacell.us>
Date: Thu, 24 Aug 2023 09:43:19 +0200
Subject: [PATCH] #703 improve docs and code clarity

---
 docs/testing.md                               | 21 ++++++++++++++++++-
 .../cloudharness_test/api.py                  |  1 +
 .../cloudharness_test/apitest_init.py         |  2 ++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/docs/testing.md b/docs/testing.md
index ef37128a..27356fea 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -189,7 +189,7 @@ deployment.
 In order to use `harness-test` install the library with
 
 ```
-pip install -r requirements-test.txt
+pip install -e tools/cloudharness-test
 ```
 
 In order to run tests against an existing deployment based on a domain (say, my.domain), run:
@@ -205,6 +205,25 @@ If you want to run the deployment locally and then run the tests, can use skaffo
 1. Wait the deployment to settle
 1. Run `harness-test PATHS`
 
+### Tests development
+The `harness-test` client is useful while developing and tweaking the tests.
+In that case it's better to target the application under development and 
+the kind of tests we are working on.
+
+
+To target a specific application for end-to-end tests, use:
+```
+harness-test . -i [APPNAME] -e
+```
+
+To target a specific application for api tests, use:
+```
+harness-test . -i [APPNAME] -a
+```
+
+Note that the local version of the openapi.yaml file located at applications/[APPNAME]/api/openapi.yaml is used if available. That's useful to tweak examples and responses
+used by schemathesis to generate the test hypotheses.
+
 ## Create test users for your application
 
 To create test users:
diff --git a/tools/cloudharness-test/cloudharness_test/api.py b/tools/cloudharness-test/cloudharness_test/api.py
index e3c93ea5..5193902d 100644
--- a/tools/cloudharness-test/cloudharness_test/api.py
+++ b/tools/cloudharness-test/cloudharness_test/api.py
@@ -63,6 +63,7 @@ def run_api_tests(root_paths, helm_values: HarnessMainConfig, base_domain, inclu
             schema_file = f"applications/{app_config.name}/api/openapi.yaml"
 
             for path in root_paths:
+                # use local schema if available to simplify test development
                 if os.path.exists(os.path.join(path, schema_file)):
                     app_env["APP_SCHEMA_FILE"] = schema_file
 
diff --git a/tools/cloudharness-test/cloudharness_test/apitest_init.py b/tools/cloudharness-test/cloudharness_test/apitest_init.py
index 32772abd..1f83eabd 100644
--- a/tools/cloudharness-test/cloudharness_test/apitest_init.py
+++ b/tools/cloudharness-test/cloudharness_test/apitest_init.py
@@ -11,9 +11,11 @@
     app_url = os.environ.get("APP_URL", "http://samples.ch.local/api")
     logging.info("Start schemathesis tests on %s", app_url)
     if app_schema:
+        # Test locally with harness-test -- use local schema for convenience during test development
         openapi_uri = app_schema
         schema = st.from_file(openapi_uri)
     else:
+        # remote testing: might be /api/openapi.json or /openapi.json
         try:
             openapi_uri = openapi_uri = app_url + "/openapi.json"
             schema = st.from_uri(openapi_uri)