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

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

@@ -1,18 +1,16 @@
 Metadata-Version: 2.4
 Name: genlayer-test
-Version: 0.1.2
+Version: 0.2.0
 Summary: GenLayer Testing Suite
 Author: GenLayer
 License-Expression: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.8
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pytest
@@ -162,7 +160,7 @@ Before diving into the examples, let's understand the basic project structure:
 ```
 genlayer-example/
 ├── contracts/              # Contract definitions
-│   └── storage.gpy         # Example storage contract
+│   └── storage.py          # Example storage contract
 └── test/                   # Test files
     └── test_contract.py    # Contract test cases
 ```
@@ -279,6 +277,44 @@ def test_write_methods():
     assert contract.get_storage() == "new_value"
 ```
 
+### Assertions
+
+The GenLayer Testing Suite provides powerful assertion functions to validate transaction results and their output:
+
+#### Basic Transaction Assertions
+
+```python
+from gltest.assertions import tx_execution_succeeded, tx_execution_failed
+
+# Basic success/failure checks
+assert tx_execution_succeeded(tx_receipt)
+assert tx_execution_failed(tx_receipt)  # Opposite of tx_execution_succeeded
+```
+
+#### Advanced Output Matching
+
+You can match specific patterns in the transaction's stdout and stderr output using regex patterns, similar to pytest's `match` parameter:
+
+```python
+# Simple string matching
+assert tx_execution_succeeded(tx_receipt, match_std_out="Process completed")
+assert tx_execution_failed(tx_receipt, match_std_err="Warning: deprecated")
+
+# Regex pattern matching
+assert tx_execution_succeeded(tx_receipt, match_std_out=r".*code \d+")
+assert tx_execution_failed(tx_receipt, match_std_err=r"Method.*failed")
+```
+
+#### Assertion Function Parameters
+
+Both `tx_execution_succeeded` and `tx_execution_failed` accept the following parameters:
+
+- `result`: The transaction result object from contract method calls
+- `match_std_out` (optional): String or regex pattern to match in stdout
+- `match_std_err` (optional): String or regex pattern to match in stderr
+
+**Network Compatibility**: The stdout/stderr matching feature (`match_std_out` and `match_std_err` parameters) is only available when running on **studionet** and **localnet**. These features are not supported on testnet.
+
 For more example contracts, check out the [contracts directory](tests/examples/contracts) which contains various sample contracts demonstrating different features and use cases.
 
 ## 📝 Best Practices
@@ -354,7 +390,7 @@ For more example contracts, check out the [contracts directory](tests/examples/c
    # Default structure
    your_project/
    ├── contracts/           # Default contracts directory
-   │   └── my_contract.gpy  # Your contract file
+   │   └── my_contract.py   # Your contract file
    └── tests/
        └── test_contract.py # Your test file
    
@@ -366,7 +402,8 @@ For more example contracts, check out the [contracts directory](tests/examples/c
    - **Problem**: Contracts aren't being recognized or loaded properly.
    - **Solution**: Follow the correct naming and structure conventions:
    ```python
-   # Correct file: contracts/my_contract.gpy
+   # Correct file: contracts/my_contract.py
+
    # Correct structure:
    from genlayer import *
    
