genlayer-test 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

{genlayer_test-0.1.3.dist-info → genlayer_test-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: genlayer-test
-Version: 0.1.3
+Version: 0.2.0
 Summary: GenLayer Testing Suite
 Author: GenLayer
 License-Expression: MIT

{genlayer_test-0.1.3.dist-info → genlayer_test-0.2.0.dist-info}/RECORD

@@ -1,21 +1,23 @@
-genlayer_test-0.1.3.dist-info/licenses/LICENSE,sha256=che_H4vE0QUx3HvWrAa1_jDEVInift0U6VO15-QqEls,1064
+genlayer_test-0.2.0.dist-info/licenses/LICENSE,sha256=che_H4vE0QUx3HvWrAa1_jDEVInift0U6VO15-QqEls,1064
 gltest/__init__.py,sha256=AK_YfRvwlhrOheOelUG8qIRG17on0-nFCF747dopg2w,332
 gltest/assertions.py,sha256=0dEk0VxcHK4I7GZPHxJmz-2jaA60V499gOSR74rZbfM,1748
 gltest/exceptions.py,sha256=deJPmrTe5gF33qkkKF2IVJY7lc_knI7Ql3N7jZ8aLZs,510
 gltest/plugin_config.py,sha256=8Z97RtEJ89OcRbki_oRuBBVct_q56BFmKvthan1y9Y4,840
 gltest/plugin_hooks.py,sha256=py1rzIR9QSsFOt8SEePPL96e-8DeiPFxvcPZurRlExM,1436
 gltest/types.py,sha256=BODmwTr2gAUEiO9FjiuTiWwuKvXgo4xZWstQWNUfnlw,156
-gltest/artifacts/__init__.py,sha256=qiJN5F1cVh_3fmxZeDFznoABxAdLhLqBfUUKwqXqvgo,87
-gltest/artifacts/contract.py,sha256=0Sp8YTKBw7hwuhIQ7Q-PnchxNfusF0HNAcWaWPWT9Cg,3570
+gltest/artifacts/__init__.py,sha256=qTt3TE19gVNWnQLUlt5aDe4nNvJ2YJ1jzDkMmYIsCG0,194
+gltest/artifacts/contract.py,sha256=jqdsJD9B4aUTpR4EODHaag5j-IvdWm3Ac4ektbpTxFo,6152
 gltest/glchain/__init__.py,sha256=X-mEbREoAOe9K4n74C55gCiXH4wItzY5HTJcg3_F3mI,412
 gltest/glchain/account.py,sha256=ZxYsfbtBXKVC5vV4pko3yyL6lhPljqIb68NgIgvInSc,403
 gltest/glchain/client.py,sha256=q04LIQy5SCIrYZflZiTapfeQ-AaSTa0w369ehnVbJLM,532
-gltest/glchain/contract.py,sha256=1pd4eAQlHXjnRF7hBvnoR-9f-HORUaYKVyV5P42io4o,8747
+gltest/glchain/contract.py,sha256=aNS2Wm93BG4kug4iyWembBDaNb2mYCTJOTfDzMPoiRE,10042
 gltest/helpers/__init__.py,sha256=I7HiTu_H7_hP65zY6Wl02r-5eAMr2eZvqBVmusuQLX4,180
 gltest/helpers/fixture_snapshot.py,sha256=DWLTsMbTnfhpv0_7_gkJpDKX4hJx-tlruX7x3FWL6UI,2073
 gltest/helpers/take_snapshot.py,sha256=eXqEKXM2hcox3pLGIcNddobU8zXPQvD-Iwf87eHqW2s,1276
 gltest_cli/main.py,sha256=Ti2-0Ev1x5_cM0D1UKqdgaDt80CDHEQGtdRne2qLm4M,53
-tests/artifact/test_contract_definition.py,sha256=8X829MsNfEObtIMmotk6nRVLDEp5KfJE6zrAK4IPfCc,3323
+tests/artifact/test_contract_definition.py,sha256=vr3guuJOvsQorUyv_ahbNvUwfDi6cq_NKAbQMATMp1g,13803
+tests/artifact/contracts/duplicate_ic_contract_1.py,sha256=bSWsUVjBy5cGtI72cjnkstsMzuUJbB3IG5JjTxOF-dc,500
+tests/artifact/contracts/duplicate_ic_contract_2.py,sha256=bSWsUVjBy5cGtI72cjnkstsMzuUJbB3IG5JjTxOF-dc,500
 tests/artifact/contracts/not_ic_contract.py,sha256=hQyGnYiiVceYdLI2WrvcFgPqzy1S4-YMb9FPhiHEGSA,510
 tests/assertions/test_assertions.py,sha256=qzVrOdOM4xYtIy1sFHVAD_-naDHOequ23tEN0MELh0k,10781
 tests/examples/contracts/football_prediction_market.py,sha256=kdouFijjeCdIJyaVJlgXcqbBAXecA9_YdhklSsIW-QM,3219
@@ -46,8 +48,8 @@ tests/examples/tests/test_user_storage.py,sha256=QEgt2p22LAyzBnBb0YW4BWa_Jasrt15
 tests/examples/tests/test_wizard_of_coin.py,sha256=aUDeV5w0XONMMS71Vzw80lHfcSM0z8RKPJSXAuDwRto,392
 tests/plugin/conftest.py,sha256=RKdoE5_zcMimeojAoA_GSFI9du4pMzMi1vZ1njtfoAs,28
 tests/plugin/test_plugin_hooks.py,sha256=FQOrkhoXLinq0sjvoYjr63Oqg-ZVPcNFeUrK4bqrn4E,2020
-genlayer_test-0.1.3.dist-info/METADATA,sha256=10N09rjm2S2uoCmyyVu6A9hPuU6w2-_rP8jU4HYsNc0,14814
-genlayer_test-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-genlayer_test-0.1.3.dist-info/entry_points.txt,sha256=rXhrPVq2IhVsd4uWzxzwCTx7jA1KcQIVNxDCUuxq4f8,89
-genlayer_test-0.1.3.dist-info/top_level.txt,sha256=-qiGZxTRBytujzgVcKpxjvQ-WNeUDjXa59ceGMwMpko,24
-genlayer_test-0.1.3.dist-info/RECORD,,
+genlayer_test-0.2.0.dist-info/METADATA,sha256=_okLWSmaUrqZVrIZ5fLCJvXFBlhmUoItqEoioj2JV2U,14814
+genlayer_test-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+genlayer_test-0.2.0.dist-info/entry_points.txt,sha256=rXhrPVq2IhVsd4uWzxzwCTx7jA1KcQIVNxDCUuxq4f8,89
+genlayer_test-0.2.0.dist-info/top_level.txt,sha256=-qiGZxTRBytujzgVcKpxjvQ-WNeUDjXa59ceGMwMpko,24
+genlayer_test-0.2.0.dist-info/RECORD,,

gltest/artifacts/__init__.py

@@ -1,3 +1,6 @@
-from .contract import find_contract_definition
+from .contract import (
+    find_contract_definition_from_name,
+    find_contract_definition_from_path,
+)
 
-__all__ = ["find_contract_definition"]
+__all__ = ["find_contract_definition_from_name", "find_contract_definition_from_path"]

gltest/artifacts/contract.py

@@ -20,6 +20,8 @@ class ContractDefinition:
 
 def search_path_by_class_name(contracts_dir: Path, contract_name: str) -> Path:
     """Search for a file by class name in the contracts directory."""
+    matching_files = []
+
     for file_path in contracts_dir.rglob("*"):
         if not file_path.suffix in [".gpy", ".py"]:
             continue
@@ -40,10 +42,24 @@ def search_path_by_class_name(contracts_dir: Path, contract_name: str) -> Path:
                                 and base.value.id == "gl"
                                 and base.attr == "Contract"
                             ):
-                                return file_path
+                                matching_files.append(file_path)
+                                break
+                    break
         except Exception as e:
-            raise ValueError(f"Error reading file {file_path}: {e}")
-    raise FileNotFoundError(f"Contract {contract_name} not found at: {contracts_dir}")
+            raise ValueError(f"Error reading file {file_path}: {e}") from e
+
+    if len(matching_files) == 0:
+        raise FileNotFoundError(
+            f"Contract {contract_name} not found at: {contracts_dir}"
+        )
+    if len(matching_files) > 1:
+        file_paths_str = ", ".join(str(f) for f in matching_files)
+        raise ValueError(
+            f"Multiple contracts named '{contract_name}' found in contracts directory. "
+            f"Found in files: {file_paths_str}. Please ensure contract names are unique."
+        ) from None
+
+    return matching_files[0]
 
 
 def compute_contract_code(
@@ -71,14 +87,35 @@ def compute_contract_code(
     return buffer.getvalue()
 
 
-def find_contract_definition(contract_name: str) -> Optional[ContractDefinition]:
-    """
-    Search in the contracts directory for a contract definition.
-    """
-    contracts_dir = get_contracts_dir()
-    if not contracts_dir.exists():
-        raise FileNotFoundError(f"Contracts directory not found at: {contracts_dir}")
-    main_file_path = search_path_by_class_name(contracts_dir, contract_name)
+def _extract_contract_name_from_file(file_path: Path) -> str:
+    """Extract contract name from a file by parsing the AST."""
+    try:
+        with open(file_path, "r") as f:
+            content = f.read()
+        tree = ast.parse(content)
+
+        # Search for class definitions that inherit from gl.Contract
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                for base in node.bases:
+                    if (
+                        isinstance(base, ast.Attribute)
+                        and isinstance(base.value, ast.Name)
+                        and base.value.id == "gl"
+                        and base.attr == "Contract"
+                    ):
+                        return node.name
+    except Exception as e:
+        raise ValueError(f"Error parsing contract file {file_path}: {e}") from e
+
+    raise ValueError(f"No valid contract class found in {file_path}")
+
+
+def _create_contract_definition(
+    main_file_path: Path, contract_name: str
+) -> ContractDefinition:
+    """Create a ContractDefinition from a main file path and contract name."""
+    # Determine if it's a multifile contract
     main_file_dir = main_file_path.parent
     runner_file_path = None
     if main_file_path.name in ["__init__.py", "__init__.gpy"]:
@@ -87,9 +124,47 @@ def find_contract_definition(contract_name: str) -> Optional[ContractDefinition]
         if not runner_file_path.exists():
             # No runner file, so it's a single file contract
             runner_file_path = None
+
+    # Compute contract code
+    contract_code = compute_contract_code(main_file_path, runner_file_path)
+
     return ContractDefinition(
         contract_name=contract_name,
-        contract_code=compute_contract_code(main_file_path, runner_file_path),
+        contract_code=contract_code,
         main_file_path=main_file_path,
         runner_file_path=runner_file_path,
     )
+
+
+def find_contract_definition_from_name(
+    contract_name: str,
+) -> Optional[ContractDefinition]:
+    """
+    Search in the contracts directory for a contract definition.
+    """
+    contracts_dir = get_contracts_dir()
+    if not contracts_dir.exists():
+        raise FileNotFoundError(f"Contracts directory not found at: {contracts_dir}")
+
+    main_file_path = search_path_by_class_name(contracts_dir, contract_name)
+    return _create_contract_definition(main_file_path, contract_name)
+
+
+def find_contract_definition_from_path(
+    contract_file_path: Union[str, Path],
+) -> ContractDefinition:
+    """
+    Create a ContractDefinition from a given file path relative to the contracts directory.
+    """
+    contracts_dir = get_contracts_dir()
+    if not contracts_dir.exists():
+        raise FileNotFoundError(f"Contracts directory not found at: {contracts_dir}")
+
+    # Resolve the file path relative to contracts directory
+    main_file_path = contracts_dir / contract_file_path
+    if not main_file_path.exists():
+        raise FileNotFoundError(f"Contract file not found at: {main_file_path}")
+
+    contract_name = _extract_contract_name_from_file(main_file_path)
+
+    return _create_contract_definition(main_file_path, contract_name)

gltest/glchain/contract.py

@@ -4,8 +4,12 @@ from eth_typing import (
 )
 from eth_account.signers.local import LocalAccount
 from typing import Union
+from pathlib import Path
 from dataclasses import dataclass
-from gltest.artifacts import find_contract_definition
+from gltest.artifacts import (
+    find_contract_definition_from_name,
+    find_contract_definition_from_path,
+)
 from gltest.assertions import tx_execution_failed
 from gltest.exceptions import DeploymentError
 from .client import get_gl_client
@@ -146,13 +150,13 @@ class ContractFactory:
     contract_code: str
 
     @classmethod
-    def from_artifact(
+    def from_name(
         cls: Type["ContractFactory"], contract_name: str
     ) -> "ContractFactory":
         """
         Create a ContractFactory instance given the contract name.
         """
-        contract_info = find_contract_definition(contract_name)
+        contract_info = find_contract_definition_from_name(contract_name)
         if contract_info is None:
             raise ValueError(
                 f"Contract {contract_name} not found in the contracts directory"
@@ -161,6 +165,19 @@ class ContractFactory:
             contract_name=contract_name, contract_code=contract_info.contract_code
         )
 
+    @classmethod
+    def from_file_path(
+        cls: Type["ContractFactory"], contract_file_path: Union[str, Path]
+    ) -> "ContractFactory":
+        """
+        Create a ContractFactory instance given the contract file path.
+        """
+        contract_info = find_contract_definition_from_path(contract_file_path)
+        return cls(
+            contract_name=contract_info.contract_name,
+            contract_code=contract_info.contract_code,
+        )
+
     def build_contract(
         self,
         contract_address: Union[Address, ChecksumAddress],
@@ -237,8 +254,27 @@ class ContractFactory:
             ) from e
 
 
-def get_contract_factory(contract_name: str) -> ContractFactory:
+def get_contract_factory(
+    contract_name: Optional[str] = None,
+    contract_file_path: Optional[Union[str, Path]] = None,
+) -> ContractFactory:
     """
     Get a ContractFactory instance for a contract.
+
+    Args:
+        contract_name: Name of the contract to load from artifacts
+        contract_file_path: Path to the contract file to load directly
+
+    Note: Exactly one of contract_name or contract_file_path must be provided.
     """
-    return ContractFactory.from_artifact(contract_name)
+    if contract_name is not None and contract_file_path is not None:
+        raise ValueError(
+            "Only one of contract_name or contract_file_path should be provided"
+        )
+
+    if contract_name is None and contract_file_path is None:
+        raise ValueError("Either contract_name or contract_file_path must be provided")
+
+    if contract_name is not None:
+        return ContractFactory.from_name(contract_name)
+    return ContractFactory.from_file_path(contract_file_path)

tests/artifact/contracts/duplicate_ic_contract_1.py

@@ -0,0 +1,22 @@
+# { "Depends": "py-genlayer:test" }
+
+from genlayer import *
+
+
+# contract class
+class DuplicateContract(gl.Contract):
+    storage: str
+
+    # constructor
+    def __init__(self, initial_storage: str):
+        self.storage = initial_storage
+
+    # read methods must be annotated with view
+    @gl.public.view
+    def get_storage(self) -> str:
+        return self.storage
+
+    # write method
+    @gl.public.write
+    def update_storage(self, new_storage: str) -> None:
+        self.storage = new_storage

tests/artifact/contracts/duplicate_ic_contract_2.py

@@ -0,0 +1,22 @@
+# { "Depends": "py-genlayer:test" }
+
+from genlayer import *
+
+
+# contract class
+class DuplicateContract(gl.Contract):
+    storage: str
+
+    # constructor
+    def __init__(self, initial_storage: str):
+        self.storage = initial_storage
+
+    # read methods must be annotated with view
+    @gl.public.view
+    def get_storage(self) -> str:
+        return self.storage
+
+    # write method
+    @gl.public.write
+    def update_storage(self, new_storage: str) -> None:
+        self.storage = new_storage

tests/artifact/test_contract_definition.py

@@ -1,6 +1,7 @@
 import pytest
 from gltest.artifacts.contract import (
-    find_contract_definition,
+    find_contract_definition_from_name,
+    find_contract_definition_from_path,
     compute_contract_code,
 )
 from gltest.plugin_config import set_contracts_dir
@@ -8,8 +9,15 @@ from pathlib import Path
 
 
 def test_single_file():
+    """
+    Test finding a contract definition by name for a single-file contract.
+
+    Verifies that the function correctly identifies and loads a contract
+    from a single Python file, extracting the contract name and computing
+    the contract code without any additional runner files.
+    """
     set_contracts_dir(".")
-    contract_definition = find_contract_definition("PredictionMarket")
+    contract_definition = find_contract_definition_from_name("PredictionMarket")
 
     assert contract_definition.contract_name == "PredictionMarket"
 
@@ -28,8 +36,15 @@ def test_single_file():
 
 
 def test_multiple_files():
+    """
+    Test finding a contract definition by name for a multi-file contract.
+
+    Verifies that the function correctly identifies and loads a contract
+    from a multi-file structure with __init__.py and runner.json,
+    properly packaging all files into a ZIP archive for deployment.
+    """
     set_contracts_dir(".")
-    contract_definition = find_contract_definition("MultiFileContract")
+    contract_definition = find_contract_definition_from_name("MultiFileContract")
 
     assert contract_definition.contract_name == "MultiFileContract"
 
@@ -47,8 +62,15 @@ def test_multiple_files():
 
 
 def test_single_file_legacy():
+    """
+    Test finding a contract definition by name for a legacy single-file contract.
+
+    Verifies that the function correctly handles legacy .gpy files,
+    maintaining backward compatibility with older contract formats
+    while extracting contract name and computing contract code.
+    """
     set_contracts_dir(".")
-    contract_definition = find_contract_definition("StorageLegacy")
+    contract_definition = find_contract_definition_from_name("StorageLegacy")
 
     # Assert complete contract definition
     assert contract_definition.contract_name == "StorageLegacy"
@@ -66,8 +88,15 @@ def test_single_file_legacy():
 
 
 def test_multiple_files_legacy():
+    """
+    Test finding a contract definition by name for a legacy multi-file contract.
+
+    Verifies that the function correctly handles legacy multi-file contracts
+    with .gpy extension and runner.json, ensuring proper packaging and
+    backward compatibility with older contract structures.
+    """
     set_contracts_dir(".")
-    contract_definition = find_contract_definition("MultiFileContractLegacy")
+    contract_definition = find_contract_definition_from_name("MultiFileContractLegacy")
 
     # Assert complete contract definition
     assert contract_definition.contract_name == "MultiFileContractLegacy"
@@ -86,7 +115,233 @@ def test_multiple_files_legacy():
 
 
 def test_class_is_not_intelligent_contract():
+    """
+    Test error handling when searching for a non-existent contract by name.
+
+    Verifies that the function raises FileNotFoundError when attempting
+    to find a contract that doesn't exist in the contracts directory,
+    ensuring proper error handling for invalid contract names.
+    """
     set_contracts_dir(".")
 
     with pytest.raises(FileNotFoundError):
-        _ = find_contract_definition("NotICContract")
+        _ = find_contract_definition_from_name("NotICContract")
+
+
+def test_find_from_path_single_file():
+    """
+    Test finding a contract definition by file path for a single-file contract.
+
+    Verifies that the function correctly loads a contract when given a relative
+    path to a single Python file, extracting the contract name via AST parsing
+    and computing the contract code without additional runner files.
+    """
+    set_contracts_dir(".")
+    contract_definition = find_contract_definition_from_path(
+        "examples/contracts/football_prediction_market.py"
+    )
+
+    assert contract_definition.contract_name == "PredictionMarket"
+
+    # Assert complete contract definition
+    expected_main_file_path = Path("examples/contracts/football_prediction_market.py")
+    expected_runner_file_path = None
+    contract_code = compute_contract_code(
+        expected_main_file_path, expected_runner_file_path
+    )
+    assert contract_definition.contract_code == contract_code
+    assert (
+        str(contract_definition.main_file_path)
+        == "examples/contracts/football_prediction_market.py"
+    )
+    assert contract_definition.runner_file_path is None
+
+
+def test_find_from_path_multiple_files():
+    """
+    Test finding a contract definition by file path for a multi-file contract.
+
+    Verifies that the function correctly loads a contract when given a relative
+    path to __init__.py in a multi-file structure, automatically detecting
+    the associated runner.json and packaging all files appropriately.
+    """
+    set_contracts_dir(".")
+    contract_definition = find_contract_definition_from_path(
+        "examples/contracts/multi_file_contract/__init__.py"
+    )
+
+    assert contract_definition.contract_name == "MultiFileContract"
+
+    # Assert complete contract definition
+    expected_main_file_path = Path("examples/contracts/multi_file_contract/__init__.py")
+    expected_runner_file_path = Path(
+        "examples/contracts/multi_file_contract/runner.json"
+    )
+    assert contract_definition.main_file_path == expected_main_file_path
+    assert contract_definition.runner_file_path == expected_runner_file_path
+    contract_code = compute_contract_code(
+        expected_main_file_path, expected_runner_file_path
+    )
+    assert contract_definition.contract_code == contract_code
+
+
+def test_find_from_path_single_file_legacy():
+    """
+    Test finding a contract definition by file path for a legacy single-file contract.
+
+    Verifies that the function correctly handles legacy .gpy files when accessed
+    by file path, maintaining backward compatibility while extracting contract
+    name via AST parsing and computing appropriate contract code.
+    """
+    set_contracts_dir(".")
+    contract_definition = find_contract_definition_from_path(
+        "examples/contracts/storage_legacy.gpy"
+    )
+
+    # Assert complete contract definition
+    assert contract_definition.contract_name == "StorageLegacy"
+    expected_main_file_path = Path("examples/contracts/storage_legacy.gpy")
+    expected_runner_file_path = None
+    contract_code = compute_contract_code(
+        expected_main_file_path, expected_runner_file_path
+    )
+    assert contract_definition.contract_code == contract_code
+    assert (
+        str(contract_definition.main_file_path)
+        == "examples/contracts/storage_legacy.gpy"
+    )
+    assert contract_definition.runner_file_path is None
+
+
+def test_find_from_path_multiple_files_legacy():
+    """
+    Test finding a contract definition by file path for a legacy multi-file contract.
+
+    Verifies that the function correctly handles legacy multi-file contracts
+    with .gpy extension when accessed by file path, properly detecting
+    runner.json and maintaining backward compatibility with older structures.
+    """
+    set_contracts_dir(".")
+    contract_definition = find_contract_definition_from_path(
+        "examples/contracts/multi_file_contract_legacy/__init__.gpy"
+    )
+
+    # Assert complete contract definition
+    assert contract_definition.contract_name == "MultiFileContractLegacy"
+    expected_main_file_path = Path(
+        "examples/contracts/multi_file_contract_legacy/__init__.gpy"
+    )
+    expected_runner_file_path = Path(
+        "examples/contracts/multi_file_contract_legacy/runner.json"
+    )
+    assert contract_definition.main_file_path == expected_main_file_path
+    assert contract_definition.runner_file_path == expected_runner_file_path
+    contract_code = compute_contract_code(
+        expected_main_file_path, expected_runner_file_path
+    )
+    assert contract_definition.contract_code == contract_code
+
+
+def test_find_from_path_file_not_found():
+    """
+    Test error handling when the specified contract file doesn't exist.
+
+    Verifies that the function raises FileNotFoundError with appropriate
+    error message when attempting to load a contract from a non-existent
+    file path relative to the contracts directory.
+    """
+    set_contracts_dir(".")
+
+    with pytest.raises(FileNotFoundError, match="Contract file not found at:"):
+        _ = find_contract_definition_from_path("nonexistent/contract.py")
+
+
+def test_find_from_path_contracts_dir_not_found():
+    """
+    Test error handling when the contracts directory doesn't exist.
+
+    Verifies that the function raises FileNotFoundError with appropriate
+    error message when the configured contracts directory is invalid,
+    ensuring proper validation before attempting file operations.
+    """
+    set_contracts_dir("nonexistent_directory")
+
+    with pytest.raises(FileNotFoundError, match="Contracts directory not found at:"):
+        _ = find_contract_definition_from_path("some/contract.py")
+
+
+def test_find_from_path_no_valid_contract_class():
+    """
+    Test error handling when a file exists but contains no valid contract class.
+
+    Verifies that the function raises ValueError with appropriate error message
+    when attempting to load a file that exists but doesn't contain a class
+    that inherits from gl.Contract, ensuring proper AST parsing validation.
+    """
+    set_contracts_dir(".")
+
+    with pytest.raises(ValueError, match="No valid contract class found in"):
+        _ = find_contract_definition_from_path("artifact/contracts/not_ic_contract.py")
+
+
+def test_multiple_contracts_same_name():
+    """
+    Test error handling when multiple contracts with the same name exist.
+
+    Verifies that the function raises ValueError with appropriate error message
+    when multiple files contain contracts with the same name, listing all
+    duplicate file locations and providing guidance for resolution.
+    """
+    set_contracts_dir(".")
+
+    with pytest.raises(
+        ValueError,
+        match=r"Multiple contracts named 'DuplicateContract' found in contracts directory\. Found in files: .+\. Please ensure contract names are unique\.",
+    ):
+        _ = find_contract_definition_from_name("DuplicateContract")
+
+
+def test_duplicate_contract_error_message_format():
+    """
+    Test that the duplicate contract error message contains all expected elements.
+
+    Verifies that when multiple contracts with the same name are found, the error
+    message includes the contract name, mentions "contracts directory", lists
+    file paths, and provides clear guidance about ensuring uniqueness.
+    """
+    set_contracts_dir(".")
+
+    try:
+        _ = find_contract_definition_from_name("DuplicateContract")
+        pytest.fail("Expected ValueError for duplicate contracts")
+    except ValueError as e:
+        error_message = str(e)
+        # Verify error message contains key components
+        assert "Multiple contracts named 'DuplicateContract' found" in error_message
+        assert "contracts directory" in error_message
+        assert "Found in files:" in error_message
+        assert "Please ensure contract names are unique" in error_message
+        # Verify that multiple file paths are mentioned (comma-separated)
+        assert (
+            "," in error_message
+            or len(error_message.split("Found in files: ")[1].split(".")[0]) > 0
+        )
+    except Exception as e:
+        pytest.fail(f"Expected ValueError but got {type(e).__name__}: {e}")
+
+
+def test_single_contract_still_works_with_duplicate_detection():
+    """
+    Test that normal single contract loading still works after duplicate detection changes.
+
+    Verifies that the enhanced search_path_by_class_name function doesn't break
+    the normal case where only one contract with a given name exists, ensuring
+    backward compatibility with existing functionality.
+    """
+    set_contracts_dir(".")
+
+    # This should work normally - no duplicates expected for PredictionMarket
+    contract_definition = find_contract_definition_from_name("PredictionMarket")
+    assert contract_definition.contract_name == "PredictionMarket"
+    assert contract_definition.main_file_path is not None
+    assert "football_prediction_market.py" in str(contract_definition.main_file_path)