From 5d59821c4e2073e91db3c5cf912a84759c2e49d9 Mon Sep 17 00:00:00 2001 From: johnsonchin Date: Tue, 27 Jan 2026 14:57:01 +0800 Subject: [PATCH] docs: updated readme for testing and sample file --- test/.env.example | 9 ++ test/.env.sample | 4 - test/README.md | 221 +++++++++++++++++++++++++++++----------------- 3 files changed, 147 insertions(+), 87 deletions(-) create mode 100644 test/.env.example delete mode 100644 test/.env.sample diff --git a/test/.env.example b/test/.env.example new file mode 100644 index 0000000..9da2fd4 --- /dev/null +++ b/test/.env.example @@ -0,0 +1,9 @@ +# General Variables +WHITELISTED_WALLET_ADDRESS= +WHITELISTED_WALLET_PRIVATE_KEY=0x +# Seller Agent Variables +SELLER_ENTITY_ID= +SELLER_AGENT_WALLET_ADDRESS= +# Buyer Agent Variables +BUYER_ENTITY_ID= +BUYER_AGENT_WALLET_ADDRESS= diff --git a/test/.env.sample b/test/.env.sample deleted file mode 100644 index 64112e6..0000000 --- a/test/.env.sample +++ /dev/null @@ -1,4 +0,0 @@ -WHITELISTED_WALLET_PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef -SELLER_ENTITY_ID=123 -SELLER_AGENT_WALLET_ADDRESS=0x1234567890123456789012345678901234567890 - diff --git a/test/README.md b/test/README.md index df07dc2..ae19a62 100644 --- a/test/README.md +++ b/test/README.md @@ -1,128 +1,183 @@ -# Node SDK Test Suite +# ACP Node SDK Automated Testing -## Test Structure +
+📑 Table of Contents -``` -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 +
-```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= +WHITELISTED_WALLET_PRIVATE_KEY=0x +# Seller Agent Variables +SELLER_ENTITY_ID= +SELLER_AGENT_WALLET_ADDRESS= +# Buyer Agent Variables +BUYER_ENTITY_ID= +BUYER_AGENT_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)