#703 improve docs and code clarity

Author: filippomc

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:

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
 

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)