Clarify --test functionality for kontrol prove (#88)

* improve messages

* tweak error message

* Set Version: 0.1.21

* method -> function

---------

Co-authored-by: devops <devops@runtimeverification.com>

package/version

@@ -1 +1 @@
-0.1.20
+0.1.21

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "kontrol"
-version = "0.1.20"
+version = "0.1.21"
 description = "Foundry integration for KEVM"
 authors = [
     "Runtime Verification, Inc. <contact@runtimeverification.com>",

src/kontrol/__init__.py

@@ -5,4 +5,4 @@
 if TYPE_CHECKING:
     from typing import Final
 
-VERSION: Final = '0.1.20'
+VERSION: Final = '0.1.21'

src/kontrol/__main__.py

@@ -492,7 +492,11 @@ def _parse_test_version_tuple(value: str) -> tuple[str, int | None]:
         dest='tests',
         default=[],
         action='append',
-        help='Limit to only listed tests, ContractName.TestName',
+        help=(
+            "Specify the contract function to test in the format 'ContractName.FunctionName'. If a function is "
+            "overloaded, you should specify the full signature, e.g., 'ERC20Test.testTransfer(address,uint256)'. This "
+            'option can be used multiple times to test multiple functions.'
+        ),
     )
     prove_args.add_argument(
         '--reinit',

src/kontrol/foundry.py

@@ -253,18 +253,14 @@ def _escape_brackets(regs: list[str]) -> list[str]:
     def matching_tests(self, tests: list[str]) -> list[str]:
         all_tests = self.all_tests
         all_non_tests = self.all_non_tests
-        matched_tests = set()
-        unfound_tests: list[str] = []
         tests = self._escape_brackets(tests)
-        for t in tests:
-            if not any(re.search(t, test) for test in (all_tests + all_non_tests)):
-                unfound_tests.append(t)
-        for test in all_tests:
-            if any(re.search(t, test) for t in tests):
-                matched_tests.add(test)
-        for test in all_non_tests:
-            if any(re.search(t, test) for t in tests):
-                matched_tests.add(test)
+        matched_tests = set()
+        unfound_tests = set(tests)
+        for test in tests:
+            for possible_match in all_tests + all_non_tests:
+                if re.search(test, possible_match):
+                    matched_tests.add(possible_match)
+                    unfound_tests.discard(test)
         if unfound_tests:
             raise ValueError(f'Test identifiers not found: {set(unfound_tests)}')
         elif len(matched_tests) == 0:
@@ -274,7 +270,10 @@ def matching_tests(self, tests: list[str]) -> list[str]:
     def matching_sig(self, test: str) -> str:
         test_sigs = self.matching_tests([test])
         if len(test_sigs) != 1:
-            raise ValueError(f'Found {test_sigs} matching tests, must specify one')
+            raise ValueError(
+                f'Multiple matches found for {test}. Please specify using the full signature, e.g., {test_sigs[0]!r}.\n'
+                + 'Signatures found: {test_sigs}'
+            )
         return test_sigs[0]
 
     def unique_sig(self, test: str) -> tuple[str, str]: