clarify service address option (#42)

the service address param must be specified in such a way that it can be
reached from the checker.

If e.g. the service is reachable from the host at localhost:1234,
specifying service address=localhost won't work since from the checkers
perspective, "localhost" refers to the checkers loopback interface (as
opposed to the hosts)

Instead we need the ip addr of the services' docker network.

README.md

@@ -5,19 +5,28 @@ Automatically test services/checker using the enochecker API
 `enochecker_test` can be used to run tests against a checker, optionally you can specify wich tests to run e.g. `enochecker_test test_getflag[0] test_exploit_per_exploit_id` will run only the first `getflag` test and all `exploit_per_exploit_id` tests.
 
 ```
-usage: enochecker_test [-h] [-a CHECKER_ADDRESS] [-p {1..65535}] [-A SERVICE_ADDRESS] [testcase ...]
+usage: enochecker_test [-h] [-a CHECKER_ADDRESS] [-p {1..65535}] [-A SERVICE_ADDRESS] [testcase [testcase ...]]
 
 Utility for testing checkers that implement the enochecker API
 
 positional arguments:
   testcase              Specify the tests that should be run in the syntax expected by pytest, e.g. test_getflag. If no test is specified, all tests will be run.
 
-options:
+optional arguments:
   -h, --help            show this help message and exit
   -a CHECKER_ADDRESS, --checker-address CHECKER_ADDRESS
                         The address on which the checker is listening (defaults to the ENOCHECKER_TEST_CHECKER_ADDRESS environment variable)
   -p {1..65535}, --checker-port {1..65535}
                         The port on which the checker is listening (defaults to ENOCHECKER_TEST_CHECKER_PORT environment variable)
   -A SERVICE_ADDRESS, --service-address SERVICE_ADDRESS
-                        The address on which the service is listening (defaults to ENOCHECKER_TEST_SERVICE_ADDRESS environment variable)
-```
+                        The address on which the checker can reach the service (defaults to ENOCHECKER_TEST_SERVICE_ADDRESS environment variable)
+
+Example Usage:
+
+    $ enochecker_test -a localhost -p 5008 -A 172.20.0.1 test_putflag
+
+Assuming that 172.20.0.1 is the ip address of the gateway of the network of the
+service's docker container as obtained by e.g:
+
+    $ docker network inspect service_default | jq ".[].IPAM.Config[].Gateway"
+```

enochecker_test/main.py

@@ -60,7 +60,18 @@ def run_tests(host, port, service_address, test_methods):
 def main():
     parser = argparse.ArgumentParser(
         prog="enochecker_test",
+        # don't reformat but use description and epilog verbatim
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Utility for testing checkers that implement the enochecker API",
+        epilog="""Example Usage:
+
+    $ enochecker_test -a localhost -p 5008 -A 172.20.0.1 test_putflag
+
+Assuming that 172.20.0.1 is the ip address of the gateway of the network of the
+service's docker container as obtained by e.g:
+
+    $ docker network inspect service_default | jq ".[].IPAM.Config[].Gateway"
+""",
     )
     parser.add_argument(
         "-a",
@@ -80,7 +91,7 @@ def main():
     parser.add_argument(
         "-A",
         "--service-address",
-        help="The address on which the service is listening (defaults to ENOCHECKER_TEST_SERVICE_ADDRESS environment variable)",
+        help="The address on which the checker can reach the service (defaults to ENOCHECKER_TEST_SERVICE_ADDRESS environment variable)",
         default=os.environ.get("ENOCHECKER_TEST_SERVICE_ADDRESS"),
     )
     parser.add_argument(