genlayer-test 0.10.1__tar.gz → 0.12.0__tar.gz

{genlayer_test-0.10.1 → genlayer_test-0.12.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 YeagerAI
+Copyright (c) 2024 GenLayer Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

{genlayer_test-0.10.1 → genlayer_test-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: genlayer-test
-Version: 0.10.1
+Version: 0.12.0
 Summary: GenLayer Testing Suite
 Author: GenLayer
 License-Expression: MIT
@@ -24,8 +24,8 @@ Dynamic: license-file
 # GenLayer Testing Suite
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/license/mit/)
-[![Discord](https://dcbadge.vercel.app/api/server/8Jm4v89VAu?compact=true&style=flat)](https://discord.gg/VpfmXEMN66)
-[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/yeagerai.svg?style=social&label=Follow%20%40GenLayer)](https://x.com/GenLayer)
+[![Discord](https://dcbadge.vercel.app/api/server/8Jm4v89VAu?compact=true&style=flat)](https://discord.gg/qjCU4AWnKE)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/genlayerlabs.svg?style=social&label=Follow%20%40GenLayer)](https://x.com/GenLayer)
 [![PyPI version](https://badge.fury.io/py/genlayer-test.svg)](https://badge.fury.io/py/genlayer-test)
 [![Documentation](https://img.shields.io/badge/docs-genlayer-blue)](https://docs.genlayer.com/api-references/genlayer-test)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -107,7 +107,7 @@ $ pip install genlayer-test
 
 2. Install from source:
 ```bash
-$ git clone https://github.com/yeagerai/genlayer-testing-suite
+$ git clone https://github.com/genlayerlabs/genlayer-testing-suite
 $ cd genlayer-testing-suite
 $ pip install -e .
 ```
@@ -312,6 +312,72 @@ The chain type determines various behaviors including RPC endpoints, consensus m
 - **Prompt Testing & Statistical Analysis** – Evaluate and statistically test prompts for AI-driven contract execution.
 - **Scalability to Security & Audit Tools** – Designed to extend into security testing and smart contract auditing.
 - **Custom Transaction Context** – Set custom validators with specific LLM providers and models, and configure GenVM datetime for deterministic testing scenarios.
+- **Direct Execution Mode** – Run contracts directly in Python for ultra-fast unit testing (~ms vs minutes).
+
+## ⚡ Direct vs Simulator Mode
+
+The testing suite provides two execution modes:
+
+| Mode | How it works | Speed | Use case |
+|------|--------------|-------|----------|
+| **Simulator** | Deploy to GenLayer simulator, interact via RPC | ~minutes | Integration tests, consensus validation |
+| **Direct** | Run Python code directly in-memory | ~milliseconds | Unit tests, rapid development |
+
+### Quick Start with Direct Mode
+
+```python
+def test_token_transfer(direct_vm, direct_deploy):
+    # Deploy contract directly in Python (no simulator)
+    token = direct_deploy("contracts/Token.py", initial_supply=1000)
+
+    # Create test addresses
+    from gltest.direct import create_address
+    alice = create_address("alice")
+    bob = create_address("bob")
+
+    # Set sender and interact
+    direct_vm.sender = alice
+    token.mint(alice, 500)
+    token.transfer(bob, 100)
+
+    assert token.balances[bob] == 100
+```
+
+### Available Fixtures
+
+| Fixture | Description |
+|---------|-------------|
+| `direct_vm` | VM context with cheatcodes |
+| `direct_deploy` | Deploy contracts directly |
+| `direct_alice`, `direct_bob`, `direct_charlie` | Test addresses |
+| `direct_owner` | Default sender address |
+| `direct_accounts` | List of 10 test addresses |
+
+### Cheatcodes
+
+```python
+# Change sender
+direct_vm.sender = alice
+
+# Prank (temporary sender change)
+with direct_vm.prank(bob):
+    contract.method()  # Called as bob
+
+# Snapshots
+snap_id = direct_vm.snapshot()
+contract.modify_state()
+direct_vm.revert(snap_id)  # State restored
+
+# Expect revert
+with direct_vm.expect_revert("Insufficient balance"):
+    contract.transfer(bob, 1000000)
+
+# Mock web/LLM (for nondet operations)
+direct_vm.mock_web(r"api\.example\.com", {"status": 200, "body": "{}"})
+direct_vm.mock_llm(r"analyze.*", "positive sentiment")
+```
+
+📖 **[Full Direct Mode Documentation](docs/direct-runner.md)**
 
 ## 📚 Examples
 
@@ -622,6 +688,205 @@ The `.analyze()` method helps you:
 - Benchmark performance across multiple runs
 
 
+### Mock Web Responses
+
+The Mock Web Response system allows you to simulate HTTP responses for web requests made by intelligent contracts using GenLayer's web methods (`gl.nondet.web.get()`, `gl.nondet.web.post()`, etc.). This feature enables deterministic testing of contracts that interact with external web services without making actual HTTP calls.
+
+#### Basic Example
+
+Here's a simple example of mocking a web API response:
+
+```python
+from gltest import get_contract_factory, get_validator_factory
+from gltest.types import MockedWebResponse
+import json
+
+def test_simple_web_mock():
+    # Define mock web responses
+    mock_web_response: MockedWebResponse = {
+        "nondet_web_request": {
+            "https://api.example.com/price": {
+                "method": "GET",
+                "status": 200,
+                "body": json.dumps({"price": 100.50})
+            }
+        }
+    }
+    
+    # Create validators with mock web responses
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_web_response=mock_web_response
+    )
+    
+    # Use validators in transaction context
+    transaction_context = {"validators": [v.to_dict() for v in validators]}
+    
+    # Deploy and test contract
+    factory = get_contract_factory("PriceOracle")
+    contract = factory.deploy(transaction_context=transaction_context)
+    
+    # Contract's web requests will receive the mocked response
+    result = contract.update_price().transact(transaction_context=transaction_context)
+```
+
+#### Supported HTTP Methods
+
+Mock web responses support all HTTP methods including GET, POST, PUT, DELETE, PATCH, etc.:
+
+```python
+mock_web_response: MockedWebResponse = {
+    "nondet_web_request": {
+        # GET request
+        "https://api.example.com/users/123": {
+            "method": "GET",
+            "status": 200,
+            "body": '{"id": 123, "name": "Alice"}'
+        },
+        # POST request
+        "https://api.example.com/users": {
+            "method": "POST",
+            "status": 201,
+            "body": '{"id": 124, "name": "Bob", "created": true}'
+        },
+        # DELETE request
+        "https://api.example.com/users/123": {
+            "method": "DELETE",
+            "status": 204,
+            "body": ""
+        },
+        # PUT request
+        "https://api.example.com/users/123": {
+            "method": "PUT",
+            "status": 200,
+            "body": '{"id": 123, "name": "Alice Updated"}'
+        },
+        # Error response
+        "https://api.example.com/error": {
+            "method": "GET",
+            "status": 500,
+            "body": "Internal Server Error"
+        }
+    }
+}
+```
+
+#### How It Works
+
+When a contract calls any web method (`gl.nondet.web.get()`, `gl.nondet.web.post()`, etc.):
+1. The mock system checks if the URL exists in the mock configuration
+2. If found, it returns the mocked response with the specified status and body
+3. If not found, the actual web request would be made (or fail if network access is disabled)
+
+#### Complete Example: Twitter/X Username Storage
+
+Here's a real-world example showing how to mock Twitter/X API responses:
+
+```python
+# test_x_username_storage.py
+from gltest import get_contract_factory, get_validator_factory
+from gltest.assertions import tx_execution_succeeded
+from gltest.types import MockedWebResponse
+import json
+import urllib.parse
+
+def test_x_username_storage():
+    # Helper to build URL with query parameters
+    def get_username_url(username: str) -> str:
+        params = {"user.fields": "public_metrics,verified"}
+        return f"https://domain.com/api/twitter/users/by/username/{username}?{urllib.parse.urlencode(params)}"
+    
+    # Define mock responses for different usernames
+    mock_web_response: MockedWebResponse = {
+        "nondet_web_request": {
+            get_username_url("user_a"): {
+                "method": "GET",
+                "status": 200,
+                "body": json.dumps({"username": "user_a", "verified": True})
+            },
+            get_username_url("user_b"): {
+                "method": "GET",
+                "status": 200,
+                "body": json.dumps({"username": "user_b", "verified": False})
+            }
+        }
+    }
+    
+    # Create validators with mock web responses
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_web_response=mock_web_response
+    )
+    transaction_context = {"validators": [v.to_dict() for v in validators]}
+    
+    # Deploy and test contract
+    factory = get_contract_factory("XUsernameStorage")
+    contract = factory.deploy(transaction_context=transaction_context)
+    
+    # Test updating username - will use mocked response
+    tx_receipt = contract.update_username(args=["user_a"]).transact(
+        transaction_context=transaction_context
+    )
+    assert tx_execution_succeeded(tx_receipt)
+    
+    # Verify the username was stored
+    username = contract.get_username().call(transaction_context=transaction_context)
+    assert username == "user_a"
+```
+
+#### Combining Mock LLM and Web Responses
+
+You can combine both mock LLM responses and mock web responses in the same test:
+
+```python
+def test_combined_mocks():
+    # Define both mock types
+    mock_llm_response = {
+        "eq_principle_prompt_comparative": {
+            "values match": True
+        }
+    }
+    
+    mock_web_response: MockedWebResponse = {
+        "nondet_web_request": {
+            "https://api.example.com/data": {
+                "method": "GET",
+                "status": 200,
+                "body": '{"value": 42}'
+            }
+        }
+    }
+    
+    # Create validators with both mock types
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_llm_response=mock_llm_response,
+        mock_web_response=mock_web_response
+    )
+    
+    # Use in your tests...
+```
+
+#### Best Practices
+
+1. **URL Matching**: URLs must match exactly, including query parameters
+2. **Response Body**: Always provide the body as a string (use `json.dumps()` for JSON data)
+3. **Status Codes**: Use realistic HTTP status codes (200, 404, 500, etc.)
+4. **Method Matching**: Specify the correct HTTP method that your contract uses
+5. **Error Testing**: Mock error responses to test error handling paths
+6. **Deterministic Tests**: Mock web responses ensure tests don't depend on external services
+
+#### Notes
+
+- Mock web responses are only available when using mock validators
+- URL matching is exact - the full URL including query parameters must match
+- The method field should match the HTTP method used by the contract
+- Useful for testing contracts that interact with external APIs without network dependencies
+- All standard HTTP methods are supported (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
+
 ### Custom Transaction Context
 
 The GenLayer Testing Suite allows you to customize the transaction execution environment by providing a `transaction_context` parameter with custom validators and GenVM datetime settings.
@@ -1001,8 +1266,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ## 💬 Support
 
 - [Documentation](https://docs.genlayer.com/api-references/genlayer-test)
-- [Discord Community](https://discord.gg/VpfmXEMN66)
-- [GitHub Issues](https://github.com/yeagerai/genlayer-testing-suite/issues)
+- [Discord Community](https://discord.gg/qjCU4AWnKE)
+- [GitHub Issues](https://github.com/genlayerlabs/genlayer-testing-suite/issues)
 - [Twitter](https://x.com/GenLayer)
 
 

{genlayer_test-0.10.1 → genlayer_test-0.12.0}/README.md

@@ -1,8 +1,8 @@
 # GenLayer Testing Suite
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/license/mit/)
-[![Discord](https://dcbadge.vercel.app/api/server/8Jm4v89VAu?compact=true&style=flat)](https://discord.gg/VpfmXEMN66)
-[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/yeagerai.svg?style=social&label=Follow%20%40GenLayer)](https://x.com/GenLayer)
+[![Discord](https://dcbadge.vercel.app/api/server/8Jm4v89VAu?compact=true&style=flat)](https://discord.gg/qjCU4AWnKE)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/genlayerlabs.svg?style=social&label=Follow%20%40GenLayer)](https://x.com/GenLayer)
 [![PyPI version](https://badge.fury.io/py/genlayer-test.svg)](https://badge.fury.io/py/genlayer-test)
 [![Documentation](https://img.shields.io/badge/docs-genlayer-blue)](https://docs.genlayer.com/api-references/genlayer-test)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -84,7 +84,7 @@ $ pip install genlayer-test
 
 2. Install from source:
 ```bash
-$ git clone https://github.com/yeagerai/genlayer-testing-suite
+$ git clone https://github.com/genlayerlabs/genlayer-testing-suite
 $ cd genlayer-testing-suite
 $ pip install -e .
 ```
@@ -289,6 +289,72 @@ The chain type determines various behaviors including RPC endpoints, consensus m
 - **Prompt Testing & Statistical Analysis** – Evaluate and statistically test prompts for AI-driven contract execution.
 - **Scalability to Security & Audit Tools** – Designed to extend into security testing and smart contract auditing.
 - **Custom Transaction Context** – Set custom validators with specific LLM providers and models, and configure GenVM datetime for deterministic testing scenarios.
+- **Direct Execution Mode** – Run contracts directly in Python for ultra-fast unit testing (~ms vs minutes).
+
+## ⚡ Direct vs Simulator Mode
+
+The testing suite provides two execution modes:
+
+| Mode | How it works | Speed | Use case |
+|------|--------------|-------|----------|
+| **Simulator** | Deploy to GenLayer simulator, interact via RPC | ~minutes | Integration tests, consensus validation |
+| **Direct** | Run Python code directly in-memory | ~milliseconds | Unit tests, rapid development |
+
+### Quick Start with Direct Mode
+
+```python
+def test_token_transfer(direct_vm, direct_deploy):
+    # Deploy contract directly in Python (no simulator)
+    token = direct_deploy("contracts/Token.py", initial_supply=1000)
+
+    # Create test addresses
+    from gltest.direct import create_address
+    alice = create_address("alice")
+    bob = create_address("bob")
+
+    # Set sender and interact
+    direct_vm.sender = alice
+    token.mint(alice, 500)
+    token.transfer(bob, 100)
+
+    assert token.balances[bob] == 100
+```
+
+### Available Fixtures
+
+| Fixture | Description |
+|---------|-------------|
+| `direct_vm` | VM context with cheatcodes |
+| `direct_deploy` | Deploy contracts directly |
+| `direct_alice`, `direct_bob`, `direct_charlie` | Test addresses |
+| `direct_owner` | Default sender address |
+| `direct_accounts` | List of 10 test addresses |
+
+### Cheatcodes
+
+```python
+# Change sender
+direct_vm.sender = alice
+
+# Prank (temporary sender change)
+with direct_vm.prank(bob):
+    contract.method()  # Called as bob
+
+# Snapshots
+snap_id = direct_vm.snapshot()
+contract.modify_state()
+direct_vm.revert(snap_id)  # State restored
+
+# Expect revert
+with direct_vm.expect_revert("Insufficient balance"):
+    contract.transfer(bob, 1000000)
+
+# Mock web/LLM (for nondet operations)
+direct_vm.mock_web(r"api\.example\.com", {"status": 200, "body": "{}"})
+direct_vm.mock_llm(r"analyze.*", "positive sentiment")
+```
+
+📖 **[Full Direct Mode Documentation](docs/direct-runner.md)**
 
 ## 📚 Examples
 
@@ -599,6 +665,205 @@ The `.analyze()` method helps you:
 - Benchmark performance across multiple runs
 
 
+### Mock Web Responses
+
+The Mock Web Response system allows you to simulate HTTP responses for web requests made by intelligent contracts using GenLayer's web methods (`gl.nondet.web.get()`, `gl.nondet.web.post()`, etc.). This feature enables deterministic testing of contracts that interact with external web services without making actual HTTP calls.
+
+#### Basic Example
+
+Here's a simple example of mocking a web API response:
+
+```python
+from gltest import get_contract_factory, get_validator_factory
+from gltest.types import MockedWebResponse
+import json
+
+def test_simple_web_mock():
+    # Define mock web responses
+    mock_web_response: MockedWebResponse = {
+        "nondet_web_request": {
+            "https://api.example.com/price": {
+                "method": "GET",
+                "status": 200,
+                "body": json.dumps({"price": 100.50})
+            }
+        }
+    }
+    
+    # Create validators with mock web responses
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_web_response=mock_web_response
+    )
+    
+    # Use validators in transaction context
+    transaction_context = {"validators": [v.to_dict() for v in validators]}
+    
+    # Deploy and test contract
+    factory = get_contract_factory("PriceOracle")
+    contract = factory.deploy(transaction_context=transaction_context)
+    
+    # Contract's web requests will receive the mocked response
+    result = contract.update_price().transact(transaction_context=transaction_context)
+```
+
+#### Supported HTTP Methods
+
+Mock web responses support all HTTP methods including GET, POST, PUT, DELETE, PATCH, etc.:
+
+```python
+mock_web_response: MockedWebResponse = {
+    "nondet_web_request": {
+        # GET request
+        "https://api.example.com/users/123": {
+            "method": "GET",
+            "status": 200,
+            "body": '{"id": 123, "name": "Alice"}'
+        },
+        # POST request
+        "https://api.example.com/users": {
+            "method": "POST",
+            "status": 201,
+            "body": '{"id": 124, "name": "Bob", "created": true}'
+        },
+        # DELETE request
+        "https://api.example.com/users/123": {
+            "method": "DELETE",
+            "status": 204,
+            "body": ""
+        },
+        # PUT request
+        "https://api.example.com/users/123": {
+            "method": "PUT",
+            "status": 200,
+            "body": '{"id": 123, "name": "Alice Updated"}'
+        },
+        # Error response
+        "https://api.example.com/error": {
+            "method": "GET",
+            "status": 500,
+            "body": "Internal Server Error"
+        }
+    }
+}
+```
+
+#### How It Works
+
+When a contract calls any web method (`gl.nondet.web.get()`, `gl.nondet.web.post()`, etc.):
+1. The mock system checks if the URL exists in the mock configuration
+2. If found, it returns the mocked response with the specified status and body
+3. If not found, the actual web request would be made (or fail if network access is disabled)
+
+#### Complete Example: Twitter/X Username Storage
+
+Here's a real-world example showing how to mock Twitter/X API responses:
+
+```python
+# test_x_username_storage.py
+from gltest import get_contract_factory, get_validator_factory
+from gltest.assertions import tx_execution_succeeded
+from gltest.types import MockedWebResponse
+import json
+import urllib.parse
+
+def test_x_username_storage():
+    # Helper to build URL with query parameters
+    def get_username_url(username: str) -> str:
+        params = {"user.fields": "public_metrics,verified"}
+        return f"https://domain.com/api/twitter/users/by/username/{username}?{urllib.parse.urlencode(params)}"
+    
+    # Define mock responses for different usernames
+    mock_web_response: MockedWebResponse = {
+        "nondet_web_request": {
+            get_username_url("user_a"): {
+                "method": "GET",
+                "status": 200,
+                "body": json.dumps({"username": "user_a", "verified": True})
+            },
+            get_username_url("user_b"): {
+                "method": "GET",
+                "status": 200,
+                "body": json.dumps({"username": "user_b", "verified": False})
+            }
+        }
+    }
+    
+    # Create validators with mock web responses
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_web_response=mock_web_response
+    )
+    transaction_context = {"validators": [v.to_dict() for v in validators]}
+    
+    # Deploy and test contract
+    factory = get_contract_factory("XUsernameStorage")
+    contract = factory.deploy(transaction_context=transaction_context)
+    
+    # Test updating username - will use mocked response
+    tx_receipt = contract.update_username(args=["user_a"]).transact(
+        transaction_context=transaction_context
+    )
+    assert tx_execution_succeeded(tx_receipt)
+    
+    # Verify the username was stored
+    username = contract.get_username().call(transaction_context=transaction_context)
+    assert username == "user_a"
+```
+
+#### Combining Mock LLM and Web Responses
+
+You can combine both mock LLM responses and mock web responses in the same test:
+
+```python
+def test_combined_mocks():
+    # Define both mock types
+    mock_llm_response = {
+        "eq_principle_prompt_comparative": {
+            "values match": True
+        }
+    }
+    
+    mock_web_response: MockedWebResponse = {
+        "nondet_web_request": {
+            "https://api.example.com/data": {
+                "method": "GET",
+                "status": 200,
+                "body": '{"value": 42}'
+            }
+        }
+    }
+    
+    # Create validators with both mock types
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_llm_response=mock_llm_response,
+        mock_web_response=mock_web_response
+    )
+    
+    # Use in your tests...
+```
+
+#### Best Practices
+
+1. **URL Matching**: URLs must match exactly, including query parameters
+2. **Response Body**: Always provide the body as a string (use `json.dumps()` for JSON data)
+3. **Status Codes**: Use realistic HTTP status codes (200, 404, 500, etc.)
+4. **Method Matching**: Specify the correct HTTP method that your contract uses
+5. **Error Testing**: Mock error responses to test error handling paths
+6. **Deterministic Tests**: Mock web responses ensure tests don't depend on external services
+
+#### Notes
+
+- Mock web responses are only available when using mock validators
+- URL matching is exact - the full URL including query parameters must match
+- The method field should match the HTTP method used by the contract
+- Useful for testing contracts that interact with external APIs without network dependencies
+- All standard HTTP methods are supported (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
+
 ### Custom Transaction Context
 
 The GenLayer Testing Suite allows you to customize the transaction execution environment by providing a `transaction_context` parameter with custom validators and GenVM datetime settings.
@@ -978,8 +1243,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ## 💬 Support
 
 - [Documentation](https://docs.genlayer.com/api-references/genlayer-test)
-- [Discord Community](https://discord.gg/VpfmXEMN66)
-- [GitHub Issues](https://github.com/yeagerai/genlayer-testing-suite/issues)
+- [Discord Community](https://discord.gg/qjCU4AWnKE)
+- [GitHub Issues](https://github.com/genlayerlabs/genlayer-testing-suite/issues)
 - [Twitter](https://x.com/GenLayer)