docs: updated readme for testing and sample file

test/.env.example

@@ -0,0 +1,9 @@
+# General Variables
+WHITELISTED_WALLET_ADDRESS=<WALLET_ADDRESS>
+WHITELISTED_WALLET_PRIVATE_KEY=0x<PRIVATE_KEY>
+# Seller Agent Variables
+SELLER_ENTITY_ID=<ENTITY_ID>
+SELLER_AGENT_WALLET_ADDRESS=<WALLET_ADDRESS>
+# Buyer Agent Variables
+BUYER_ENTITY_ID=<ENTITY_ID>
+BUYER_AGENT_WALLET_ADDRESS=<WALLET_ADDRESS>

test/README.md

@@ -1,128 +1,183 @@
-# Node SDK Test Suite
+# ACP Node SDK Automated Testing
 
-## Test Structure
+<details>
+<summary>📑 Table of Contents</summary>
 
-```
-test/
-├── unit/                      # Unit tests (mocked dependencies)
-│   └── acpContractClientV2.test.ts
-│
-├── integration/               # Integration tests (real network calls)
-│   └── acpContractClientV2.integration.test.ts
-│
-├── e2e/                       # End-to-end tests (coming soon)
-│
-├── env.ts                     # Environment variable loader
-└── .env.sample                # Environment variable template
-```
+- [Introduction](#introduction)
+  - [Purpose](#purpose)
+- [Running Tests](#running-tests)
+  - [All Tests](#all-tests)
+  - [Unit & Component Tests Only](#unit-&-components-tests-only)
+  - [Specific Test Files](#specific-test-files)
+  - [Generating Coverage Report](#generate-coverage-report)
+- [How to Write Tests](#how-to-write-tests)
+  - [Unit Tests](#unit-tests)
+  - [Integration Tests](#integration-tests)
+  - [E2E Testing](#e2e-testing-coming-soon)
 
-## Running Tests
+</details>
 
-```bash
-# Run all tests
-npm test
+## Introduction
 
-# Run only unit tests
-npm test -- test/unit
+### Purpose
 
-# Run only integration tests
-npm test -- test/integration
+This test suite validates the ACP Node SDK's functionality across three levels:
 
-# Run with coverage
-npm run test:coverage
+- **Unit Tests** - Verify individual functions and classes in isolation
+- **Component Tests** - Test interactions between multiple units
+- **Integration Tests** - Validate end-to-end functionality with real blockchain/API calls
 
-# Run specific test file
-npm test -- acpContractClientV2
+The test suite ensures code quality, prevents regressions, and provides confidence when shipping new features.
 
-# Run in watch mode
-npm run test:watch
-```
+## Running Tests
 
-## Setup
+Below are some commands to get you started to run the test suites.
 
-### 1. Install Dependencies
+### All Tests
 
-```bash
-npm install
 ```
-
-### 2. Configure Environment Variables (for integration tests)
-
-```bash
-# Copy the sample file
-cp test/.env.sample test/.env
-
-# Edit test/.env with your testnet credentials
+npm test
 ```
 
-Required variables:
+### Unit & Component Tests Only
 
-- `WHITELISTED_WALLET_PRIVATE_KEY` - Private key with testnet ETH
-- `SELLER_ENTITY_ID` - Alchemy session key entity ID
-- `SELLER_AGENT_WALLET_ADDRESS` - Agent wallet address
+```
+npm run test:unit
+```
 
-See `test/.env.sample` for full configuration.
+### Specific Test Files
 
-## Test Coverage
+```
+npm test -- test/unit/acpJob.test.ts
+```
 
-To see detailed coverage report:
+### Generate Coverage Report
 
-```bash
+```
 npm run test:coverage
 ```
 
-**Current Coverage** (AcpContractClientV2):
+## How to Write Tests
 
-- 21 tests (19 unit + 2 integration)
-- 95.45% statement coverage
-- 83.33% branch coverage
-- 100% function coverage
+### Unit Tests
 
-## Writing Tests
+Unit tests should be **isolated, fast, and deterministic**. These tests don't involve any on-chain activity or external dependencies.
 
-### Unit Test Example
+**Location**: `test/unit/`
 
-```typescript
-import AcpContractClientV2 from "../../src/contractClients/acpContractClientV2";
+**General Guidelines:**
 
-describe("MyClass Unit Tests", () => {
-  let client: AcpContractClientV2;
+- No network calls
+- No blockchain interactions
+- External dependencies are mocked using `jest.mock()`
+- No `.env` needed
 
-  beforeEach(() => {
-    // Mock dependencies - no network calls
-    client = new AcpContractClientV2(/* ... */);
-    client["_sessionKeyClient"] = mockClient;
-  });
+**Example Structure:**
 
-  it("should do something", () => {
-    const result = client.someMethod();
-    expect(result).toBe(expected);
+```typescript
+// acpJob.test.ts
+import { AcpJob } from "../../src/acpJob";
+import { AcpError } from "../../src/acpError";
+
+describe("AcpJob Unit Testing", () => {
+  // ^^^ Tests are grouped by files
+  describe("Job Creation", () => {
+    // ^^^ Group similar functions together for better organization
+    it("should create a job with valid parameters", () => {
+      // ^^^ Test cases should be descriptive
+      const job = new AcpJob(/* ... */);
+      expect(job).toBeDefined();
+      expect(job.id).toBe(1);
+    });
+
+    it("should throw error for invalid parameters", () => {
+      expect(() => new AcpJob(/* invalid params */)).toThrow(AcpError);
+    });
   });
 });
+
+// Mocking Examples
+const mockData = /* some data */;
+
+// Mock Fetch for API Calls
+global.fetch = jest.fn().mockResolvedValue({
+    json: async() => ({data: mockData}),
+})
+
+// Mocking contract client
+const mockClient = {
+    readContract: jest.fn().mockResolvedValue(mockValue),
+};
+```
+
+What to Test:
+
+- Input Validation
+- Error Handling
+- Edge Cases
+- Business Logic
+- State Transitions
+- Helper Functions
+
+### Integration Tests
+
+Integration Tests should verify the SDK works correct withe external dependencies/services (blockchain, APIs).
+
+**Location**: `test/integration/`
+
+**General Guidelines:**
+
+- Require `.env` to be defined
+- Makes real network & blockchain calls
+- Able to test partial end-to-end functionality
+
+**Environment Setup**
+
+1. Copy .env.sample to .env:
+
+```bash
+cp test/.env.sample test/.env
+```
+
+2. Populate environment variables:
+
+```bash
+// .env
+# General Variables
+WHITELISTED_WALLET_ADDRESS=<WALLET_ADDRESS>
+WHITELISTED_WALLET_PRIVATE_KEY=0x<PRIVATE_KEY>
+# Seller Agent Variables
+SELLER_ENTITY_ID=<ENTITY_ID>
+SELLER_AGENT_WALLET_ADDRESS=<WALLET_ADDRESS>
+# Buyer Agent Variables
+BUYER_ENTITY_ID=<ENTITY_ID>
+BUYER_AGENT_WALLET_ADDRESS=<WALLET_ADDRESS>
 ```
 
-### Integration Test Example
+**Example Structure:**
 
 ```typescript
-import AcpContractClientV2 from "../../src/contractClients/acpContractClientV2";
-import {
-  WHITELISTED_WALLET_PRIVATE_KEY,
-  SELLER_ENTITY_ID,
-  SELLER_AGENT_WALLET_ADDRESS,
-} from "../env";
-
-describe("MyClass Integration Tests", () => {
-  jest.setTimeout(10000);
-  let client: AcpContractClientV2;
-
-  it("should work with real network", async () => {
-    client = await AcpContractClientV2.build(
+// acpContractClientV2.integration.test.ts
+import { testBaseAcpConfigV2 } from "../testConfigs";
+import { AcpContractClientV2 } from "../../src/contractClient/acpContractClientV2";
+
+describe("AcpContractClientV2 Integration Testing", () => {
+  it("should initialize client successfully", async () => {
+    const client = await AcpContractClientV2.build(
       WHITELISTED_WALLET_PRIVATE_KEY,
       SELLER_ENTITY_ID,
       SELLER_AGENT_WALLET_ADDRESS,
+      testBaseAcpConfigV2, // <- Uses test config with proxy RPC
     );
 
     expect(client).toBeDefined();
   });
 });
 ```
+
+**Important Notes:**
+
+- All integration tests should only use `testConfigs.ts` to avoid rate limits.
+- Ensure that test wallets are funded with corresponding environment (e.g. testnet/mainnet)
+
+### E2E Testing (Coming Soon)