test: added unit and integration testing for contract_client_v2

- updated .gitignore to ignore test related outputs
- added conftest.py to load variables for integration tests
- added .env.example to help with running tests

Author: JohnsonChin1009

.gitignore

@@ -21,3 +21,6 @@ __pycache__/
 
 # Intellij IDEA files
 .idea/
+tests/.env
+htmlcov/
+.coverage

tests/.env.example

@@ -0,0 +1,11 @@
+# General Variables
+WHITELISTED_WALLET_ADDRESS=<YOUR_WHITELISTED_WALLET_ADDRESS>
+WHITELISTED_WALLET_PRIVATE_KEY=<YOUR_WHITELISTED_PRIVATE_KEY>
+
+# Seller Agent Variables
+SELLER_ENTITY_ID=<YOUR_SELLER_ENTITY_ID>
+SELLER_AGENT_WALLET_ADDRESS=<YOUR_SELLER_AGENT_WALLET_ADDRESS>
+
+# Buyer Agent Variables
+BUYER_ENTITY_ID=<YOUR_BUYER_ENTITY_ID>
+BUYER_AGENT_WALLET_ADDRESS=<YOUR_BUYER_AGENT_WALLET_ADDRESS>

tests/conftest.py

@@ -0,0 +1,22 @@
+import os
+from pathlib import Path
+import pytest
+
+
+# Load .env file from tests directory if it exists
+def pytest_configure(config):
+    """Load environment variables from tests/.env before running tests"""
+    env_file = Path(__file__).parent / ".env"
+    if env_file.exists():
+        print(f"\n✅ Loading environment variables from {env_file}")
+        with open(env_file) as f:
+            for line in f:
+                line = line.strip()
+                # Skip comments and empty lines
+                if line and not line.startswith('#'):
+                    if '=' in line:
+                        key, value = line.split('=', 1)
+                        os.environ[key.strip()] = value.strip()
+    else:
+        print(f"\n⚠️  No .env file found at {env_file}")
+        print("Integration tests will be skipped. Create tests/.env from tests/.env.example")

tests/integration/test_integration_contract_client_v2.py

@@ -0,0 +1,57 @@
+import pytest
+import os
+from virtuals_acp.contract_clients.contract_client_v2 import ACPContractClientV2
+
+
+# Skip all integration tests if environment variables are not set
+pytestmark = pytest.mark.integration
+
+# Check if we have required environment variables for integration tests
+SKIP_INTEGRATION = not all([
+    os.getenv("WHITELISTED_WALLET_PRIVATE_KEY"),
+    os.getenv("SELLER_AGENT_WALLET_ADDRESS"),
+    os.getenv("SELLER_ENTITY_ID"),
+])
+
+
+@pytest.mark.skipif(SKIP_INTEGRATION, reason="Integration test environment variables not set")
+class TestIntegrationACPContractClientV2:
+    @pytest.fixture(scope="class")
+    def integration_client(self):
+        wallet_private_key = os.getenv("WHITELISTED_WALLET_PRIVATE_KEY")
+        agent_wallet_address = os.getenv("SELLER_AGENT_WALLET_ADDRESS")
+        entity_id = int(os.getenv("SELLER_ENTITY_ID", "0"))
+
+        try:
+            client = ACPContractClientV2(
+                agent_wallet_address=agent_wallet_address,
+                wallet_private_key=wallet_private_key,
+                entity_id=entity_id,
+            )
+            yield client
+        except Exception as e:
+            pytest.fail(f"Failed to initialize integration client: {e}")
+
+    class TestInitialization:
+        def test_should_connect_to_mainnet(self, integration_client):
+            assert integration_client is not None
+            assert integration_client.agent_wallet_address is not None
+
+        def test_should_have_valid_web3_connection(self, integration_client):
+            assert integration_client.w3 is not None
+            assert integration_client.w3.is_connected()
+
+        def test_should_fetch_manager_addresses(self, integration_client):
+            assert integration_client.job_manager_address is not None
+            assert integration_client.job_manager_address.startswith("0x")
+
+        def test_should_validate_session_key(self, integration_client):
+            # If client initialized, session key validation already passed
+            assert integration_client.account is not None
+            assert integration_client.entity_id is not None
+
+        def test_should_have_x402_instance(self, integration_client):
+            assert integration_client.x402 is not None
+
+        def test_should_have_alchemy_kit_instance(self, integration_client):
+            assert integration_client.alchemy_kit is not None