@@ -374,7 +411,7 @@ For more example contracts, check out the [contracts directory](tests/examples/c
        # Contract code here
        pass
    
-   # Incorrect file: contracts/my_contract.py  # Wrong extension
+
    # Incorrect structure:
    class MyContract:  # Missing gl.Contract inheritance
        pass
@@ -385,7 +422,7 @@ For more example contracts, check out the [contracts directory](tests/examples/c
    - **Solution**: Verify your environment:
    ```bash
    # Check Python version
-   python --version  # Should be >= 3.8
+   python --version  # Should be >= 3.12
    
    # Check GenLayer Studio status
    docker ps  # Should show GenLayer Studio running

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

@@ -1,23 +1,25 @@
-genlayer_test-0.1.2.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=dBjiK5-LuxrrktkNDP7n-t6i43UNCL_cq7M4BLqRyFk,678
+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=CBRfUTltKv2tPy--LcmVbP_4hbXYt9VrunvJlMzNd5s,3566
+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=y1XE15908Rv3RjWNxU7DtRF2gEGM9eEiHPh9jJHbR4g,1046
+tests/assertions/test_assertions.py,sha256=qzVrOdOM4xYtIy1sFHVAD_-naDHOequ23tEN0MELh0k,10781
 tests/examples/contracts/football_prediction_market.py,sha256=kdouFijjeCdIJyaVJlgXcqbBAXecA9_YdhklSsIW-QM,3219
 tests/examples/contracts/intelligent_oracle.py,sha256=WrNZWWoi1sz22Azt2EXgdWHDg5Ihca2pWUHrM9pVfQE,12319
 tests/examples/contracts/intelligent_oracle_factory.py,sha256=ax496IZuDCA728rRcbjwTaM4Q4E-Y1jGkHsEcyf1cig,1490
@@ -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.2.dist-info/METADATA,sha256=05aK4xzg2NrGQIAcFkWS6NNzvFyxVkF_jCqSZhgk8po,13471
-genlayer_test-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-genlayer_test-0.1.2.dist-info/entry_points.txt,sha256=rXhrPVq2IhVsd4uWzxzwCTx7jA1KcQIVNxDCUuxq4f8,89
-genlayer_test-0.1.2.dist-info/top_level.txt,sha256=-qiGZxTRBytujzgVcKpxjvQ-WNeUDjXa59ceGMwMpko,24
-genlayer_test-0.1.2.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

@@ -10,7 +10,7 @@ from typing import Union
 
 @dataclass
 class ContractDefinition:
-    """Class that represents a contract definition from a .gpy file."""
+    """Class that represents a contract definition from a contract file."""
 
     contract_name: str
     contract_code: Union[str, bytes]
@@ -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/assertions.py

@@ -1,18 +1,59 @@
+import re
+from typing import Optional
 from genlayer_py.types import GenLayerTransaction
 
 
-def tx_execution_succeeded(result: GenLayerTransaction) -> bool:
+def tx_execution_succeeded(
+    result: GenLayerTransaction,
+    match_std_out: Optional[str] = None,
+    match_std_err: Optional[str] = None,
+) -> bool:
     if "consensus_data" not in result:
         return False
     if "leader_receipt" not in result["consensus_data"]:
         return False
     if len(result["consensus_data"]["leader_receipt"]) == 0:
         return False
-    if "execution_result" not in result["consensus_data"]["leader_receipt"][0]:
+
+    leader_receipt = result["consensus_data"]["leader_receipt"][0]
+
+    if "execution_result" not in leader_receipt:
+        return False
+
+    execution_result = leader_receipt["execution_result"]
+
+    if execution_result != "SUCCESS":
         return False
-    execution_result = result["consensus_data"]["leader_receipt"][0]["execution_result"]
-    return execution_result == "SUCCESS"
+
+    if match_std_out is not None or match_std_err is not None:
+        if "genvm_result" not in leader_receipt:
+            return False
+
+        genvm_result = leader_receipt["genvm_result"]
+
+        if match_std_out is not None:
+            if "stdout" not in genvm_result:
+                return False
+            try:
+                if not re.search(match_std_out, genvm_result["stdout"]):
+                    return False
+            except re.error:
+                return False
+
+        if match_std_err is not None:
+            if "stderr" not in genvm_result:
+                return False
+            try:
+                if not re.search(match_std_err, genvm_result["stderr"]):
+                    return False
+            except re.error:
+                return False
+    return True
 
 
-def tx_execution_failed(result: GenLayerTransaction) -> bool:
-    return not tx_execution_succeeded(result)
+def tx_execution_failed(
+    result: GenLayerTransaction,
+    match_std_out: Optional[str] = None,
+    match_std_err: Optional[str] = None,
+) -> bool:
+    return not tx_execution_succeeded(result, match_std_out, match_std_err)

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)

tests/assertions/test_assertions.py

@@ -10,22 +10,335 @@ GENLAYER_FAILED_TRANSACTION = {
 
 GENLAYER_EMPTY_LEADER_RECEIPT = {"consensus_data": {"leader_receipt": []}}
 
+GENLAYER_GENVM_TRANSACTION = {
+    "consensus_data": {
+        "leader_receipt": [
+            {
+                "execution_result": "SUCCESS",
+                "genvm_result": {
+                    "stdout": "Process completed successfully with code 123 items",
+                    "stderr": "Warning: deprecated function used",
+                },
+            }
+        ]
+    }
+}
+
+GENLAYER_GENVM_EMPTY_STDERR = {
+    "consensus_data": {
+        "leader_receipt": [
+            {
+                "execution_result": "SUCCESS",
+                "genvm_result": {
+                    "stdout": "Task finished without errors",
+                    "stderr": "",
+                },
+            }
+        ]
+    }
+}
+
+GENLAYER_GENVM_NO_STDOUT = {
+    "consensus_data": {
+        "leader_receipt": [
+            {
+                "execution_result": "SUCCESS",
+                "genvm_result": {"stderr": "Error occurred"},
+            }
+        ]
+    }
+}
+
+GENLAYER_GENVM_FAILED = {
+    "consensus_data": {
+        "leader_receipt": [
+            {
+                "execution_result": "ERROR",
+                "genvm_result": {
+                    "stdout": "Process failed",
+                    "stderr": "Critical error occurred",
+                },
+            }
+        ]
+    }
+}
+
 
 def test_with_successful_transaction():
+    """Test assertion functions with a basic successful transaction.
+
+    Validates that:
+    - tx_execution_succeeded returns True for successful transactions
+    - tx_execution_failed returns False for successful transactions
+    """
     assert tx_execution_succeeded(GENLAYER_SUCCESS_TRANSACTION) is True
     assert tx_execution_failed(GENLAYER_SUCCESS_TRANSACTION) is False
 
 
 def test_with_failed_transaction():
+    """Test assertion functions with a basic failed transaction.
+
+    Validates that:
+    - tx_execution_succeeded returns False for failed transactions
+    - tx_execution_failed returns True for failed transactions
+    """
     assert tx_execution_succeeded(GENLAYER_FAILED_TRANSACTION) is False
     assert tx_execution_failed(GENLAYER_FAILED_TRANSACTION) is True
 
 
 def test_with_empty_leader_receipt():
+    """Test assertion functions with empty leader_receipt array.
+
+    Validates that:
+    - Both functions handle empty leader_receipt gracefully
+    - Empty leader_receipt is treated as a failed transaction
+    """
     assert tx_execution_succeeded(GENLAYER_EMPTY_LEADER_RECEIPT) is False
     assert tx_execution_failed(GENLAYER_EMPTY_LEADER_RECEIPT) is True
 
 
 def test_with_invalid_transaction():
+    """Test assertion functions with completely invalid transaction structure.
+
+    Validates that:
+    - Both functions handle malformed transactions gracefully
+    - Invalid transactions are treated as failed
+    """
     assert tx_execution_succeeded({}) is False
     assert tx_execution_failed({}) is True
+
+
+def test_genvm_result_without_match():
+    """Test assertion functions with genvm_result but no match parameters.
+
+    Validates that:
+    - Transactions with genvm_result succeed when execution_result is SUCCESS
+    - No match parameters means only basic execution status is checked
+    """
+    assert tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION) is True
+    assert tx_execution_failed(GENLAYER_GENVM_TRANSACTION) is False
+
+
+def test_match_std_out_simple_string():
+    """Test stdout matching with simple string patterns.
+
+    Validates that:
+    - Simple string matching works correctly in stdout
+    - Non-matching strings cause the assertion to fail
+    - tx_execution_failed behaves oppositely to tx_execution_succeeded
+    """
+    assert (
+        tx_execution_succeeded(
+            GENLAYER_GENVM_TRANSACTION, match_std_out="Process completed"
+        )
+        is True
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_out="nonexistent")
+        is False
+    )
+    assert (
+        tx_execution_failed(GENLAYER_GENVM_TRANSACTION, match_std_out="nonexistent")
+        is True
+    )
+
+
+def test_match_std_err_simple_string():
+    """Test stderr matching with simple string patterns.
+
+    Validates that:
+    - Simple string matching works correctly in stderr
+    - Non-matching strings cause the assertion to fail
+    - tx_execution_failed behaves oppositely to tx_execution_succeeded
+    """
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_err="Warning")
+        is True
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_err="nonexistent")
+        is False
+    )
+    assert (
+        tx_execution_failed(GENLAYER_GENVM_TRANSACTION, match_std_err="nonexistent")
+        is True
+    )
+
+
+def test_match_std_out_regex():
+    """Test stdout matching with regex patterns.
+
+    Validates that:
+    - Complex regex patterns work correctly in stdout
+    - Different regex patterns match appropriately
+    - Non-matching regex patterns cause assertions to fail
+    - Tests various regex features like \\d+, .*, word boundaries
+    """
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_out=r".*code \d+")
+        is True
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_out=r".* 123 .*")
+        is True
+    )
+    assert (
+        tx_execution_succeeded(
+            GENLAYER_GENVM_TRANSACTION, match_std_out=r"Process.*successfully"
+        )
+        is True
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_out=r"code \d{4}")
+        is False
+    )
+
+
+def test_match_std_err_regex():
+    """Test stderr matching with regex patterns.
+
+    Validates that:
+    - Complex regex patterns work correctly in stderr
+    - Different regex patterns match appropriately
+    - Non-matching regex patterns cause assertions to fail
+    - Tests various regex features like .*, word boundaries
+    """
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_err=r"Warning:.*")
+        is True
+    )
+    assert (
+        tx_execution_succeeded(
+            GENLAYER_GENVM_TRANSACTION, match_std_err=r".*deprecated.*"
+        )
+        is True
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_TRANSACTION, match_std_err=r"Error:.*")
+        is False
+    )
+
+
+def test_match_both_stdout_and_stderr():
+    """Test matching both stdout and stderr simultaneously.
+
+    Validates that:
+    - Both stdout and stderr patterns must match for success
+    - If either pattern fails to match, the assertion fails
+    - Combined matching works with both simple strings and regex
+    """
+    assert (
+        tx_execution_succeeded(
+            GENLAYER_GENVM_TRANSACTION,
+            match_std_out="Process completed",
+            match_std_err="Warning",
+        )
+        is True
+    )
+
+    assert (
+        tx_execution_succeeded(
+            GENLAYER_GENVM_TRANSACTION,
+            match_std_out="Process completed",
+            match_std_err="nonexistent",
+        )
+        is False
+    )
+
+
+def test_match_empty_stderr():
+    """Test matching empty stderr with different approaches.
+
+    Validates that:
+    - Empty stderr can be matched with regex pattern ^$
+    - Empty stderr can be matched with empty string
+    - Non-empty patterns fail when stderr is empty
+    """
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_EMPTY_STDERR, match_std_err=r"^$") is True
+    )
+    assert tx_execution_succeeded(GENLAYER_GENVM_EMPTY_STDERR, match_std_err="") is True
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_EMPTY_STDERR, match_std_err="Warning")
+        is False
+    )
+
+
+def test_missing_stdout_field():
+    """Test behavior when stdout field is missing from genvm_result.
+
+    Validates that:
+    - Missing stdout field causes match_std_out to fail
+    - The assertion handles missing fields gracefully
+    - tx_execution_failed returns True when stdout matching is requested but field is missing
+    """
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_NO_STDOUT, match_std_out="anything")
+        is False
+    )
+    assert (
+        tx_execution_failed(GENLAYER_GENVM_NO_STDOUT, match_std_out="anything") is True
+    )
+
+
+def test_missing_stderr_field():
+    """Test behavior when stderr field is missing from genvm_result.
+
+    Validates that:
+    - Missing stderr field causes match_std_err to fail
+    - The assertion handles missing fields gracefully
+    - tx_execution_failed returns True when stderr matching is requested but field is missing
+    """
+    genvm_no_stderr = {
+        "consensus_data": {
+            "leader_receipt": [
+                {"execution_result": "SUCCESS", "genvm_result": {"stdout": "Success"}}
+            ]
+        }
+    }
+    assert tx_execution_succeeded(genvm_no_stderr, match_std_err="anything") is False
+    assert tx_execution_failed(genvm_no_stderr, match_std_err="anything") is True
+
+
+def test_failed_execution_with_genvm_result():
+    """Test assertion behavior with failed execution but present genvm_result.
+
+    Validates that:
+    - execution_result takes precedence over output matching
+    - Even with matching stdout/stderr, failed executions return False
+    - The basic execution status is checked before output matching
+    """
+    assert tx_execution_succeeded(GENLAYER_GENVM_FAILED) is False
+    assert tx_execution_failed(GENLAYER_GENVM_FAILED) is True
+
+    # Even with matching stdout/stderr, should still fail if execution_result is not SUCCESS
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_FAILED, match_std_out="Process failed")
+        is False
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_GENVM_FAILED, match_std_err="Critical error")
+        is False
+    )
+
+
+def test_missing_genvm_result_with_match():
+    """Test behavior when genvm_result is missing but match parameters are provided.
+
+    Validates that:
+    - Missing genvm_result causes output matching to fail
+    - Both stdout and stderr matching fail when genvm_result is absent
+    - tx_execution_failed returns True when match parameters are used without genvm_result
+    """
+    assert (
+        tx_execution_succeeded(GENLAYER_SUCCESS_TRANSACTION, match_std_out="anything")
+        is False
+    )
+    assert (
+        tx_execution_succeeded(GENLAYER_SUCCESS_TRANSACTION, match_std_err="anything")
+        is False
+    )
+    assert (
+        tx_execution_failed(GENLAYER_SUCCESS_TRANSACTION, match_std_out="anything")
+        is True
+    )